# Keybindings

`Ctrl+X` is the leader. It acts as a prefix: press it, then press the chord's second key. Nothing happens until that second key arrives, and `Esc` cancels. Hold the leader for a moment and a panel lists every chord available where you are.

Leader chords are written as two keys below, and every one of them is reachable on any terminal: Caudra ships no `Alt` defaults, because macOS routes Option through the input method and never reports it as Alt.

## Focus

`PageUp`, `PageDown`, `Home`, and `End` act on whatever holds the keyboard. While you are typing they belong to the composer, so `Home` and `End` move the text cursor and the page keys scroll a draft too tall to fit. When the draft fits, a page key scrolls the transcript and hands it the focus, so `Home` and `End` then reach the top and bottom of the chat.

Typing anything takes the focus back, and so does `Esc`. Clicking the transcript gives it the focus, and clicking the composer returns it. The wheel scrolls whatever the pointer is over and leaves the focus where it is. `Ctrl+U`, `Ctrl+G`, and `Ctrl+X b` scroll the transcript wherever the focus sits, and an open modal claims all four navigation keys for itself.

Anywhere a scrollbar is shown it can be dragged. Press the thumb and the surface follows the pointer, press the track anywhere else and the thumb jumps there and stays held. Hold `Alt` while dragging to cover an eighth of the distance, which is what makes a long transcript landable. Dragging the transcript bar shows which message the thumb is on.

A modal whose lines run wider than the screen wears a second bar along its bottom border, and drags the same way. `Shift+Left` and `Shift+Right` move it by a column of a table at a time, and a sideways wheel over the modal moves it too. The bar appears only while there is something off the edge to reach.

That bar carries an arrow at each end, and pressing one moves half a screen; an arrow dims once its direction is spent. The arrows are the way across on a phone: Android terminals send no sideways wheel at all, so a swipe that way reports nothing, and a tap is the only gesture left. They are deliberately easy to hit, so a press just above one still counts.

Holding `Alt` while turning the wheel scrolls four times as far. A middle-click anchors the view and scrolls it on its own, faster the further you then move the pointer from the mark, until you middle-click again or touch anything else. `ui.scrollbar` set to `false` hides the bars and with them the drag.

## General

| Key | Action |
|-----|--------|
| `Ctrl+C` | Quit / clear input (copies instead when text is selected) |
| `Ctrl+D Ctrl+D` | Exit |
| `Ctrl+P` | Command palette |
| `Ctrl+X` | Leader: lists the chords below, then runs the one you press |
| `F1` / `Ctrl+X ?` | Show keybindings |
| `Ctrl+F` | Search messages |
| `Ctrl+X y` | Copy last reply as markdown |
| `Ctrl+X r` | Review the last reply |
| `Ctrl+S` / `Ctrl+X f` | File picker |
| `Ctrl+O` / `Ctrl+X o` | Open the plan in the workbench |
| `Ctrl+X t` | Toggle plan / todo panel |
| `Ctrl+X a` | Open tasks |
| `Ctrl+X k` | Open the workflow inspector (needs `experimental.workflows`) |
| `Ctrl+X l` | Browse sessions |
| `Ctrl+X n` | Start a new session |
| `Ctrl+X v` | Toggle compact / expanded transcript |
| `Ctrl+X s` | Stash the current prompt |
| `Ctrl+X p` | Restore the newest stashed prompt |
| `Ctrl+X m` | Model picker |
| `Shift+Left` / `Shift+Right` | Pan a modal too wide for the screen left / right |
| `Ctrl+X w` | Open the workbench |

## Editing

