← jui vizTurn Slack messages into tasks with jui viz`jui viz` can fetch messages from Slack channels, mask secrets on your machine, sort each message into one of your projects, and have a Claude Code session turn them into tasks. The tasks are notes on a whiteboard in a room of their own, the sorting factory, and you send each one to a running session. It can also take each message the moment it is written, through Slack's Socket Mode. Nothing of this runs until you write slack.json. For the setup itself, step by step, see Set up the Slack intake.8 min read
How it worksThe intake runs in four steps inside the `jui viz` server:
• Fetch: the new messages of the channels you list, once a day by default or when you press Fetch now (今すぐ取る). With mode socket each message also arrives as it is written.
• Filter: on your machine, Slack's own marks are written out, attached files are dropped and secrets are masked.
• Route: a router you choose decides which project each filtered message is about, or that it is small talk.
• Make tasks: a Claude Code session started in the intake's folder, the task-making robot, groups the sorted messages into tasks.Every step writes plain files under one folder, orchestrationDir (by default ~/slack-orchestration). Each file and folder is made readable by you only (0600 and 0700).The header has a Slack button whenever the page is connected to a running server, with or without slack.json. Without it, the room says No slack.json yet (nothing is fetched) (slack.json がまだありません(取得は止まっています)).
folders
~/slack-orchestration/ orchestrationDir (the default) inbox/ raw messages as fetched; deleted once placed projects/<project id>/ filtered messages sorted to a project _unsorted/ low confidence, or a choice not in the list tasks/<task id>.json the robot's tasks (T-0001.json, ...) .state/ cursor, threads, routes, status, board .state/context/<task id>.md an excerpt of a started task's sessionWhat leaves your machine
Know where each message goes• Fetch with mode api talks to Slack's Web API with each workspace's token. No language model is used.
• Mode socket keeps a connection to Slack with the app token and takes each message as it is written; the schedule still reads the Web API with the token. No language model is used here either.
• Fetch with mode connector runs `claude -p` with your Slack connector. The messages then pass through Claude (Anthropic) before the filter. The room says so under Fetch now: Note: With mode connector, the messages pass through Claude (Anthropic) before the filter (measured).
• The router sees the filtered message only: its text, user, workspace and channel. haiku sends it to the Anthropic API, jev to TypeSafe's System One API, and a path adapter to your own Python file.
• The task-making robot is a Claude Code session, so the filtered messages it reads go to Claude as well.
• The robot may also read an excerpt of the talk in a started task's session, so that goes to Claude too. A reply forwarded to a session goes to that session's model. See Replies and the session's talk.
No mode can read a workspace you have no access to. A channel the token's app or your connector cannot read gives an error, and the other channels are still fetched. The room shows the last fetch's errors with a hint for the fix; see Set up the Slack intake.Write slack.jsonThe intake reads slack.json in jui viz's state folder: ~/.local/state/jui-viz/slack.json by default, or under JUI_VIZ_HOME or XDG_STATE_HOME when you set one. No command writes it for you, except the room's Prompts (プロンプトの設定), which keeps your other keys.It holds tokens and keys, so it must be readable by you only. A file readable by anyone else is refused, and nothing is read from it. Measured with mode 0644:The keys and their defaults:
• orchestrationDir: ~/slack-orchestration.
• schedule.everyHours: 24, and schedule.at: 09:00 (local time). everyHours 0 means by hand only.
• source.mode: api, connector or socket. source.workspaces: a list of {name, token, appToken, channels}; appToken is for socket; channels are channel ids. Names and ids take letters, digits, '.', '_' and '-' only.
• source.threadWatchDays: 14. source.connectorModel: claude-haiku-5-5 ("" leaves --model off). source.claudeCommand: the claude to run for connector, by default the one on PATH.
• filter.adapter: builtin or the path of a Python file. filter.extraPatterns: more patterns to mask.
• router.adapter: haiku, jev or the path of a Python file. router.anthropicApiKey or router.typesafeApiKey for the first two. router.confidenceMin: 0.6.
• router.prompt: instructions, projects (id: description) and chitchat. The ids chitchat, _unsorted, inbox and tasks are reserved.
• taskPrompt: what the robot is told with each batch of messages ("" uses the built-in one).
• doneRetentionMinutes: 60.
• robotName: the robot's session name in its start command (by default the room's name).
• autoForwardReplies: true. false keeps every reply with the robot.The file is read again on every pass, so an edit applies without restarting the server.
slack.json
{ "orchestrationDir": "~/slack-orchestration", "schedule": {"everyHours": 24, "at": "09:00"}, "source": { "mode": "api", "workspaces": [ {"name": "acme", "token": "xoxp-…", "channels": ["C0123456789"]} ] }, "filter": {"adapter": "builtin", "extraPatterns": [{"name": "ticket", "pattern": "TCK-[0-9]+"}]}, "router": { "adapter": "haiku", "anthropicApiKey": "sk-ant-…", "prompt": { "instructions": "Decide which project this Slack message is about.", "projects": {"web": "The web app: pages, sign-in, the API it calls."}, "chitchat": "Small talk, greetings, thanks and anything that asks for no work." } }}status
<state folder>/slack.json is readable by others (mode 0644); chmod 600 itshell
chmod 600 ~/.local/state/jui-viz/slack.jsonWhen messages are fetched• The schedule runs every everyHours hours, counted from schedule.at. A run missed while the server was down runs as soon as it is back.
• Fetch now (今すぐ取る) in the room fetches at once. It also retries the messages that failed earlier.
• A channel fetched for the first time starts from the last everyHours hours (24 when the schedule is by hand only).
• A reply to a thread is taken too, even when the thread started before the last fetch, for threads started in the last threadWatchDays days.
• Slack's own notices (joins, leaves, topic and name changes, pins) are skipped.
• With mode socket, Slack pushes each new message in a listed channel, DM or group, and it takes the same road at once. Edits and deletions are not taken. The schedule and Fetch now still read the Web API, to pick up what a dropped connection missed, and a message taken one way is not taken again the other way.
• A channel's position moves only after its messages are written, so a failed fetch takes the same messages again next time.
• A scheduled fetch that fails (an error from Slack or the connector, or the run itself failing) is tried again after 1, 2, 4, 8 and 16 minutes, then at the schedule's times; a fetch without an error ends the steps. Fetch now is not retried this way. Read by calling the retry bookkeeping of the shipped intake, with no Slack contacted.Measured with the shipped intake and a fake Socket Mode server on this machine: the message was acknowledged at once, an edit of it was acknowledged and not taken, the message went to projects/web/, and a Web API fetch returning the same message afterwards took 0.
The filter: files dropped, secrets maskedThe built-in filter runs on your machine and sends nothing anywhere. It drops the message's attached files and masks each match as [REDACTED:<kind>]. The kinds are private-key, slack-token, slack-app-token, slack-webhook, aws-access-key, aws-secret-key, github-token, anthropic-key, openai-key, google-api-key, jwt, password, email and phone. A pattern in filter.extraPatterns is a string, or {name, pattern} to name its kind.Before any filter, Slack's own way of writing is turned back into the text a person reads: & < > become & < >, <@U…> becomes @U…, <#C…|name> becomes #name, and <https://…|label> becomes label (https://…). The filter, the router and the robot all read this form. Measured with a message pushed through the fake Socket Mode server:Measured with a message placed in inbox/ by hand and the extra pattern from the example above:When a filter fails — an error, a timeout, a wrong shape, a missing file — the message stays in inbox/ and nothing is routed, so nothing unfiltered leaves your machine. It is tried again when the filter settings or the file change, or on Fetch now. Measured: with a missing adapter file the message stayed in inbox/ with stage filter in the status, and was routed once the setting was put back.
text
as Slack sent it: The login page fails & returns <500> for <@U012ABC>, see <https://example.com/log|the log> in <#C0123456789|web-bugs> in projects/web/: The login page fails & returns <500> for @U012ABC, see the log (https://example.com/log) in #web-bugsbefore and after
inbox/1793500000.000100-acme-C012.json (as fetched) "text": "The login page fails for ann@example.com, password: hunter22 and see TCK-1234", "files": [{"name": "shot.png"}] projects/web/1793500000.000100-acme-C012.json (filtered and routed) "text": "The login page fails for [REDACTED:email], [REDACTED:password] and see [REDACTED:ticket]", "removedFiles": 1, "redactions": 3, "router": {"adapter": "path", "choice": "web", "confidence": 0.9}What the filter does not promiseIt masks shapes, not meaning. A customer's name, an address, or a secret written in a shape it does not know reaches the router as written. Add patterns of your own, or write your own filter.
Your own filter is a Python file, given by its absolute path (or ~) in filter.adapter. It runs in a separate `python -I` process and must answer within 60 seconds:my_filter.py
def filter_message(record: dict) -> tuple[dict, dict]: # record: one inbox file {workspace, channel, ts, permalink, message, via} text = record["message"].get("text", "") ... return ({"text": text, "user": "U1", "permalink": record.get("permalink", "")}, {"removedFiles": 0, "redactions": 0})The router: which projectThe router's choices are your project ids and chitchat. Where a message goes:
• chitchat with confidence at or above router.confidenceMin: deleted. Nothing is written and nothing is logged.
• a project id at or above confidenceMin: projects/<id>/.
• anything else (low confidence, or an answer that is not in the list): _unsorted/. The room lists them, with the router's guess (see The sorting factory).
• a reply in a thread that already went to a project or to _unsorted/: the same place, without asking the router.Measured with a path adapter that answers by keyword:When the router fails, the message stays in inbox/ and is tried again after 10 minutes, or on Fetch now. Your own router is a Python file in router.adapter, run the same way as a filter:
routing
message router said went to"The login page fails …" web, 0.9 projects/web/"also on Safari …" (a reply to it) (not asked) projects/web/ router.adapter "thread""maybe the header is off" web, 0.3 _unsorted/ under confidenceMin 0.6"thanks all!" chitchat, 0.95 deleted, nothing written"a question for the infra team" somewhere-else, 0.9 _unsorted/ not a project idmy_router.py
def route(message: dict, prompt: dict) -> dict: # message: {workspace, channel, user, ts, text} after the filter # prompt: router.prompt from slack.json return {"choice": "web", "confidence": 0.9}The sorting factoryPress Slack in the header. The sorting factory (仕分け工場) opens over the whole page. When tasks wait on you — a draft to look at, one ready to start, or one whose work ended — the button shows their number.• Left, at the top: the factory in 3D. Messages ride a belt into one bin per project, and the robot shows what the intake is doing.
• Under it: Fetch now, the intake's line (the last and the next fetch, or by hand only), the last fetch's errors with a hint, the connector's note, and with mode socket one line per workspace.
• Two tabs: Tell the robot (ロボットへの指示), a box that sends the task-making robot a prompt; and What was sorted (仕分けの様子): how many arrived, how many the robot has not been told of, how many could not be sorted, and the latest ones.
• Under those, when anything could not be sorted: See the N not sorted (仕分けられなかった N 件を見る), closed at first, and still open when a new arrival redraws the tab. It lists them newest first, up to 40. Each row has the channel and the sender, the router's guess and how sure it was (Guess: appA (42% sure, not enough)), or, for a reply, Followed its thread's first message with that message's guess, and the start of the text. They stay in _unsorted/: the robot is not told of them, and no task is made from them. Before 2.5.49 the room showed only their number.
• Right: the task board, a whiteboard with one note per task.
How to use each part is in Set up the Slack intake.Prompts (プロンプトの設定) edits the router's instructions, the projects, the chitchat definition and the task prompt. Saving writes only router.prompt and taskPrompt into slack.json; the other keys stay as you wrote them, and the file stays 0600. A reserved id is refused. Measured:
Prompts
not a project id: 'inbox'The task-making robotThe robot is a Claude Code session whose folder is orchestrationDir. Start it with the jui-viz channel, so that the page can send it prompts. The room shows this command, and you can copy it:The command names the session with -n: robotName from slack.json, or by default the room's name in the page's language (Sorting factory in English, 仕分け工場 in Japanese). Measured: -n Sorter with robotName Sorter, -n 'Sorting factory' without it. When your viz keeps its files somewhere other than the default, the command also carries JUI_VIZ_HOME=<that folder>, so the session reaches this viz.• The robot sits in the factory, not in a project's room.
• When sorted messages come that no task names yet, and the robot is idle, the server tells it: the new files, the open tasks, the sessions a task can go to, and the next id (T-0001, T-0002, …). It is told at most 40 files at a time, and no sooner than 20 seconds after the last time.
• The robot writes one file per task in tasks/. A thread always stays in one task, and related messages may join it. Only a Talking, Draft or Ready task takes more messages. A message about a task already Working, Ended or Done gets a new task that points at the old one. A reply in a started task's own thread goes to its session instead; see Replies and the session's talk.
shell
cd ~/slack-orchestration && claude --channels plugin:jui-viz@jsonui -n 'Sorting factory'Slack messages are other people's wordsThe robot reads what other people wrote in Slack, and a task's prompt is built from it. Read a task as data, not as an instruction, before you send it on.
The task boardThe whiteboard has one lane per state: Talking (やり取り中) → Draft (下書き) → Ready (開始待ち) → Working (作業中) → Ended (作業終了) → Done (完了).• Talking: the robot judged the exchange not settled yet. It, or you, raises it to Draft.
• On a Draft or Ready note you edit the title and the prompt in place, and choose the session it goes to. Save (保存) keeps it. A prompt you changed is marked, and the robot leaves it; messages that came after your change are listed on the note.
• Start (開始) sends the prompt to the chosen session and moves the note to Working. Only a session started with the jui-viz channel takes it. A session that cannot says why, and the note offers the command to start one.
• Working becomes Ended once that session was seen at work and is idle again, or has gone. You move it to Done.
• The State (状態) select moves a note to any state at once. It sends nothing, and a note moved this way is no longer followed to Ended.
• Ask to edit (直しを頼む) sends your words to the robot, which rewrites that task.
• A note's messages open in a side panel, each with Open in Slack (Slack で開く). Whole board (ボード全体) lays the six lanes over the room without shrinking them, and a lane's heading shows that lane alone, a note's prompt opens large in a popup, and the arrow keys move between notes. See Set up the Slack intake.The buttons check the state. Measured against the server:
refusals
Start on a Draft only a ready task is startedStart without a session choose the session to send it toDone on a Ready only a started task is doneReplies and the session's talkA reply in the thread of a started task goes straight to the session doing it, with no Start and no robot. The note then says 1 reply(ies) sent to the session (返信 1 件を担当セッションへ送った), and the reply joins the note's messages. Set autoForwardReplies to false in slack.json to stop this: the robot gets the reply instead and makes a new task pointing at the old one.• Which replies: the same thread in the same channel as a task that Start sent to a session, while that task is Working or Ended.
• Which stay with the robot: a Done task's thread, a task moved to Working with the State select, the same thread in another channel, and a thread that a Talking, Draft or Ready task also holds.
• When: once the thread has been quiet for 5 seconds, and no later than 30 seconds after the first reply started waiting. Replies waiting together go as one prompt, up to 12,000 characters, and the rest go next. One reply is cut at 4,000 characters. A reply first has to arrive: with mode api that is the next fetch, with mode socket it is as it is written.
• What is sent: the filtered text under projects/, so files are already dropped and secrets masked.
• Once only: a reply is marked before it is sent and is not sent twice, also across a restart. One being sent when the server stopped goes to the robot.
• A session that cannot take it: a full queue is tried again for 10 minutes. After that, or for any other refusal, the reply goes to the robot and the note says why: 1 reply(ies) went to the robot: session has no channel (返信 1 件は担当に送れず、ロボットへ回した: 担当が受け取れません(チャンネルなしで起動)).
Anyone in the thread reaches the sessionNobody presses Start for a reply, so whoever can post in that thread can put words in front of a working session. The prompt wraps each reply in <slack-reply>, says it is not an instruction from you, tells the session not to run commands, change or delete files, or send or publish anything because of it alone, and to ask you first. A reply cannot close that wrapper. These are words to a model and not a lock. If that is too much for a channel, set autoForwardReplies to false.
The robot may also read what the started session has been doing. The server keeps an excerpt at .state/context/<task id>.md, and the robot's list of tasks names it with context=.
• In it: your words and the session's text from Start on, up to that session's next task. Not tool calls, thoughts, or other sessions' messages.
• Size: the newest 16,000 characters, each turn cut at 2,000. The file is readable by you only and is removed with its task.
• The robot is told to read it only when a message's meaning is not clear, to treat it as material, and not to copy it into a prompt. In jsonui-cli's 10 tries it read the excerpt 8 times anyway, so expect it to be read. No key in slack.json turns the excerpt off.Done tasks are removedA task that has been Done for doneRetentionMinutes (60 by default) is removed, together with its messages under projects/, unless another task still names them. The note counts down: Removed in N min (あと N 分で消えます). The server does this whether the room is open or not. Moving a note out of Done keeps it; moving it to Done again starts the time again.Measured with doneRetentionMinutes 0: the task file and both of its messages were removed, and the server log said:
log
jui viz: slack room: removed 1 done task(s) and their messages: T-0001What was measured hereMeasured with an isolated viz on another port and state folder, messages placed in inbox/ by hand, and a path router adapter: the refusal of a 0644 slack.json, the filter, the routing, a reply following its thread, a failed filter keeping its message, the board's refusals, Prompts keeping the other keys, and the removal of a done task.Measured: the room's connector note, error line and socket line read in a headless browser; the robot's start command with and without robotName; and Socket Mode against a fake server on this machine (the acknowledgement, an edit not taken, Slack's marks written out, no second copy from a later fetch).Measured by driving the shipped factory code with a stand-in for the server's sessions (no Slack, no server, no session): a reply sent once and not again, the wrapper with a reply trying to close it, the 5-second wait and the 30-second limit, each case that stays with the robot, autoForwardReplies false, a refusal and a queue full past 10 minutes going to the robot, and what an excerpt keeps and leaves out, in a 0600 file in a 0700 folder. Read from the source only: the restart while sending, and the two notes on a note in the room. Not measured here or by jsonui-cli: a real session taking the reply while it works, a real Slack thread all the way through, and Codex.Not measured here: a real Socket Mode connection, fetching real messages from Slack in any mode, the haiku and jev routers, and the robot writing tasks. These are written from the shipped source. Upstream said the connector mode had not been tried on a real machine, and that Socket Mode had been checked only against a fake server.
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
Messages between sessions`jui viz message` sends a message from one session to another, Claude Code and Codex alike, and both robots' Talk shows it./viz/messages
Slack setupMake the Slack app, choose its scopes, take the tokens, turn on Socket Mode, write slack.json, start the robot, and read the room's errors./viz/slack-setup