# The agents view

URL: https://tuios.dev/docs/keybindings/agents-view

> The agents view: part of the Keybindings of TUIOS.

This page is one part of `docs/KEYBINDINGS.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/KEYBINDINGS.md). The [Keybindings](https://tuios.dev/docs/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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#the-agents-view) for what goes in it.

| Keys                                                                                                | What it does                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctrl+b i`                                                                                          | Open the agents view                                                                                                                                                                                                                                                                                                                                          |
| `ctrl+b o`                                                                                          | Go 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 K` | Next 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 M`                                                                                          | Open the agents view on the mail for you (`m` there opens the whole mailbox)                                                                                                                                                                                                                                                                                  |

Inside it:

| Keys                                | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `j` `k`, arrows                     | Move between agents. The focus area shows the selected one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `g` `G`                             | Go to the first or last agent. When the thread is scrolled up, `G` first shows its newest lines and follows it again                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `enter`                             | Go to the agent's pane and close the view. On mail, open the thread                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `a` `A` `X` `R`                     | On a held approval: allow once, always allow, reject, reject and say why. `1` `2` `3` still work                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `r`, `i`                            | Write a reply to the agent, or to the mail. On a held approval, `r` names the keys that answer it                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `tab` `shift+tab`                   | Give 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                                                                                                                                                                                                                                                                                                                                                                                                              |
| `N`                                 | Go to the next agent that needs you, and from the top again after the last                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `space`                             | Read 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                                                                                                                                                                                                    |
| `n`                                 | Open the New agent sheet. See below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `c`                                 | On an attempt of a fan: compare the attempts. See below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `b`                                 | Show the task board, the cards grouped by stage, or the agents again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `t`                                 | On 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+right` | On a card: move it to the stage before or after                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `v`                                 | On a card its agent is done with: open the Changes view of that agent's worktree, while its pane is open                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `M`                                 | On 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                                                                                                                                                                                                                                                                                                                                        |
| `B`                                 | Show the task board as columns or as a list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `Ctrl+T`                            | On 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+X`                            | On 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](https://tuios.dev/docs/configuration/agents#the-agent-list)                                                                                                                                                                                                                                                                                                                                                                |
| `o`                                 | Open what the agent has shown, such as a TML form, on its Artifacts tab, and use it. `esc` goes back to the list                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `f`                                 | Show only what needs you, then each kind of item, then every agent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `s`                                 | Opens 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` `S`                     | Dismiss, snooze, undo, show the snoozed items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `D`                                 | Settle 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` `m`                         | Resume 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 marks                  | Allow every marked approval once, after a sheet that lists them, or reject them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `y` with marks                      | Resume every marked Resume row. `*` then `y` resumes them all                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `[` `]`                             | Switch the focus tabs: Card on the board, Thread, Changes, Artifacts, Checkpoints and Pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `J` `K`                             | Scroll 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+o`                            | Go back to the thread you opened another agent from, at the same place. Each `ctrl+o` goes back one more                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `e`                                 | Show every line of every card in the thread                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `W`                                 | Wrap 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 link                     | Open it, as a link in a pane opens. The pointer on a link underlines it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Drag over the thread                | Select 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                                                                                                                                                                                                                                                                                                                                                  |
| `F`                                 | Fold or open the group of the row under the cursor. On a folded heading, `enter` also opens it                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `v`                                 | Review 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` `left`             | On 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `esc`                               | Go 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                                                                                                                                                                                                                                                                                                                                                                   |
| `q`                                 | Close 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](https://tuios.dev/docs/configuration)                                                                                                                                                                                                                                                                                                                                             |
| `w`                                 | Hide 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                                                                                                                                                                                                                                                                                                                                                                                                  |
| `Z`                                 | Show 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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#the-agents-view).

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`.

| Field          | What it does                                                                  |
| -------------- | ----------------------------------------------------------------------------- |
| Task           | The first prompt. It is typed when the agent is ready                         |
| Agent          | The agents that run now come first, then the installed ones                   |
| Model          | Passed to the agent as `--model`. Empty uses the agent's default              |
| Where it works | A new worktree on its own branch, or this folder                              |
| Branch, Base   | The new branch, named after the task until you change it, and where it starts |
| Machine        | This machine and the linked hosts, the most free cores first                  |
| Attempts       | 1 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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#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.

```toml
[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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#approvals-from-the-inbox)), `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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#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](https://tuios.dev/docs/keybindings/agents-view#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.

| Keys                         | Where                                      | What it does                                                                                                                                                                                                                                                            |
| ---------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctrl+b v`                   | anywhere                                   | Review the focused pane's changes                                                                                                                                                                                                                                       |
| `ctrl+b O`                   | anywhere                                   | Go 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 A`                   | anywhere                                   | Open the Agents tab of the settings page, where you install, update and uninstall each harness's integration                                                                                                                                                            |
| `v`                          | agents view                                | Review the changes in the item's pane                                                                                                                                                                                                                                   |
| `z`, then `1` to `4`         | agents view                                | Snooze the item: 15 minutes, 1 hour, until 9:00 tomorrow, or until it changes; any other key cancels. On a snoozed item, wake it                                                                                                                                        |
| `u`                          | agents view                                | Undo the last dismiss, snooze or settle, within 10 seconds                                                                                                                                                                                                              |
| `D`                          | agents view                                | Settle the agent, or every marked one. Put away until it needs you                                                                                                                                                                                                      |
| `S`                          | agents view                                | Show or hide snoozed items                                                                                                                                                                                                                                              |
| `R`                          | agents view                                | Reject a held approval, or keep a plan planning, with a reason you type (`X` and `3` stay the plain reject)                                                                                                                                                             |
| `n`                          | agents view                                | Start a new agent                                                                                                                                                                                                                                                       |
| `c`                          | agents view                                | Compare the attempts of the fan under the cursor                                                                                                                                                                                                                        |
| `J`, `K`, `ctrl+d`, `ctrl+u` | agents view                                | Scroll 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                                                                                                                                           |
| `u`                          | rail agent row                             | Mark the pane's finished turn unread, for every client (not the pane in front of you)                                                                                                                                                                                   |
| `z`                          | rail agent row                             | Snooze what needs you in the pane: the agents view opens on it with the four lengths                                                                                                                                                                                    |
| `enter`                      | rail `+N at rest` line                     | Show 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)                                                                   |
| `r`                          | agents view, on a finished or errored item | Reply to the agent: the editor under the thread, queued with `enter` and typed when the agent is at rest                                                                                                                                                                |
| `r`                          | rail agent row                             | Reply to the agent, the same line in the agents view; refused while the pane waits on a prompt                                                                                                                                                                          |
| `v`                          | rail agent row                             | Review the pane's changes                                                                                                                                                                                                                                               |
| `x`                          | rail agent row with messages queued        | Drop 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]`:

| Keys                                           | What it does                                                                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `j` / `k`, arrows                              | Move by line; with the file list focused, move through the files                                                                                                                                              |
| `space`, `pgdown`, `ctrl+d` / `pgup`, `ctrl+u` | Move by a page                                                                                                                                                                                                |
| `g` / `G`                                      | First 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`)                                                                                                                                                |
| `a`                                            | Stage the hunk under the cursor (`review_stage_hunk`)                                                                                                                                                         |
| `d`                                            | Unstage the hunk under the cursor (`review_unstage_hunk`)                                                                                                                                                     |
| `A` / `D`                                      | Stage or unstage the whole file (`review_stage_file`, `review_unstage_file`)                                                                                                                                  |
| `z`                                            | Undo the last stage or unstage (`review_undo_stage`)                                                                                                                                                          |
| `s`                                            | One 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` / `right`                    | Scroll 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                                                                          |
| `tab`                                          | Focus the file list or the diff. A review opens on the diff, or on the list with `[review] focus = "files"` (see [CONFIGURATION.md](https://tuios.dev/docs/configuration/dock-and-rail#where-a-review-opens)) |
| `enter`                                        | In the file list: open that file                                                                                                                                                                              |
| `c`                                            | A note on the line under the cursor                                                                                                                                                                           |
| `C`                                            | A note on the whole hunk                                                                                                                                                                                      |
| `e`                                            | Edit the note under the cursor                                                                                                                                                                                |
| `x`                                            | Resolve (remove) the note under the cursor                                                                                                                                                                    |
| `S`                                            | Send every unsent note to the pane's agent as one message, typed when it is at rest                                                                                                                           |
| `u`                                            | Switch between the changes since the base and the uncommitted ones only                                                                                                                                       |
| `b`                                            | Diff from another base (a line, filled with the current one; empty for the default)                                                                                                                           |
| `w`                                            | The compare view, for a pane in a fan                                                                                                                                                                         |
| `r`                                            | Read the diff again                                                                                                                                                                                           |
| `esc`, `q`                                     | Close (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:

```toml
[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:

| Keys            | What it does                                                                                                                             |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `j` / `k`       | Move                                                                                                                                     |
| `enter`         | Review that attempt; `esc` comes back                                                                                                    |
| `m`             | Mark an attempt; two marks enable `d`                                                                                                    |
| `d`             | Diff the two marked attempts with each other                                                                                             |
| `V`             | Run a command in every attempt (a line filled with the last one)                                                                         |
| `K`             | Keep 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`, `w` | Back 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](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#reviewing-an-agents-changes).