| Key | Action |
|-----|--------|
| `Enter` | Submit prompt |
| `Tab` | Toggle BUILD/PLAN mode |
| `Ctrl+T` / `Shift+Tab` | Cycle reasoning effort |
| `/command` | Open command palette |
| `Home` / `End` | Start / end of line or transcript |
| `PageUp` / `PageDown` | Page the draft or the transcript |
| `Ctrl+U` | Scroll half page up |
| `Shift+Left` / `Shift+Right` | Pan a wide diagram left / right |
| `Ctrl+G` | Scroll to top |
| `Ctrl+X b` | Scroll to bottom |
| `Ctrl+Q` / `Ctrl+X q` | Pop queue |
| `Esc Esc` | Rewind |
| `Ctrl+X e` | Edit the prompt in the workbench |

## Text Fields

These keys work the same in every text field: the composer, a picker's filter, forms and prompts, `/btw`, and the workbench editor with its fields. Where a surface binds one of them itself, the surface wins. `/btw` keeps `Ctrl+Y` to copy the answer, and the permissions picker keeps `Ctrl+E` to edit, `Ctrl+K` to revoke, and `Ctrl+Y` to copy a rule. In a list, `Home` and `End` move the cursor in its filter, and `Ctrl+Home` and `Ctrl+End` pick the first and last item.

`Ctrl+Z` is undo everywhere, so it never suspends Caudra. A masked field, such as an API key, refuses to select all, copy, or cut. A terminal paste goes to the field that has focus. `Super` chords need a terminal that reports them, such as one with the kitty keyboard protocol.

| Key | Action |
|-----|--------|
| `Ctrl+W` / `Ctrl+Backspace` | Delete the word or path component before the cursor, or the selection |
| `Ctrl+Delete` | Delete the word or path component after the cursor, or the selection |
| `Ctrl+K` | Delete to the end of the line, or join the next line at its end |
| `Super+Backspace` | Delete to the start of the line |
| `Ctrl+A` | Select all |
| `Ctrl+Z` / `Ctrl+Y` | Undo / redo |
| `Ctrl+C` | Copy the selection, or run the surface's own action when nothing is selected |
| `Shift+Delete` | Cut the selection |
| `Ctrl+←` / `Ctrl+→` | Move by word |
| `Home` / `Super+←` | First character of the line, then column zero |
| `End` / `Ctrl+E` / `Super+→` | End of the line |
| `Ctrl+Home` / `Ctrl+End` | Start / end of the text |
| `Shift+move` | Extend the selection with any move above |
| `Shift+Enter` / `Ctrl+Enter` / `Ctrl+J` | Newline, in a field that takes more than one line |

## Pasted Text

| Key | Action |
|-----|--------|
| `Enter` | Insert newline |
| `Ctrl+V` | Put back what this editor last copied or cut |
| `Ctrl+S` | Save pasted text |
| `Esc` | Cancel editing |

## Review

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move the caret through the passage |
| `Shift+↑` / `Shift+↓` / `Shift+←` / `Shift+→` | Select part of the passage |
| `Ctrl+A` | Select the whole passage |
| `Ctrl+C` | Copy the selection |
| `Enter` | Write a note on the selection |
| `e` / `d` | Edit or delete the note under the cursor |
| `n` / `p` | Jump between notes |
| `Ctrl+S` | Send notes to the prompt |

## While Streaming

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate input history |
| `Esc Esc` | Cancel agent |
| `Enter` | Send prompt next |
| `Ctrl+X g` | Guide current run |
| `Ctrl+X x` | Stop and replace current run |

## Form

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate options |
| `F2` | Ask /btw about a pending main-agent question without answering it |
| `Enter` | Select option |
| `Esc` | Close |

## Pickers

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate |
| `Enter` | Select |
| `Esc` | Close |
| `Type` | Filter |
| `PageUp` / `PageDown` | Scroll page up / down |
| `Ctrl+Home` / `Ctrl+End` | First / last item |
| `Ctrl+U` | Scroll page up |

## Docs

