Inbox and Review

One list of everything your agents are waiting on, a view of every agent and its conversation, answers from wherever you are, safer approvals, replies queued for a busy agent, and a review of what an agent changed.

The Inbox is one list of everything waiting for you, in every session and on every linked machine: approvals and questions an agent is blocked on, questions an agent put to you, mail, agents that errored, conversations to resume after a restart, and finished turns you have not looked at. From it you answer prompts, reply to agents and review what they changed.

The daemon keeps the Inbox, so every attached client sees the same list, and tuios list-attention prints it from a shell. The daemon can also send an item to your phone when nobody is at a client. See Push Notifications.

Setting up

Wire each harness you use to report its state. Its hooks then say when it works, waits and finishes:

tuios integration install claude-code    # or codex, gemini-cli, opencode, ..., or --all
tuios doctor agents                      # what is installed, and agent panes missing one

Without an integration, TUIOS still reads the process, the screen and the title, but it can say less. See Agents.

A person who never runs an agent is not shown any of this. Until an agent has been seen, the Inbox lines of the prefix menu, the palette's agent entries and the help's Agents section stay hidden. The keys work before that too.

Opening it

Key	Does
Ctrl+B i	Open the Inbox
Ctrl+B o	Go to the oldest item that needs you, switching session and workspace. o again goes to the next
Ctrl+B O	Go to the newest finished turn you have not seen. O again goes to the next older one
Ctrl+B M	Open the Inbox on its mail. m there opens the whole mailbox
Tab in the Inbox	Show every agent in one list, with its conversation. See The agents view

The palette has them too: type agent.

Rows are grouped under Approvals, Plans, Questions, Mail, Errored, Resume and Done, oldest first in each group. Mail to another machine whose link is down waits under Waiting to send. A row shows its kind's glyph, the pane's name, what it said, its session and how long it has waited. The footer offers only the keys that act on the row under the cursor, the one that answers it first. An item closes by itself when what opened it stops being true: the agent leaves needs_input, the mail is read, or someone looks at the pane that finished.

f shows one kind at a time. / narrows the list with a selector, such as harness:codex needs:you or session:api-fan-*. See Selectors.

Every key in the Inbox is rebindable. The full list is on the Keybindings page.

From a shell:

tuios list-attention
tuios list-attention --kind approval --kind question
tuios list-attention --select 'harness:codex group:fan/add-retry'
tuios list-attention --snoozed

Approvals
   35s  #2     api/claude  approve Bash: make

Questions
   46s  #1     docs/claude  which retry policy?

2 waiting. Open the Inbox with the prefix key then i, or jump to the oldest with the prefix key then o.

Only a person at an attached client can dismiss, snooze or answer an item. An agent cannot empty the list you read to find out what the agents want.

Answering a prompt from the Inbox

Space on an approval or a question opens the prompt as the pane shows it, with its numbered options and how long the agent has waited:

Key	Does
1 to 9	Choose that option
a	Approve
A	Approve and do not ask again, when the menu offers it
d	Deny
Tab	Type an answer
r	Read the prompt again
Enter	Go to the pane instead
Esc, q, Space	Back to the list

The keys are the ones the harness's manifest declares for that prompt. An answer is bound to an option's label, not its number, so A is offered only where the menu really has an "always" option. Before it presses anything, the daemon reads the prompt again and refuses if it changed. When two people answer the same prompt, the first answer wins.

The same two steps work from a shell outside every pane:

tuios peek-prompt -w review
tuios respond -w review --prompt-id 75f8b9fadb5b5dfc approve
tuios respond -w review choose 2

Crush permission prompts

Crush draws its permission prompt as a "Permission Required" dialog. TUIOS reads the dialog from the screen:

• The pane goes to needs_input, and the Inbox lists it under Approvals.
• The message names the tool and what it acts on, such as approve bash: touch hello.txt: the command for bash, the file for edit and write, and the URL or folder for the others.
• Space on the row shows the dialog. a allows, A allows for the rest of the Crush session, and d denies. TUIOS presses Crush's own keys for each: a, s and d.
• The dialog does not always show the whole call. A long command scrolls in the dialog, and a narrow dialog shows only Crush's description of the command. Then the message ends with (not all shown), and allowing it takes a second press, as for a risky call. Read the dialog before you allow it.
• TUIOS answers only the dialog itself. The dialog's words in Crush's chat, with no box around them, are not a prompt. When two boxes on the screen hold the dialog's words, TUIOS offers no answers.
• TUIOS answers only when it sees a Crush process in the pane. Any program can report to the herdr socket as Crush.

