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.

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 for instance actions and image forms for the host picker and approved probe. File uploads and downloads live in the workbench Transfer view, 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 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 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:

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.