| Key | Action |
|-----|--------|
| `↑` / `↓` | Scroll the page, or move through the contents or the results |
| `←` / `→` | Pan across a row too wide for the reader |
| `n` / `p` | Next or previous heading |
| `Tab` / `Shift+Tab` | Select the next or previous link on screen |
| `Enter` | Follow the link, or open the page or result; links out open in the browser |
| `Backspace` / `[` | Back to the place a link or result was opened from |
| `]` | Forward again |
| `/` | Search every page; Esc returns to the page |
| `F3` / `Shift+F3` | Next or previous search highlight |
| `c` | Contents; typing filters them, Esc clears the filter |
| `Ctrl+C` | Copy the selection, or close |
| `Esc` / `q` | Close, keeping the place for the next /docs |

## Sandbox Manager

These keys exist only with `sandboxes = true` under `[experimental]`. See [Experimental features](/docs/configuration/#experimental-features).

| Key | Action |
|-----|--------|
| `Ctrl+S` | Validate and save sandbox defaults; export preview saves as a new file |
| `Tab` / `Shift+Tab` | Move focus between sandbox list and form fields (never insert a tab) |
| `Enter` | Inspect/edit; confirmations default to Keep, not Accept |
| `Ctrl+Enter` | Apply to draft, or preview a live action for separate confirmation |
| `F2` | Choose provider, image, policy or purpose-store credential reference |
| `Esc` | Close, not cancel operations; retain live drafts; offer Save/Discard for configuration |
| `1` / `2` / `3` / `4` | Switch Instances, Profiles, Images, Providers when not editing text |
| `/` | Search the sandbox master list |
| `n` / `d` / `Delete` | Profiles: new, duplicate or stage deletion; Instances: d detaches, Delete reviews deletion |
| `g` / `t` | Browse and edit reusable Network or Transfer policies from Profiles |
| `i` / `x` | Import a strict configuration draft or preview a reference-only export |
| `c` / `r` / `a` | Compare baseline/draft/external file, reload, or save as a new private file |
| `a` / `u` / `p` / `e` | Instances: review Attach, Resume, Pause or Extend |
| `v` / `r` / `z` | Profiles: Create VM; Instances: Reconcile or explicitly Cancel create |
| `h` / `k` | Doctor; Providers: edit lifecycle credential in its purpose store |
| `i` / `b` / `g` / `l` | Images: approved offline Import, Build, GC or Inspect |
| `g` / `F4` / `F6` | Live network preview/apply; Test rules (no probe); discard action draft |
| `Ctrl+N` / `Ctrl+U` | Domain and CIDR lists: append a rule line, or clear the current line |
| `Ctrl+G` / `Ctrl+L` | Live action forms: focus the first or last field |

See [Managed Sandboxes](/docs/sandboxes/#tui-manager) for instance actions and [image forms](/docs/sandboxes/#images-and-template-catalog) for the host picker and approved probe. File uploads and downloads live in the [workbench Transfer view](/docs/workbench/#transfer), available after attaching to a sandbox. Leaving Transfer requests cancellation and waits for cleanup.

## Workbench

| Key | Action |
|-----|--------|
| `Esc` / `Ctrl+X w` | Back to the transcript |
| `Ctrl+X b` | Show or hide the sidebar |
| `Ctrl+X -` / `Ctrl+X =` | Narrow / widen the sidebar |
| `Ctrl+X 1` | Explorer |
| `Ctrl+X 2` | Source control |
| `Ctrl+X 3` | Search |
| `Ctrl+X 4` | Transfer files with the attached sandbox (needs `experimental.sandboxes`) |
| `Tab` / `Shift+Tab` | Leave the sidebar for the editor |
| `Ctrl+P` | Open a file by name |
| `F5` | Reread the tree and the repository |
| `Ctrl+X Enter` | Send the file or selection to the composer |
| `Ctrl+X .` | Open the context menu for the row or tab under the cursor |

## Context-Specific

Some pickers add extra bindings on top of the defaults:

| Context | Key | Action |
|---------|-----|--------|
| Queue | `Shift+Up` / `Shift+Down` | Move item up / down |
| Queue | `Enter` | Edit item |
| Queue | `d` / `Delete` | Delete item |
| Queue | `m` | Move unsent item to Main |
| Queue | `g` | Guide current run |
| Queue | `n` | Move prompt to Up next |
| Queue | `b` | Toggle send together |
| Queue | `.` | Open item actions |
| Queue | `r` | Replace current run |
| Commands | `Tab` | Complete command |
| Model Picker | `R` | Clear job binding |
| Session Picker | `Ctrl+N` | New session |
| Session Picker | `F2` | Move current session |
| Session Picker | `F3` | Migrate directory sessions |
| Session Relocation | `Ctrl+O` | Enter a custom destination directory |
| Session Relocation | `Ctrl+R` | Change relocation source or destination selection |
| Session Relocation | `Space` | Toggle the selected historical project usage row in bulk confirmation |
| Worktree Picker | `Ctrl+N` | New worktree |
| Worktree Picker | `Ctrl+D` | Remove the selected worktree |
| Worktree Picker | `Ctrl+R` | Refresh the worktree list |
| Worktree Picker | `Space` | Toggle carrying uncommitted changes into a new worktree |
| Session Picker | `Ctrl+R` | Rename session |
| Session Picker | `Ctrl+G` | Generate session title |
| Session Picker | `Ctrl+D` | Delete session (press twice) |
| Stash Picker | `Ctrl+D` | Delete stash entry (press twice) |
| Peer Manager | `1` / `2` / `3` | Switch Sessions / Held messages / Messages outside filter editing |
| Peer Manager | `/` | Edit the current view's filter; Enter keeps it, Esc clears it |
| Peer Manager | `Tab` / `Shift+Tab` | Switch list/detail focus, or move between This session's controls |
| Peer Manager | `Enter` | Open the selected message review, inspect a peer, or read a channel; never approve from the list |
| Peer Manager | `Enter` | In This session, remove the focused topic, switch broadcasts, or subscribe to the typed patterns |
| Peer Manager | `Ctrl+R` | Refresh peer discovery or the message history without blocking the interface |
| Peer Manager | `Ctrl+Y` | Copy the selected peer's @name or exact target outside filter editing |
| Peer Manager | `o` | Load the selected channel's older stored messages |
| Peer Manager | `s` | Subscribe to or unsubscribe from the selected topic, or switch broadcasts on or off |
| Peer Manager | `y` | Approve the current rendered message review once |
| Peer Manager | `n` | Confirm rejection of the current reviewed message |
| Peer Manager | `p` | Open This session: its name, inbound policy, subscriptions, and broadcasts |
| Peer Manager | `a` | Apply the selected policy, confirming any relaxation |
| Peer Manager | `Esc` | Cancel confirmation, clear the pattern field, or leave This session; then return to the list and close |
| Workflow Inspector | `p` | Pause the selected run |
| Workflow Inspector | `r` | Resume the selected run |
| Workflow Inspector | `s` | Stop the selected run |
| Workflow Inspector | `Tab` / `Shift+Tab` | Next or previous section |
| Workflow Inspector | `1-4` | Jump to a section |
| Workflow Inspector | `Left` / `Right` | Focus the run list or the section |
| Workflow Inspector | `Enter` | Open the row under the cursor: a phase's agents, a scratch file, or a call's prompt and result |
| Workflow Inspector | `t` | Open the transcript of the agent under the cursor |
| Workflow Inspector | `o` | Open the script the selected run executed |
| Workflow Inspector | `e` | Copy the whole run as markdown, every prompt and result included |
| Workflow Inspector | `y` | Copy the visible section |
| Workflow Inspector | `/` | Filter the run list |
| Workflow Catalog | `Enter` | Launch a trusted workflow, or trust an untrusted one |
| Automation Inspector | `Enter` | Open the row under the cursor: a firing's trace, an action's request and result, or a JSON node |
| Automation Inspector | `Space` | Arm or disarm the selected automation |
| Automation Inspector | `e` | Edit the selected automation's state or args |
| Automation Inspector | `Ctrl+S` | Save the state or args being edited |
| Automation Inspector | `t` | Trust the selected project script at the digest shown |
| Automation Inspector | `p` | Pause or resume every automation in the session |
| Automation Inspector | `c` | Clear the selected automation's state, after confirming |
| Automation Inspector | `x` | Drop the waiting firing or outbox item under the cursor |
| Automation Inspector | `r` | Dry-run the finished firing under the cursor against the script as it is now |
| Automation Inspector | `o` | Open the script, at the failing line for a failed firing |
| Automation Inspector | `y` | Copy the firing under the cursor as markdown |
| Automation Inspector | `/` | Filter the list by name, description, or a session's title or @name |
| Automation Inspector | `Tab` / `Shift+Tab` | Next or previous section |
| Automation Inspector | `1-4` | Jump to a section |
| Automation Inspector | `Left` / `Right` | Focus the list or the section |
| Decisions | `Tab` / `Shift+Tab` | Next or previous section |
| Decisions | `1-4` | Jump to a section |
| Decisions | `Left` / `Right` | Focus the list or the detail |
| Decisions | `g` | Cycle the scope: this session, this project, every session |
| Decisions | `y` | Copy the selected decision as JSON, or the visible section |
| Decisions | `Ctrl+R` | Read the decision log again |
| Workbench Explorer | `Ctrl+X h` | Show hidden files |
| Workbench Explorer | `C` | Fold the tree back to its top level |
| Workbench Editor | `Ctrl+S` | Save the active file |
| Workbench Editor | `Ctrl+R` | Discard edits and take what is on disk |
| Workbench Editor | `Ctrl+F` / `Ctrl+G` | Find in file / go to line |
| Workbench Editor | `F3` / `Shift+F3` | Next / previous match, with or without the find bar |
| Workbench Editor | `Ctrl+V` | Put back what the workbench last copied or cut |
| Workbench Editor | `Ctrl+X x` | Cut the selection |
| Workbench Editor | `Ctrl+X z` | Wrap long lines onto more rows |
| Workbench Editor | `Ctrl+PageUp` / `Ctrl+PageDown` | Previous / next tab |
| Workbench Editor | `Ctrl+X k` | Close the active tab |
| Workbench Editor | `Ctrl+X v` | Show a Markdown file rendered, or its source again |
| Workbench Source Control | `Space` | Stage or unstage the file, folder, or whole section |
| Workbench Source Control | `D` | Open the diff, or the commit under the cursor |
| Workbench Source Control | `X` | Discard changes (press twice) |
| Workbench Source Control | `T` | Switch the change sections between tree and flat |
| Workbench Source Control | `Ctrl+X ↑` / `Ctrl+X ↓` | Shrink / grow the section the cursor is in |
| Workbench Search | `Enter` | Run the search, then open the file at the match |
| Workbench Search | `Ctrl+X i` | Move between the query and the file globs |
| Workbench Search | `Ctrl+X c` | Match case |
| Workbench Search | `Ctrl+X w` | Match whole words |
| Workbench Search | `Ctrl+X r` | Read the query as a regular expression |
| Workbench Transfer | `↑` / `↓` / `k` / `j` | Move through the aligned tree |
| Workbench Transfer | `PgUp` / `PgDn` / `Home` / `End` | Move a page at a time, or to the first or last row |
| Workbench Transfer | `→` / `Enter` | Unfold a folder, open a file's diff, or run a note's action |
| Workbench Transfer | `←` | Fold the folder, or step out to the one above |
| Workbench Transfer | `C` | Fold the tree back to its top level |
| Workbench Transfer | `Tab` / `Shift+Tab` | Focus the local or the sandbox pane |
| Workbench Transfer | `Space` | Choose the row, and everything under a folder |
| Workbench Transfer | `U` / `D` | Review an upload / download of the chosen rows, or of the cursor row |
| Workbench Transfer | `A` | Approve the review on screen, exactly as shown |
| Workbench Transfer | `=` / `F5` | Compare the roots again |
| Workbench Transfer | `I` | Include or leave out ignored files until Transfer closes |
| Workbench Transfer | `.` | Skip or include dotfiles until Transfer closes |
| Workbench Transfer | `F` | Show only what differs |
| Workbench Transfer | `L` / `S` | Edit the local / sandbox root |
| Workbench Transfer | `Ctrl+U` | Clear the root being edited |
| Workbench Transfer | `Backspace` | Go back to the previous root pair |
| Workbench Transfer | `O` | Show the last transfer report |
| Workbench Transfer | `Q` | Reconcile a publication whose outcome is unknown |
| Workbench Transfer | `X` | Stop the running operation |
| Workbench Transfer | `Esc` | Close the prompt or panel, then leave Transfer once cleanup ends |

Some of these contexts belong to an [experimental feature](/docs/configuration/#experimental-features) and exist only while its switch is on:

- Peer Manager: `cross_session_messaging`
- Workflow Inspector: `workflows`
- Workflow Catalog: `workflows`
- Automation Inspector: `automations`
- Decisions: `decision_engine`
- Workbench Transfer: `sandboxes`

## Context Inheritance

Child contexts inherit their parent's bindings and add their own.

- **Pickers** is the base for: Rewind Picker, Theme Picker, Model Picker, Queue, Commands, Search, File Picker, Stash Picker, Session Picker, Session Relocation, Worktree Picker, Peer Manager, Workflow Inspector, Workflow Catalog, Automation Inspector, Decisions
- **Workbench** is the base for: Workbench Explorer, Workbench Editor, Workbench Source Control, Workbench Search, Workbench Transfer

## Overriding Keybindings

With [Lua plugins](/docs/configuration/#experimental-features) turned on, plugins and `init.lua` can rebind keys at runtime with `caudra.keymap.set` and `caudra.keymap.del`. The tables above are the built-in defaults. An override on the same key wins, unless a modal or overlay is open (help, plan form, permission prompt).

Precedence, high to low:

1. **Modal and overlay keys.** An open modal or picker consumes its keys first, so they cannot be shadowed while open.
2. **Lua overrides** from `caudra.keymap.set`. Last set wins, and binding the same key twice warns.
3. **Built-in defaults.** An override on the same key shadows them, and `caudra.keymap.del` lifts the override so the default returns. Every built-in key can be remapped this way.

Only single-key bindings can be overridden. Multi-key combinations and non-key rows (like `Type` to filter) cannot.

The `/help` modal and the splash show default labels, not live overrides, but pressing the key still runs the override.

### Recovering from a bad keymap

If an override leaves Caudra stuck (a rebound `Ctrl+C`, a modal that will not close, a plugin that throws on load), boot without Lua:

```bash
caudra --no-plugins
```

This run skips every plugin and both `init.lua` files and starts no Lua host, even with `lua_plugins` on. Every built-in tool is native, so tools still work. `caudra.toml`, `permissions.toml`, custom commands, and env files load as usual.

The default keymap lives in Rust, not Lua, so `--no-plugins` never drops it.

## Shell and images

These are input conventions, not remappable key rows:

- Prefix a line with `!` to run a shell command yourself (5 minute timeout). Use `!!` to hide the command and its output from the agent.
- `Ctrl+V` pastes an image from the clipboard into the prompt when the model supports vision. You can also paste image file paths.
- Text pastes with at least 3 lines or more than 150 characters appear as compact tokens. Focus one and press `Enter`, or click it, to edit the complete pasted text.