Crush v0.97.1 and earlier can report working while the dialog is still up. TUIOS then reads the screen, and the pane stays on needs_input until the dialog closes. If Crush stops at its dialog, for example after a crash, the pane clears when it is back at its shell.

Who may answer

respond acts as you, so the daemon takes it only from your attached client, or from a shell outside every pane when [daemon] respond_from_shell = true is set in the config file. A program inside a pane is refused with not_human, unless you gave that pane the respond grant.

Approvals the Inbox holds

The peek presses keys into a prompt on the pane's screen. For Claude Code, opencode, Kilo and Qwen Code, the Inbox can also hold a permission prompt before the harness shows it, and answer it for you. Turn it on per harness:

[agents.approvals]
enabled = ["claude-code", "opencode"]
hold_seconds = 120

Then run tuios integration install claude-code (or opencode, kilo, qwen) again, so its hook is the version that waits.

While a prompt is held, the harness shows nothing in its pane. The Approvals row shows the request, such as approve Bash: go test ./..., and the whole line is under the list:

Key	Does
1	Allow once
2	Always allow. Offered only when every rule it adds can be shown, and the rules are shown
3	Deny
n	Deny with a reason you type, which the model reads

A key answers only what you have read: the digits do nothing until the item has been on screen, unchanged, for 0.4 seconds. Only a request that fits on one line whole is held, such as a shell command or a file read. An edit, an MCP tool call or a long command is answered in the pane as before.

The hold ends with no answer, and the harness asks in its own pane, when hold_seconds passes, when you go to the pane, when you dismiss the item, or when the pane moves on. Any error on the way (no daemon, a restart, an unreadable reply) also falls back to the harness's own prompt. A failure can never approve.

Risk rules

An approval whose command matches a risk rule is marked risky: its row reads risky:, the rail's word for it is risky, and the detail names each rule. 1 and 2 then allow it only on a second press of the same key within 3 seconds. The first press sends nothing and says when it lapses. 3 denies with one press. The daemon enforces this too: an allow of a risky call that does not name the rules it matched is refused.

The shipped rules are matched against every command of a shell line, after sudo, env and similar wrappers, and inside sh -c, $( ), backticks and eval:

Rule	Matches
recursive delete	rm with -r and -f, in any order
force push	git push with --force, -f, --force-with-lease, or a + refspec
hard reset	git reset --hard
clean	git clean -f, -fd, -fx
discard changes	git checkout -- ., git checkout ., git restore .
pipe to shell	curl or wget piped to a shell or interpreter, or run through one with a substitution
sudo	any command under sudo or doas
disk	dd of=, mkfs, a redirect to a disk device
wide permissions	chmod -R 777, chown -R on / or ~
database	DROP TABLE, DROP DATABASE, TRUNCATE TABLE
infrastructure	terraform apply or destroy, kubectl delete, docker system prune, npm publish, cargo publish
outside the worktree	a write, copy, move or delete of a path outside the pane's worktree, or a Write or Edit of one

Add your own, or turn the shipped ones off:

[agents.approvals.risk]
builtin = true

[[agents.approvals.risk.rule]]
name = "kubectl apply"
tools = ["Bash"]
pattern = '\bkubectl\s+(apply|delete)\b'

Warning

A speed bump, not a sandbox

A command written to hide what it does (a variable holding rm, an alias, a script) passes the rules. The harness's own permission system stays the boundary. The rules make allowing a dangerous call take two deliberate presses.

Plans

With approvals on for Claude Code, a plan it asks you to approve when it leaves plan mode is held too, under Plans. The row is the plan's title and length, and the whole plan is under the list. J and K scroll it.

Key	Does
1	Approve. Claude Code leaves plan mode and still asks before each edit
2	Approve and accept edits for this session, when Claude Code offers that
3	Keep planning
n	Keep planning, with a reason you type

1 and 2 work only once the plan's last line has been on screen. 1 is the safest answer, which differs from Claude Code's own menu on purpose. Set hold_plans = false under [agents.approvals] to answer plans in the pane.

Questions an agent asks you

An agent, or a script, that needs a decision asks with fixed answers:

tuios ask-human 'Deploy the branch to staging?' -o yes -o no -o later

The question waits in the Inbox under Questions. When your client shows the pane that asked, the Inbox opens on it at once, and a digit picks the answer. From any other pane it raises the usual alert and waits. The command prints your answer and exits 0. If its --timeout runs out first it exits 2, the question stays, and your answer is mailed to the asking pane when you give it. Only you can answer: an agent calling it gets not_human.

