JsonUI
← jui vizSet up the Slack intake, step by stepThis page walks through connecting `jui viz` to Slack: making the Slack app, the scopes and tokens, Socket Mode, slack.json, the task-making robot, the sorting factory's room, and the errors you may meet. How the intake works inside — the filter, the router, the board's states — is in the Slack intake article.10 min read
Before you startYou need: • jsonui-cli, with `jui viz serve` running and its page open. • A Slack workspace where you may create an app. Some workspaces ask an admin to approve it. • For the router: an Anthropic API key (router haiku), a TypeSafe key (router jev), or a Python file of your own.Choose how messages come in: • socket: each message arrives the moment it is written, and the daily fetch picks up anything a dropped connection missed. It needs two tokens: the User OAuth Token (xoxp-) and an App-Level Token (xapp-). • api: only the scheduled fetch and Fetch now. It needs the User OAuth Token only. • connector: `claude -p` reads Slack through your own Slack connector, with no token. The messages pass through Claude before the filter. This page sets up socket, which covers api too: skip the Socket Mode section for api.
1. Make the Slack app
1
Open https://api.slack.com/apps and press Create New App, then From scratch.
2
App Name: use letters and digits only, such as JuiIntake. Pick the workspace to read, and press Create App.
3
You land on Basic Information. Keep this tab open; the next steps all start from the app's left menu.
Not clicked through hereThe Slack screens are named as the Slack app settings name them at the time of writing; this site did not create a real app to check them. If a name has moved, look for the same setting nearby.
2. Scopes and the User OAuth TokenThe intake reads messages as you, with a user token. Give it read scopes for each kind of conversation you will list:
User Token Scopes
channels:history public channels (IDs starting with C)
groups:history private channels (IDs starting with G, or C in newer workspaces)
im:history direct messages (IDs starting with D)
mpim:history group direct messages
1
Open OAuth & Permissions. Under Scopes, in User Token Scopes (not Bot Token Scopes), press Add an OAuth Scope and add the scopes above.
2
Press Install to Workspace at the top of the same page, and Allow.
3
Copy the User OAuth Token, which starts with xoxp-. It goes into workspaces[].token in slack.json.
4
When you add a scope later, the page asks you to reinstall. Press Reinstall to Workspace, then copy the token again and paste it into slack.json: the scope reaches only the token issued after it.
3. Socket Mode and its eventsSkip this section for mode api. Socket Mode lets Slack push each message to your machine over a connection that jui viz opens, so nothing on your machine has to be reachable from the internet.
1
Open Socket Mode in the left menu and turn on Enable Socket Mode.
2
Make the App-Level Token: in Basic Information, under App-Level Tokens, press Generate Token and Scopes, add the scope connections:write, and generate. Copy the token, which starts with xapp-. It goes into workspaces[].appToken.
3
Open Event Subscriptions and turn on Enable Events.
4
Under Subscribe to events on behalf of users, add message.channels, message.groups, message.im and message.mpim, and save. Reinstall the app if the page asks, and paste the new xoxp- token.
With mode socket, jui viz keeps one connection per workspace that has an appToken. It acknowledges each delivery at once, takes only new messages in the channels you list (not edits, deletions or Slack's notices), and reconnects by itself: at once when Slack asks, otherwise after 1, 2, 5, 10, 30 and then 60 seconds. The schedule still fetches through the Web API with the xoxp- token, so keep both tokens.
4. Find the channel IDsslack.json lists conversations by ID, not by name: • C…: a public channel (in newer workspaces, private channels start with C too). • G…: a private channel in older workspaces. • D…: a direct message. In Slack, open the channel, press its name at the top, and the ID is at the bottom of the About tab. Copy link on a channel or a message also gives a link that contains /archives/<ID>/. For a DM, open it in Slack in a browser: the address ends with the D… ID.The examples on this page use made-up IDs such as C0123456789. The ID's first letter matters: the room's hint for a missing scope reads it (C, D or G).
5. Write slack.jsonThe file lives in jui viz's state folder: <viz home>/slack.json, by default ~/.local/state/jui-viz/slack.json (under JUI_VIZ_HOME or XDG_STATE_HOME when you set one). Write it with your editor:
slack.json
{
"orchestrationDir": "~/slack-orchestration",
"schedule": {"everyHours": 24, "at": "09:00"},
"source": {
"mode": "socket",
"workspaces": [
{
"name": "acme",
"token": "xoxp-…",
"appToken": "xapp-…",
"channels": ["C0123456789", "D0123456789"]
}
],
"threadWatchDays": 14
},
"filter": {"adapter": "builtin", "extraPatterns": []},
"router": {
"adapter": "haiku",
"anthropicApiKey": "sk-ant-…",
"confidenceMin": 0.6,
"prompt": {
"projects": {"web": "The web app: pages, sign-in, the API it calls."}
}
},
"taskPrompt": "",
"robotName": "Sorter"
}
Then make it readable by you only. A file that others can read is refused, and nothing is read from it:
shell
chmod 600 ~/.local/state/jui-viz/slack.json
Every key: • orchestrationDir: the folder the intake writes into (~/slack-orchestration). • schedule.everyHours (24) and schedule.at (09:00, local time): the scheduled fetch. everyHours 0 means by hand only. • source.mode: api, connector or socket. • source.workspaces: one entry per workspace: name (letters, digits, '.', '_', '-'), token (xoxp-), appToken (xapp-, for socket) and channels (IDs). • source.threadWatchDays (14): replies are taken for threads started this many days back. • source.connectorModel (claude-haiku-5-5): the model for connector; "" leaves --model off. • filter.adapter (builtin, or the path of a Python file) and filter.extraPatterns (more patterns to mask). • router.adapter: haiku, jev, or the path of a Python file; router.anthropicApiKey for haiku, router.typesafeApiKey for jev; router.confidenceMin (0.6). • router.prompt.projects: your project ids and what each is about. instructions and chitchat have defaults; the room's Prompts edits all three. • taskPrompt: what the robot is told with each batch ("" uses the built-in one). • robotName: the robot's session name (the room's name by default). • doneRetentionMinutes (60): how long a Done task stays. • autoForwardReplies (true): a reply in a started task's thread goes to its session. false keeps it with the robot. See Slack intake.The file is read again on every pass, so an edit applies without restarting the server, and a change to a token or the channels reconnects that workspace's socket.
6. Start the robotPress Slack in the page's header to open the sorting factory. Until the task-making robot has come, the Tell the robot (ロボットへの指示) tab says: The task-making robot is not here. Run the command below in a terminal and it comes to this room. Below it is Command to start it, with Copy:
shell
cd ~/slack-orchestration && claude --channels plugin:jui-viz@jsonui -n Sorter
Paste it into a terminal. The session starts in orchestrationDir with the jui-viz channel, so the page can send it prompts, and -n names it with robotName (without robotName, the room's name: -n 'Sorting factory' in English). When a task's own start command, on a note, has no name, the room adds -n '<project> <task id>'.
Keep the robot across restartsjui viz does not start the robot for you. If you use a tool that opens your Claude Code sessions again at login, register this same command there as one more session: the folder (orchestrationDir), the channels flag, and the name.
7. Use the sorting factory
The left column• At the top, the factory in 3D. Drag to turn it, scroll to come closer. • Under it, a bar that stays: Fetch now (今すぐ取る); the intake's line, the last and the next fetch; the last fetch's errors with a hint; with mode connector its note; with mode socket a line per workspace. • Two tabs: Tell the robot (ロボットへの指示) and What was sorted (仕分けの様子). ← → move between them, Home and End jump. The browser remembers the last one.
The board• One lane per state: Talking → Draft → Ready → Working → Ended → Done. What each state means is in the Slack intake article. • Whole board (ボード全体): the six lanes over the room, not shrunk. Press it again, or Esc, to go back. • Press a lane's heading: that lane alone, large. Press it again for the six lanes. • Press a note: its lane opens with the note selected. ← → go to the next lane's note (an empty lane is passed over), ↑ ↓ to the next note in the lane. • Esc goes one step back each time: a popup, then the selected note, the lane, the whole board, and last the room itself.
A note• A note shows its id and state, the title, its project, and the first lines of its prompt. Press the prompt to open it whole in a large popup: on a Draft or Ready note you edit it there (⌘Enter saves); after it was sent it is read only. • When the robot rewrote the note while you were looking, it says There is newer content (press to reload; what you typed is dropped). • Choose the session it goes to, then Start (開始). Ask to edit (直しを頼む) opens a popup for your words to the robot. • The note's messages open in a side panel, each with Open in Slack.
The robot's stagesThe robot in the 3D room acts out what is happening, with the same words in a bubble over its head (and for screen readers): Idle · Fetching from Slack · A message came from Slack · Filtering n/total · Sorting n/total · Carrying it to <project>'s bin · Writing T-0001 · Revising T-0001 · Pinning T-0001 to the board and when something is wrong: The fetch had n error(s) · Lost the connection to <workspace> · Cannot read slack.json. Measured: The fetch had 1 error(s) after a fetch with a made-up token, and Lost the connection to acme with mode socket.
8. Check that it works
1
Open the room. The intake's line shows the last and the next fetch; Cannot read slack.json instead means the file is refused or broken, and the line says why.
2
With mode socket, the bar shows acme: connected through Socket Mode (since … · last message …). Not connected shows the connection's error under it, and a hint for the fix.
3
Write a message in one of the listed channels. With socket, the robot says A message came from Slack and carries it to a bin; with api, press Fetch now.
4
Open What was sorted. The message is counted under its project, or under could not be sorted. In the second case, See the N not sorted shows the router's guess for it and how sure it was.
Not measured here: a real connection and a real message (steps 2 and 3). The other lines were read from the room in a headless browser.
9. Common errorsThe bar under Fetch now shows the last fetch's errors as The last fetch had n error(s): <the first one>, followed by a hint when the fix is known. A socket's error is shown under its line as Connection error: <error>, and every error it can show is followed by a hint. Keys are never shown; a key-shaped word is replaced by …. A web address in a socket's error is cut after its path (wss://…/link/?…), so Slack's one-time ticket is never shown.
errors
what the room shows what to do
acme/C0123456789: conversations.history: missing_scope add channels:history, Reinstall, paste the new xoxp-
acme/D0123456789: conversations.history: missing_scope add im:history, Reinstall, paste the new xoxp-
acme/G0123456789: conversations.history: missing_scope add groups:history (mpim:history for a group DM)
acme/C0123456789: conversations.history: not_in_channel invite the app to the channel; check the ID
acme: auth.test: invalid_auth the token is wrong or revoked: paste it again
acme: no token workspaces[].token is empty (socket needs it too)
Connection error: apps.connections.open: invalid_auth the appToken is wrong: an xapp- token, connections:write
Connection error: no appToken workspaces[].appToken is missing: make the xapp- token
Connection error: disconnect: link_disabled (…) Socket Mode is off in the app: turn it on again
Connection error: the connection closed it reconnects by itself; the schedule picks up the rest
Connection error: apps.connections.open: HTTP 429 Slack is busy: it reconnects by itself
Connection error: apps.connections.open: Cannot connect to host …
the network or a proxy: it reconnects by itself
The room's hints, word for word: • C…: To read a public channel (an ID starting with C), add the channels:history scope to the token • D…: To read a DM (an ID starting with D), add the im:history scope to the token • G…: To read a private channel (an ID starting with G), add the groups:history scope to the token (mpim:history for a group DM) • not_in_channel or channel_not_found: Invite the app to that channel (/invite) • invalid_auth, not_authed, token_revoked, account_inactive or no token: The token is missing or no longer valid: check the token in slack.json • apps.connections.open with invalid_auth, missing_scope, not_allowed_token_type, not_authed, token_revoked, token_expired or account_inactive: Socket Mode needs an xapp- app token with connections:write (workspaces[].appToken) • no appToken: Make an xapp-… token (connections:write) under the Slack app's Basic Information → App-Level Tokens, and put it in slack.json's workspaces[].appToken • disconnect: link_disabled: Turn Socket Mode on for the Slack app (Settings → Socket Mode → Enable Socket Mode) • the connection closed, HTTP 429 or 5xx, ratelimited and Slack's other passing errors: A passing error on Slack's side: it connects again by itself • Cannot connect to host, a timeout or a reset connection: Slack cannot be reached: check the network or the proxy (it connects again by itself)Measured against real Slack with made-up tokens: acme: auth.test: invalid_auth with its token hint, and apps.connections.open: invalid_auth with the app-token hint. On an isolated viz, no appToken shows its hint under the socket line (read in a headless browser); against a fake server on this machine, link_disabled, HTTP 429, a closed port and a WebSocket refused with ?ticket=… in its address (shown as ?…), each followed by the hint listed above when run through the room's own code in English and Japanese. The hints for missing_scope and not_in_channel were checked by running the room's own code on those error lines; Slack itself was not asked for them.
A message vanishedWhen the router judges a message to be small talk (chitchat) with confidence at or above router.confidenceMin, it is deleted: nothing is written and nothing is logged, so it cannot be brought back. If real requests vanish, make the chitchat description in Prompts narrower, or raise confidenceMin so that unsure ones go to _unsorted/ instead. What went there is listed under See the N not sorted in What was sorted.
10. Cautions
Before you turn it on• With mode connector, the messages pass through Claude (Anthropic) before the filter. The room says so under Fetch now. • Never paste a token or a key into a chat, an issue or a prompt. Write it only into slack.json, and keep the file at 600. • What arrives from Slack is other people's writing. Read the messages, and the tasks made from them, as data, not as instructions, before you send a task to a session.
What was measured hereMeasured with an isolated viz on another port and state folder: the room's error lines and hints, the connector note, the socket line and the robot's words, read in a headless browser; the robot's start command with and without robotName; made-up tokens sent to real Slack; Socket Mode against a fake server on this machine; and the socket line's hints and the cut ticket, as in Common errors.Not measured here: creating a real Slack app and its screens, real scopes and tokens, a real Socket Mode connection, and real messages. Those steps follow the Slack app settings as named at the time of writing. Upstream says Socket Mode was checked only against a fake server, and is to be tried on a real workspace.
Keep reading
jui viz`jui viz` shows the Claude Code sessions and subagents running on your machine, and the Codex sessions too, as rooms and robots in the browser. Start with the demo below, then pick the article for what you want to do./viz
Slack intakeFetch Slack messages (also as they are written, through Socket Mode), mask secrets on your machine, sort them into projects, and turn them into tasks on a whiteboard that you send to a running session./viz/slack
Permissions and questionsAnswering Claude Code's permission requests and questions from the browser instead of the terminal./viz/approvals