Keybindings

The agents view

The agents view: part of the Keybindings of TUIOS.

This page is one part of docs/KEYBINDINGS.md of the tuios repository. The Keybindings page lists every part.

The agents view

Everything waiting for you, and every agent tuios knows of, is one full-screen view on ctrl+b i. It was the Inbox panel. The agents are grouped by what each needs from you: Needs you, Ready for review, Working, Idle, Settled. What the Inbox held is the Needs you group. Settled holds the agents you put away with D and the agents at rest for more than an hour. See AGENT_STATE.md for what goes in it.

KeysWhat it does
ctrl+b iOpen the agents view
ctrl+b oGo to the oldest item that needs you; o again, inside the repeat window, goes to the next
opt+shift+j / opt+shift+k (alt+shift+j / alt+shift+k off macOS), or ctrl+b J / ctrl+b KNext and previous agent pane (next_agent, prev_agent), in the order the rail's agents section lists them, wrapping at the ends. From a pane with no agent they go to the first and the last. An agent in another session or workspace is switched to, as choosing its row does. The chords also work in terminal mode and while the rail has the keyboard
ctrl+b MOpen the agents view on the mail for you (m there opens the whole mailbox)

Inside it:

KeysWhat it does
j k, arrowsMove between agents. The focus area shows the selected one
g GGo to the first or last agent. When the thread is scrolled up, G first shows its newest lines and follows it again
enterGo to the agent's pane and close the view. On mail, open the thread
a A X ROn a held approval: allow once, always allow, reject, reject and say why. 1 2 3 still work
r, iWrite a reply to the agent, or to the mail. On a held approval, r names the keys that answer it
tab shift+tabGive the keys to the next or the previous region: the list, the focus, the reply, the side column. A region the screen does not show is skipped. See below
NGo to the next agent that needs you, and from the top again after the last
spaceRead an approval's or a question's prompt and answer it here. On a card of the board's columns: show the card whole, its prompt, attachments and history, beside the columns or over them. It follows the cursor; J K scroll it, [ ] step its attachments and show the selected one, o shows a picture whole, Z zooms it, and space or esc closes it
nOpen the New agent sheet. See below
cOn an attempt of a fan: compare the attempts. See below
bShow the task board, the cards grouped by stage, or the agents again
tOn a card: take it for the pane behind the agents view. n on a card in the board's list opens the New agent sheet on it
H L, shift+left shift+rightOn a card: move it to the stage before or after
vOn a card its agent is done with: open the Changes view of that agent's worktree, while its pane is open
MOn a card in review: Ready to merge. Then c commits the work with the card's title, p pushes the branch, o pushes it and opens the pull request. A push and a pull request show what they send first, and enter sends it
BShow the task board as columns or as a list
Ctrl+TOn the board: turn task dispatch from manual to pull to auto. In pull, an agent that finishes its card is given the board's next open card. In auto, tuios starts an agent for each open card in a new worktree, with the board's preset (the New agent sheet's saved preset the first time, else Claude Code on this machine), at most 3 at once. The header says which, and in auto how many run and wait
Ctrl+XOn the board: pause all task dispatch, or start it again after a pause or a stop. The palette has "Agents: pause all task dispatch" too
\Show the agents as a column beside the focus, or as a strip of chips above it. tuios keeps the choice. See view_list in CONFIGURATION.md
oOpen what the agent has shown, such as a TML form, on its Artifacts tab, and use it. esc goes back to the list
fShow only what needs you, then each kind of item, then every agent
sOpens the Group menu under the header's Group control: 1 groups by state (Needs you, Ready for review, Working, Idle, Settled), 2 by session, 3 by machine, 4 by project, and s steps the order inside each group. Up and down and enter pick too, and esc closes it. Needs you stays on top in every grouping, and the header counts the agents by state in every one. tuios keeps the grouping. A click on Group opens the same menu, and the header's Board and machine controls open menus of their own: Agents or Board, and All machines or one machine
/Search. A key:value term is a selector, such as harness:codex
d z u SDismiss, snooze, undo, show the snoozed items
DSettle the agent: put it away until it needs you. It goes to Settled, and its finished turn closes. D on a settled agent takes it off the shelf, and u undoes a settle within 10 seconds. With marks, settle every marked agent. The Settle button in the focus header does the same
y p mResume in place (the view stays open), pass held mail on, open the mailbox
x *Mark an agent or a Resume row, or every row shown, for a bulk answer. A marked row shows a mark, and the header counts the marks
1 3 with marksAllow every marked approval once, after a sheet that lists them, or reject them
y with marksResume every marked Resume row. * then y resumes them all
[ ]Switch the focus tabs: Card on the board, Thread, Changes, Artifacts, Checkpoints and Pane
J KScroll the thread, or a long plan waiting for a yes a page at a time. On the Artifacts tab, move between the artifacts
{ }Show the thread's previous or next prompt at the top. The ruler at the right of the thread marks each prompt
.Select the next agent a card in the thread names: one it started, or one it sent mail to, asked or read mail from. enter or a click on the name opens that agent's thread
ctrl+oGo back to the thread you opened another agent from, at the same place. Each ctrl+o goes back one more
eShow every line of every card in the thread
WWrap the long lines of the thread's code blocks, or cut them again. A wrapped row starts with ↳, and a cut line ends with …. It holds until the client ends
ctrl+b [Copy mode over the thread (y in the focus region too): the pane's copy mode keys, Y copies the selected entries as Markdown, and gx opens the link under the cursor. A click moves the cursor, a drag selects, and the wheel scrolls
click on a linkOpen it, as a link in a pane opens. The pointer on a link underlines it
Drag over the threadSelect text and copy it on release. A double click selects a word, a path or a URL; a triple click a line; shift+click moves the end. A right click on the selection offers Copy, Copy as Markdown and Search for it
FFold or open the group of the row under the cursor. On a folded heading, enter also opens it
vReview the agent's changes
ctrl+]Go to the agent's pane and zoom it. ctrl+b i comes back to the same agent
l h, right leftOn a narrow screen, open the focus and go back to the list
?All keys. Help opens over the view, and esc gives the view back as it was
escGo back one step: on a narrow screen from the focus to the list, then from a region to the list, then clear the search and the filter, then close the view. The key bar says what the next esc does
qClose the view at once
< >Make the list narrower or wider by 4 cells. A drag on the edge of the list sets it, and a double click there resets it. tuios keeps the width. See list_width in CONFIGURATION.md
wHide the side column, or show it again. The column needs 170 columns and room for the focus beside it; without that room w says why in the key bar and changes nothing
ZShow the focused region alone. Z or esc gives the whole view back. Under 80 columns Z says so in the key bar and changes nothing, except on a plan whose card is open, which it still zooms

The focus header has a Talked with line when the agent has sent or got mail or asks: a chip for each agent, the newest exchange first, with how many messages went between them. A click on a chip opens that agent's thread, and ctrl+o comes back. The agents the line has no room for are in a +N chip, which opens them as a menu. An agent with no mail has no line.

The region that has the keys wears an accent rule along its top edge, and the key bar names it at the left and shows its keys. In the focus, j k scroll the thread a line, the page keys a screen, and g G go to its ends; every other key does what it does in the list. In the side column enter opens the agent's pane. A click in a region gives it the keys; the wheel does not. Stepping onto the reply opens it, and stepping off keeps the draft, as esc does. In the @ list tab still puts the entry in.

On the board's columns, h l go between the columns, j k between the cards, n adds a card, and enter on a free card opens the New agent sheet on it. See AGENT_STATE.md.

When the board opens, it also reads the project cards of each linked machine (tuios task ls --hosts). Such a card says on HOST, and its holder, if it has one, is a pane on another machine. The view does not change it: t and n on it show the command to run in the agent's pane, tuios task claim ID -s HOST:SESSION, and its Card tab names tuios task get, which reads it from its machine.

A bulk key acts only on the marked agents the list shows. An agent in a folded group, or one a search hides, is left out, and closing the view clears the marks. An approval whose command does not fit on the card is not answered here: the card says so, and enter answers it in the pane.

c on an attempt of a fan compares every attempt side by side: its agent, how long it took, its diff, its check from tuios fan verify, its first changed lines and its files. J asks a judge: an agent that reads the attempts and reports which one to keep. Through tuios it can only read the attempts: their diffs, screens and scrollback. Its verdict shows on top, with its reasons, and its pick is marked recommended. 1 to 9 and the arrows pick an attempt, and K twice keeps it: the other worktrees are removed, their changes go to git stash and their branches stay. The first K names every file git ignores in the other worktrees, such as .env: they are deleted, not stashed. j and k, or up and down, scroll that list, as they move everywhere else in the view. The second K reads the attempts again and keeps only when nothing changed. When the list grew, or could not be read, it says so and keeps nothing. enter goes to the attempt's pane, r reads the attempts again and esc goes back.

The New agent sheet starts an agent with a task. Write the task, then pick the agent, the model, where it works and the machine. tab and shift+tab move between the fields. left and right change the agent, where it works, the attempts and the button. space or down on the agent opens the list of every agent. up and down on the machines pick one. v on the attempts gives each attempt a different agent. ctrl+j adds a new line to the task. enter starts. esc closes the sheet and keeps what you wrote for the next n.

FieldWhat it does
TaskThe first prompt. It is typed when the agent is ready
AgentThe agents that run now come first, then the installed ones
ModelPassed to the agent as --model. Empty uses the agent's default
Where it worksA new worktree on its own branch, or this folder
Branch, BaseThe new branch, named after the task until you change it, and where it starts
MachineThis machine and the linked hosts, the most free cores first
Attempts1 to 8. Each attempt gets its own worktree and branch

A new worktree goes through the same path as tuios fan, and this folder through tuios start-agent. Uncommitted files stay in this folder. On a linked host the agent works in a new worktree of the host's checkout, which the host finds by the repository's origin.

The Artifacts tab lists what the agent has shown you: each TML document its pane opened, open or closed, and each screenshot it took. The newest is first. The selected one is drawn under the list. An open document is the same document as its popup or pane, with the same state: what you choose in one place shows in the other. o or a click gives it the keys, and esc gives them back. A closed document shows what it showed last, and your answer. A document from another session is read-only here.

A TML popup and the agents view do not show at the same time:

  • Open the view while an agent's popup floats, and the view selects that agent and shows the popup's document, with the keys.
  • A document that opens while the view is open shows in the focus when it is from the selected agent. From another agent, its row gets a ● new artifact chip, and a popup moves the row to Needs you. A click on the chip opens it.
  • Close the view while the Artifacts tab shows an open document, and its window gets the focus and floats again.

In the image view, which a click on an image chip in the reply opens: o opens the image in the desktop's viewer, c saves a copy and copies its path, s saves a copy, left and right step through the images, + and - zoom, and esc or a click outside the picture closes it.

The mouse works too. A click on a row selects it, and a double-click goes to its pane. A click on a group heading folds the group, as F does. The buttons on an approval card answer it. + New agent opens the New agent sheet, and the search box opens the search. The wheel scrolls the list, and over the focus it scrolls the card. A search narrows the items with the agents. A selector the search line cannot read shows its error in the search box.

The layout follows the width of the screen. At 120 columns and wider the list has two lines per agent beside the focus. From 80 columns the rows are one line. Under 80 columns the list fills the screen, and enter, right or a click opens the focus in its place. With one or two agents the list folds into a strip of names over the focus. When the list is taller than the screen, its rows are one line and a long group shows its first 8 rows; right or a click on +N more shows the rest.

In the mailbox: j and k move, enter opens a thread, n writes a new message, esc closes. n opens a list of the agents in this session. Choose one with enter, type the message, and press enter to send it. In an open thread, r replies, o goes to the pane that last wrote, and esc goes back to the list.

The message editor works as the reply does: ctrl+j adds a line, a long paste shows as one block, and ctrl+v attaches the clipboard's image. A message that does not fit in 8 KB, or that holds an image, goes with each block and image as a file the message attaches.

In the prompt space opens: a digit chooses that option, a approves, A approves and does not ask again, d rejects, tab types an answer, r reads the prompt again, enter goes to the pane, esc goes back to the list. A prompt with numbered options offers its digits in the footer and not a, A and d, which still work. See Answering a prompt without attaching.

These keys are in three sections of their own, rebindable like any other: [keybindings.inbox] (the list: inbox_down, inbox_up, inbox_page_down, inbox_page_up, inbox_first, inbox_last, inbox_go, inbox_peek, inbox_dismiss, inbox_reply, inbox_resume, inbox_pass_on, inbox_filter, inbox_select, inbox_mailbox, inbox_close, inbox_write, inbox_sort, inbox_view_pane, inbox_new_agent, inbox_allow, inbox_allow_always, inbox_reject, inbox_open, inbox_back, inbox_help, inbox_mark, inbox_mark_all, inbox_tab_prev, inbox_tab_next, inbox_expand, inbox_code_wrap, inbox_code_left, inbox_code_right, inbox_code_copy, inbox_block_source, inbox_fold, inbox_prompt_prev, inbox_prompt_next, inbox_child, inbox_jump_back, inbox_compare, inbox_artifact, inbox_board, inbox_board_layout, inbox_dispatch_mode, inbox_dispatch_pause, inbox_view_list, inbox_take, inbox_ship, inbox_stage_prev, inbox_stage_next, inbox_region_next, inbox_region_prev, inbox_escape, inbox_next_needs), [keybindings.inbox_peek] (the prompt: peek_approve, peek_approve_always, peek_deny, peek_type, peek_read_again, peek_go, peek_back) and [keybindings.mail] (the mailbox: mail_down, mail_up, mail_page_down, mail_page_up, mail_open, mail_reply, mail_focus_pane, mail_new, mail_back). The footers name whatever key the config binds. The digits 1 to 9 are not bindings: they pick an answer by the number the prompt shows. The selector line and the reply, message and answer lines take text, so every key there is typed. The selector line, the reason for a reject and the answer to a prompt are edited as the reply is: the arrows and the word keys move the cursor, ctrl+z undoes, and a paste keeps to one line.

The global keys work over the view, and over every line and sheet in it: ctrl+p opens the command palette and opt+space (alt+space off macOS) the launcher on top of the view, the reply included. While the reply's @ list is open, ctrl+p and ctrl+n move in the list. The leader works too, in window mode and in terminal mode, so ctrl+b , opens settings over the view. Each one closes back to the view as you left it: the same agent, the same scroll, the same draft. A key that types a character stays the view's even when [keybindings.global] binds it, and tuios keybinds doctor lists a view key that a global key takes. A palette command that goes to another pane or workspace closes the view; ctrl+b i opens it again on the same agent. A click on the view outside the palette closes the palette and selects nothing. ctrl+p and ctrl+n no longer move the list: j k and the arrows do.

[keybindings.inbox]
inbox_dismiss = ["x"]

The keys new with the agents view yield to your own: when your [keybindings.inbox] already gives n, R, a, x or another new key to an action, that action keeps it, and the new action has no key. tuios keybinds doctor lists each one. inbox_agents, the old tab that switched the Inbox to the agents view, is gone: tab is inbox_region_next now, and doctor lists a config that still binds inbox_agents. A config that kept the old default inbox_deny_reason = ["n"] moves it to R, so n starts a new agent, and doctor says so. When your binding takes one of an action's new keys, only that key yields: inbox_open keeps right when l is yours.

The help overlay (ctrl+b ?) has an Agents section with all of these, the prefix chords, the rail's agent keys and the palette's @ filter, read from your config. In the command palette the agent actions are named "Agents: ...", so typing agent lists them: what needs you, the mail for you, the oldest waiting item, and the mailbox.

On an approval tuios holds ([agents.approvals], see AGENT_STATE.md), 1 allows it once, 2 always allows it and 3 rejects it; enter gives the prompt back to the pane. The keys act on the row under the cursor, whose whole prompt, and the rules 2 adds, are shown on its card, and only once it has been on screen as it is for 0.4 seconds. space does not open a held approval: the hook keeps its prompt off the pane until you answer, so there is nothing on the screen to read.

Review, triage and replies

These keys are bound for the agent review, triage, reply and approval work. The triage keys work: ctrl+b O, z, u and S in the agents view, and u and z on a rail agent row (see Snoozing, undo and unread), and so do the approval keys: R, J, K, ctrl+d and ctrl+u in the agents view (see Reject with a reason), and the reply keys: r in the agents view on a finished or errored item, and r and x on a rail agent row (see Replying to an agent), and the review keys: ctrl+b v, and v in the agents view and on a rail agent row (see The review overlay below). ctrl+b v works whether or not an agent has been seen, since calling it is an explicit act; on a pane with no git repository under it, the dock says so and nothing opens. ctrl+b O does what an unbound key does until an agent has been seen: after ctrl+b in terminal mode, the key is typed into the focused pane, so a person who runs no agents keeps typing O into the pane. The prefix menu and the help overlay list them only once an agent has been seen, like the rest of the Agents section. Attached to a daemon without mark-attention (an older one, found by asking its list-verbs once per attach), the agents view's z, u and S and the rail's z are not offered and do what an unbound key does, and the rail's u clears only this client's seen marks. Attached to a daemon without review-diff, found the same way, ctrl+b v and the two v keys are not offered and do what an unbound key does: after ctrl+b in terminal mode, v is typed into the focused pane.

KeysWhereWhat it does
ctrl+b vanywhereReview the focused pane's changes
ctrl+b OanywhereGo to the newest finished turn nobody has seen; O again, inside the repeat window, goes to the next older one, and a turn that finishes meanwhile starts over
ctrl+b AanywhereOpen the Agents tab of the settings page, where you install, update and uninstall each harness's integration
vagents viewReview the changes in the item's pane
z, then 1 to 4agents viewSnooze the item: 15 minutes, 1 hour, until 9:00 tomorrow, or until it changes; any other key cancels. On a snoozed item, wake it
uagents viewUndo the last dismiss, snooze or settle, within 10 seconds
Dagents viewSettle the agent, or every marked one. Put away until it needs you
Sagents viewShow or hide snoozed items
Ragents viewReject a held approval, or keep a plan planning, with a reason you type (X and 3 stay the plain reject)
nagents viewStart a new agent
cagents viewCompare the attempts of the fan under the cursor
J, K, ctrl+d, ctrl+uagents viewScroll the card a page, such as a long plan. On a plan, pgdown, pgup, g and G read the plan before they move the list
urail agent rowMark the pane's finished turn unread, for every client (not the pane in front of you)
zrail agent rowSnooze what needs you in the pane: the agents view opens on it with the four lengths
enterrail +N at rest lineShow the agent rows folded as at rest, settled agents included, until the rail lets go of the keyboard (after a click with the rail not focused, until a click outside the rail or a pane is focused)
ragents view, on a finished or errored itemReply to the agent: the editor under the thread, queued with enter and typed when the agent is at rest
rrail agent rowReply to the agent, the same line in the agents view; refused while the pane waits on a prompt
vrail agent rowReview the pane's changes
xrail agent row with messages queuedDrop the newest queued message still waiting; u on the row within 10 seconds queues it again. On a row with nothing queued, x opens the rail's menu as before. From send-keys or a tape, neither x nor the undo touches the queue, since both act as the person

A key never answers a held approval alone. 1, 2, 3, a, A and r ask first, and so do a, A, d and a digit in the peek: the card says what will happen, enter answers, and any other key cancels and does nothing else. A sentence typed into the list by mistake answers nothing. On a plan, 1 approves, 2 approves and accepts edits for the session, and 3 keeps it planning; 1 and 2 work once the plan's last line has been shown. The digits are not bindings.

The agents view's keys are inbox_review, inbox_snooze, inbox_undo, inbox_show_snoozed, inbox_deny_reason, inbox_detail_down and inbox_detail_up in [keybindings.inbox], and the prefix chords are prefix_review, prefix_next_finished and prefix_agents_settings in [keybindings.prefix_mode]. The agent rows' keys are a section of their own, [keybindings.sidebar_agents] (agent_unread, agent_snooze, agent_reply, agent_review, agent_cancel_queued, agent_subagents). It is consulted before the rail's own keys and only while the cursor is on an agent row, the way [keybindings.sidebar_files] is on a file row, so r and x mean the agent on an agent row and keep renaming and opening the menu on every other row. agent_subagents (space) opens or closes the subagent rows under the agent row. It works on the agent row and on the subagent heading, and only when appearance.sidebar.subagent_collapse is expanded or collapsed.

The reply editor takes every key: enter queues the reply, ctrl+j, shift+enter or \ then enter adds a new line, and esc closes it and keeps the draft. A paste keeps its line breaks, and a long one shows as one block. ctrl+v attaches the clipboard's image when it holds one and no text. @ opens a list of agents, panes and files to name: tab puts one in. up on the first row brings back an earlier message to the same agent, ctrl+r searches them, and ctrl+g opens the draft in $EDITOR. alt+m makes the editor as tall as its area and back; [agents] reply_rows sets its own height. ctrl+o on a selected image shows it larger, and o there opens it in the desktop's image viewer. The editing keys are in docs/AGENT_STATE.md, "Replying to an agent". They are not bindings yet. Attached to a daemon without queue-prompt (an older one), the first reply says to restart it, and after that r does what it did before: it says r replies to mail in the agents view, and renames on the rail.

The review overlay

ctrl+b v (or v in the agents view or on a rail agent row) opens the diff of the pane's changes over the whole screen, once the daemon has read it: the file list on the left, the file under it on the right, and your notes under the lines they are on. The code is coloured by its file type in the active theme's colours, added and removed lines sit on green and red grounds, and the words that changed in a changed line are marked. It owns every key while it is open, in either mode. The keys are the overlay's own, not bindings, like the scrollback browser's, except the hunk and file motions and the stage keys, which are in [keybindings.review]:

KeysWhat it does
j / k, arrowsMove by line; with the file list focused, move through the files
space, pgdown, ctrl+d / pgup, ctrl+uMove by a page
g / GFirst or last line
] / [Next or previous hunk, going on into the next or previous file (review_next_hunk, review_prev_hunk)
} / {Next or previous file (review_next_file, review_prev_file)
aStage the hunk under the cursor (review_stage_hunk)
dUnstage the hunk under the cursor (review_unstage_hunk)
A / DStage or unstage the whole file (review_stage_file, review_unstage_file)
zUndo the last stage or unstage (review_undo_stage)
sOne column, or the old and new sides next to each other where the diff column is wide enough (about 120 columns of screen)
h / l, left / rightScroll the focused panel sideways. In the diff, scroll the code. In the file list, scroll the paths to show the start of a long path
tabFocus the file list or the diff. A review opens on the diff, or on the list with [review] focus = "files" (see CONFIGURATION.md)
enterIn the file list: open that file
cA note on the line under the cursor
CA note on the whole hunk
eEdit the note under the cursor
xResolve (remove) the note under the cursor
SSend every unsent note to the pane's agent as one message, typed when it is at rest
uSwitch between the changes since the base and the uncommitted ones only
bDiff from another base (a line, filled with the current one; empty for the default)
wThe compare view, for a pane in a fan
rRead the diff again
esc, qClose (from a review opened in the compare view, go back to it)

A stage key changes only the index of the pane's worktree. The working files do not change. A hunk header shows staged when the index holds all of the hunk, and partly staged when it holds some of it. a stages only the lines of the hunk you see. When git splits those lines into two hunks of the index, the first a stages one part and the hunk shows partly staged. Press a again to stage the rest. The keys do nothing in a comparison of two attempts.

In the note line and the other one-line prompts every printable key is text, a paste is typed as one line, enter saves and esc drops.

], [, } and { need Option on some layouts, AZERTY among them, where Option is often the Alt key that tuios reads. To move them, bind other keys in the review section. A key bound there wins over the overlay's own key, so pick one the table above does not use:

[keybindings.review]
review_next_hunk = ["n"]
review_prev_hunk = ["p"]
review_next_file = ["N"]
review_prev_file = ["P"]

The footer and the help overlay show the keys as they are bound. tuios warns when a review key is one of the overlay's own keys, and tuios keybinds doctor lists it under REVIEW KEYS.

The compare view lists the attempts of the fan, with what each changed against the fan's base and its last check:

KeysWhat it does
j / kMove
enterReview that attempt; esc comes back
mMark an attempt; two marks enable d
dDiff the two marked attempts with each other
VRun a command in every attempt (a line filled with the last one)
KKeep the attempt under the cursor: a question names what is removed, y keeps it and removes the others, any other key keeps everything
esc, q, wBack to the review

A key from send-keys or a tape may move around the review but never acts as you: a note it typed is not saved, and S, x, V, the stage keys and the keep confirmation refuse it. See Reviewing an agent's changes.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page