Snoozing, undo and unread

Some of what lands in the Inbox is for later.

• z snoozes the item, then 1 for 15 minutes, 2 for an hour, 3 until 9:00 tomorrow, or 4 until it changes. A snoozed item leaves the list and the counts, and comes back early when the pane reports something new.
• S shows the snoozed items under a Snoozed heading. z on one wakes it now.
• d dismisses. u undoes the last dismiss or snooze for 10 seconds.
• On the rail, u on an agent row marks its finished turn unread again, for every client, and z opens the Inbox on it to snooze.

An approval the Inbox holds, a plan, and a question from ask-human cannot be snoozed, because an agent is waiting on them.

Try the keys on a pretend Inbox. Focus the list, then allow the risky command, snooze the finished turn and undo it:

Tip

This part is interactive on the docs site. Open it on tuios.dev.

The agents view

Tab in the Inbox shows every agent in one list: the agents of this session, of the other sessions, and of linked machines. Tab again goes back to the attention list. The Inbox opens on the view you used last. (Added in v0.10.1)

Each row shows the agent's state mark, its name, its session, what it does and how long it has done it. The row also shows what waits for the agent: queued replies, unread mail and subagents. An agent on another machine has the machine's name before its session. The rows come from the rail's agents section, so the two lists always agree.

Key	Does
j, k	Move
f	Show one group: all, needs you, working, done, error
s	Sort: needs you first, name, most recent change, session
/	Search. A key:value term is a selector. Other words match the name, the session and the agent's last message
Enter	Go to the agent's pane
r	Reply to the agent. See Replying and the queue
Ctrl+]	Look at the agent's own screen. Ctrl+B i comes back
Tab	Go back to the attention list
Esc	Close

The thread

On a screen 110 columns wide or more, the thread of the selected agent is next to the list. On a narrower screen, Enter opens the thread in place of the list. Enter there goes to the pane, and Esc goes back.

For Claude Code, the thread is the conversation from its transcript: your prompts, its answers, its tool calls and their result, plans and todo lists. The thread grows while the agent works. For other agents, the thread shows the recap of their turns, their last message and their last mail. A gutter mark is in front of all text that an agent wrote. Nothing in that text is a link or a key.

When the agent waits on an approval that the Inbox holds, the whole approval is at the bottom of the thread. 1 allows it once, 2 always allows it, and 3 denies it. The same rules apply as in the attention list. r or i opens the reply editor under the thread.

Ctrl+] closes the Inbox, focuses the agent's pane and zooms it. The dock shows Press ctrl+b i to go back to the agents. The Inbox then opens on the same agent, at the same scroll, with every draft kept. The key also works while the reply editor is open.

The view does not poll. The list changes when the state of an agent changes. The times move on once a minute while the view is on the screen.

Many agents at once

Space marks the selected agent. * marks every agent in the list, or clears the marks when all are marked. The title shows how many agents have a mark. With marks:

Key	Does
r	Write one reply. Enter queues it for each marked agent, at most 32. An agent that waits on a prompt, or that runs on another machine, does not get it. The dock names those agents
1	List each approval that the marked agents wait on. Enter allows all of them
3	Deny each approval that the marked agents wait on
d	Dismiss the Inbox items of the marked agents
z	Snooze the Inbox items of the marked agents. Then select the time

The list that 1 opens shows each approval whole. Enter does nothing until the list has been on the screen for a moment. A risky approval, a plan, and an approval that the screen cannot show whole are not in the list. The list says 2 need a second look. Allow them one by one. An approval that changed after the list showed it is not allowed. 2, always allow, does not work on many agents at once.

Esc and Ctrl+] close a reply to many agents and keep the draft. A key that send-keys typed does none of these actions.

Replying and the queue

A message for an agent in the middle of a turn has nowhere good to go: typed now, it lands in the middle of the turn. The queue holds it in the daemon and types it the moment the agent comes to rest.

r on a finished or errored item in the Inbox, on an agent in the agents view, or on a rail agent row opens the reply editor. Enter queues the reply. If the agent is at rest, TUIOS types the reply in a second or so. If not, the row says 1 queued until TUIOS types it. On the rail, x drops the newest queued message and u within 10 seconds queues it again.

On a pane that waits on a prompt, r opens nothing and says api is waiting on a prompt. Answer it first (space to peek).

The reply editor

The reply editor keeps line breaks. It grows to 8 rows, then scrolls. (Added in v0.10.1)

Key	Does
Enter	Queue the reply
Ctrl+J, Shift+Enter, Alt+Enter, \ then Enter	Add a new line
Alt+← →, Ctrl+← →	Move by word
Home, End, Ctrl+A, Ctrl+E	Go to the start or end of the line
Ctrl+W, Alt+Backspace	Delete a word
Ctrl+U, Ctrl+K	Delete to the start or end of the line
Ctrl+Z, Alt+Z	Undo, redo
Ctrl+C	Clear the draft
Ctrl+V	Paste from the clipboard: its text, or its image when it holds an image and no text
↑, ↓, Ctrl+R	Bring back an earlier reply. See History and your editor
Ctrl+G	Edit the draft in $VISUAL or $EDITOR
Esc	Close the editor and keep the draft. r on the same pane opens it again

The deny reason, the answer to a prompt and the selector line use the same editing keys, on one line.

Paste blocks. A paste of more than 800 characters or 3 lines shows as one block, such as [Pasted text #1 · 42 lines]. The cursor steps over a block in one move, and Backspace deletes all of it. When the cursor is right after a block, the block is selected and the footer shows its keys:

Key	Does
Ctrl+O	Read the text of the block. The arrows and page keys scroll, Esc goes back
Ctrl+E	Put the text of the block into the draft, to edit it
Backspace	Remove the block

Undo brings back a block that you removed or expanded.

Before it sends, the editor removes invisible characters, such as Unicode tags, bidi controls and zero-width spaces. When it removes any, it does not send and says Removed 3 invisible characters. Read the message and press enter to send. Text from a web page can hide instructions in these characters.

Naming a pane, an agent or a file

Type @ at the start of the reply or after a space. A list opens under the editor: the agents and panes of every session on this machine, and the files in the folder of the pane that gets the reply. Type more to narrow the list.

› compare with @rev
  agent work/review  working

Key	Does
↑, ↓	Select an entry
Tab	Put the entry in place of the @ and the text after it
Esc, Space	Close the list

An agent or a pane goes in as its address, such as work/review. A file goes in as its path from the folder of the pane, such as api/client.go. A folder goes in with a slash and keeps the list open, so you can go into it. TUIOS does not copy the file. The agent reads it with its own tools.

The list shows no files for a pane whose folder TUIOS does not know, or whose shell runs on another machine. A client in a browser or on the SSH server shows no files, because the files are on the server and not with you.

Images

An image in the reply shows as one block, such as [Image #1 · 1280×720 png]. These three actions attach an image:

• Ctrl+V when the clipboard holds an image and no text. TUIOS reads it with wl-paste, xclip, osascript or PowerShell.
• An empty paste from your terminal. Some terminals send one when the clipboard holds only an image.
• A paste of only the path of an image file. A terminal pastes a file that you drop on it in this way.

While the draft holds an image, a strip above the draft shows a preview of each image, 3 rows high. The strip shows at most 4 images, then +N more. TUIOS draws the previews with kitty graphics when your terminal has them, and with block characters if not. At 16 colours each image is a line of text, such as Image #1 · 1280×720 png · 412 KB.

Ctrl+O on a selected image shows it larger in place of the draft. There, o opens the image in the image viewer of your desktop, from a private copy. TUIOS removes the copy when you close the view. Esc goes back to the draft.

A reply takes 8 images, each at most 8 MB, and 8 MB in total. The same image twice is refused: Image #1 is already in the message. A client that runs on another machine, such as tuios ssh or the browser, cannot read your clipboard image. There, Ctrl+V pastes the text.

When TUIOS types the reply, the daemon writes each image to a file on the machine of the pane. The harness manifest tells where the path goes. Claude Code, Codex, OpenCode, Kilo and Crush get the path in a paste of its own, where the image was, so the agent attaches the image. See How a reply is typed. An agent that takes no images refuses the reply: This agent cannot take images. Remove the image to send.

Large pastes

The daemon on the machine of the pane decides how each block gets to the agent when it types the reply:

• A reply of 12 KB or less goes in one paste, with the text of each block in its place.
• In a larger reply, each block goes into a file, and a label in its place names the file.

make the backoff jitter configurable. The failing run:
[Pasted text #1: /run/user/1000/tuios/paste/tuios-paste-reply-20261016-101500-3fa2c1.txt, 2,048 lines]

The agent reads the file with its own tools. The file is yours only, in the paste folder next to the daemon's socket. The daemon writes the file when it types the reply, so a reply that waits in the queue never names a file that is gone. The daemon keeps the file for 24 hours, and removes it when the daemon stops.

The typed words without the blocks must fit in 16 KB, and the whole reply in 8 MB. A larger reply stays open and says why: The message is larger than 16 KB. Make it shorter to send. or The message is larger than 8 MB. Remove a paste to send.

A daemon from v0.10.0 or earlier takes a reply with blocks only when all of it fits in 16 KB. For a larger reply, the editor keeps the draft and tells you to restart the daemon with tuios kill-server.

History and your editor

↑ on the first row of the draft brings back what you sent to this agent before, newest first. ↓ on the last row goes the other way, back to your draft. Ctrl+R searches what you sent: type to narrow the list, select with the arrows, and press Enter to load the message. A draft that Ctrl+C cleared is in the history too.

The daemon keeps the history in memory only, for each harness and folder. A pane that opens again in the same folder keeps its history. The history ends when the daemon stops. Only your attached client can read it. Each message keeps at most 256 KB of pastes and images. A larger block is not kept, and the editor tells you when the message comes back.

Ctrl+G opens the draft in $VISUAL or $EDITOR, with the text of each block in its place. When you save and quit, the file becomes the draft. An image is in the file as its label, such as [Image #1 · 640×480 png]. Keep the label to keep the image in its place. Remove the label to remove the image. TUIOS refuses a file that is too large for a draft, and the draft does not change. The file is yours only, and TUIOS removes it when the editor closes.

When the daemon refuses a reply, the draft stays. Drafts stay in the memory of the client and end with it.

Replying to an agent on another machine

A reply to an agent on a linked machine goes to the daemon on this machine, which sends it over the link. The other machine queues it, writes the paste and image files there, and types the reply when the agent comes to rest. The [hosts] policy of that machine for this machine must allow write, and files for a paste block or an image. See Remote Hosts.

The queue

From a shell:

tuios queue -w build 'make the backoff jitter configurable'
tuios queue ls
tuios queue rm q3

ID  STATE    BY     AGE       PANE   MESSAGE
q1  waiting  shell  just now  build  make the backoff jitter configurable

• A message is typed once the agent has been at rest for a second, one message per rest.
• It is never typed over a prompt the agent waits on, so a queued message cannot answer an approval.
• The daemon watches for the agent to take it. A message it does not take within 5 seconds is marked stalled, is never typed again, and opens a question in the Inbox asking you to look at the pane.
• A pane holds at most 8 messages ([agents.queue] max), each at most 16 KiB of typed text. A reply with paste blocks can carry up to 8 MiB of pasted text. The queues hold at most 32 MiB for each pane and 128 MiB in total.
• The queue lives in memory: a daemon restart, the pane closing, or the agent leaving the pane drops it.

Reviewing an agent's changes

When an agent finishes, read what it changed, leave notes on the lines you want changed, and send the notes back as one message.

Ctrl+B v reviews the focused pane. v in the Inbox or on a rail agent row reviews that item's pane. The review opens over the whole screen: the changed files on the left, the file under the cursor on the right, and each note under its line. The code is coloured by file type in your theme's colours, and s puts the old and new sides next to each other on a wide screen.

│ Review  api-fan-demo-2  Terminal f40d4b17  2 files  +2 -0  vs main  1 note
├──────────────────┬──────────────────────────────────────
│  M a.txt   +1 -0 │ › @@ -1 +1,2 @@
│  U b.txt   +1 -0 │    1   1   hi
│                  │        2 + change
│                  │          ▌ note from a script: why this line

c adds a note on the line under the cursor and C one on the whole hunk. S sends every unsent note to the agent as one message, through the queue, so it is typed when the agent is at rest. Every key is on the Keybindings page.

To read or undo what one turn changed, see Checkpoints. When the work is good, ship it: commit, merge, push and open a pull request. A push that an agent asks for waits for your yes under Questions.

From a shell:

tuios review api-fan-retry-2 --stat
tuios review note -s api-fan-retry-2 api/retry.go:42 'log the attempt number here too'
tuios review notes -s api-fan-retry-2
tuios review send -s api-fan-retry-2

Review of api-fan-demo-2, pane f40d4b17, against main (20e3b85): 2 files, +2 -0
M  a.txt  +1 -0
U  b.txt  +1 -0

What is diffed. The pane's repository, from its base: the base the worktree was made from (by fan or worktree new), else the merge base with the branch's upstream, else HEAD. Committed and uncommitted work show together, untracked files included. --base names another base, --uncommitted shows only what is not committed, and --against diffs two attempts of a fan. The diff is made through a temporary git index, so the repository, its index and its files are never changed. It stops at 400 files, 2 MiB of text or 5000 lines in one file.

Notes. A note keeps the text of its line, so it follows the line when the file changes. A note whose line is gone is marked outdated. The daemon holds the notes, so every client and the CLI see the same ones. A daemon restart keeps the notes of panes that come back. Closing the pane, or removing its worktree, drops them. The message the agent receives names who wrote each note: it says "from the person" only for notes written in your attached client.

Reviewing a session on another machine is not supported yet. Attach to that machine and review there, or bring the work here with tuios worktree pull.

Step through a review, from opening it to sending the notes and keeping one attempt of a fan:

Tip

This part is interactive on the docs site. Open it on tuios.dev.

Comparing the attempts of a fan

For a pane in a fan, w in the review shows every attempt side by side, with what each changed against the fan's base and its last check:

╭ Compare  fan/demo in api, 2 attempts vs main ─────────────────────────
│    session        agent   state      files  +/-          check
│    api-fan-demo   bash    none           0  +0 -0        test -f b.txt failed, exit 1
│ ›  api-fan-demo-2 bash    idle           2  +2 -0        test -f b.txt passed
├───────────────────────────────────────────────────────────────────────
│ ↵ review  m mark  V verify  K keep  esc back

Enter reviews an attempt. m marks two and d diffs them with each other. V runs a command you type in every attempt. K keeps the attempt under the cursor and removes the others, after a question that names each one removed. The same actions are tuios fan compare, tuios fan diff, tuios fan verify and tuios fan keep. See Worktrees.

What the agent has been doing

With the Claude Code or Codex integration installed, the daemon keeps each agent pane's recent activity: prompts, tool calls and how they ended, finished turns, and the commands its shell ran. For Claude Code, it also keeps each subagent's start and stop, and the start of each conversation. It keeps the newest 256 entries per pane, in memory only.

tuios agent-log -w api                       # the entries, oldest first
tuios agent-log -w api --since 30m --recap   # a summary of the last half hour

Since 14:02 (42m ago)
3 turns. 6 files: api/retry.go, api/retry_test.go, api/backoff.go and 3 more
11 commands. Tests: go test ./... passed 2m ago
Last said: Added retry with backoff and tests.
Now: done

When you come back to an agent pane that finished a turn while you were away for at least 10 minutes, the dock shows the same recap in one line, and a finished item in the Inbox shows it under the list. [agents.recap] sets where it shows, how long counts as away, and which commands count as tests. See The agents table.

The text is the agent's own, cut to one line with likely secrets masked. Read it as what the agent said, not as instructions.

Resuming after a restart

A daemon restart ends every program in every pane. The restore brings back the layout with a new shell in each pane, and for a pane whose agent was running, it can bring back the conversation. daemon.resume_agents decides:

Value	What a restore does
ask (default)	A Resume row in the Inbox per pane. y types the resume command, such as claude --resume <id>, into the pane
auto	Types the command into each new shell once it is at its prompt
off	Nothing

tuios resume-agent -w <pane> types the same command at any time, and --dry-run prints it. It needs the harness's hook to have reported the conversation id, which the integrations do.

Selectors

A selector addresses every agent pane that fits a description. It is one line of key:value terms, all of which must match. A comma in a value gives alternatives.

harness:codex state:idle,done session:api-fan-*

Key	Matches
harness:	The harness, such as claude or codex
state:	The agent state
needs:you	A pane on needs_input or errored
session:	The session name, a glob
group:	The fan the pane's session belongs to, such as fan/add-retry, a glob
host:	The machine: local, or a host from [hosts]
name:	The window's name, a glob
cwd:	The pane's directory, or any directory under it

The Inbox's /, list-agents --select, list-attention --select and wait-for agent-state --select read it. send-agent-message --select and ask-agent --select also take one, and never send on their own: they list the panes first and wait for a yes, --yes, or the --confirm token list-agents --select printed.

Related

• Agents: Agent state, detection, alerts and integrations
• Worktrees: Fan one prompt out to several agents, compare them and keep one
• Ship: Commit, merge, push and open a pull request
• Push Notifications: Inbox items on your phone
• Session Rail: The agents section and what its rows say
• Keybindings: Every Inbox, review and rail agent key