Keybindings

Every keyboard shortcut in the Theus TUI, grouped by the context where it is active, plus how to customize them in ~/.theus/keybindings.json.

How bindings work

Theus resolves shortcuts by context: the same key can mean different things depending on what is focused (the chat prompt, an autocomplete popup, a confirmation dialog, and so on). Default bindings ship with Theus and are loaded first; your personal overrides from ~/.theus/keybindings.json are applied on top (last wins).

Modifier notation: ctrl, alt, shift, meta and cmd. A binding written with spaces, like ctrl+x ctrl+e, is a chord: press the steps in sequence. Some shortcuts (cmd+…, ctrl+shift+-) only reach the app on terminals that speak the kitty keyboard protocol; portable fallbacks are provided where possible.

Global

Active everywhere in the app.

Key	Action
`ctrl+c`	Interrupt (double-press to exit)
`ctrl+d`	Exit
`ctrl+l`	Redraw the screen
`ctrl+t`	Toggle the to-do list
`ctrl+o`	Toggle the transcript view
`ctrl+shift+o`	Toggle teammate preview
`ctrl+r`	Search command history

Chat (prompt input)

Active while you are composing a message.

Key	Action
`enter`	Submit the message
`escape`	Cancel / stop the current turn
`shift+tab`	Cycle mode (on Windows without VT mode: `meta+m`)
`meta+p`	Open the model picker
`meta+o`	Toggle fast mode
`meta+t`	Toggle thinking
`up` / `down`	Previous / next entry from history
`ctrl+_` or `ctrl+shift+-`	Undo edit
`ctrl+g` or `ctrl+x ctrl+e`	Open the external editor
`ctrl+s`	Stash the current draft
`ctrl+v`	Paste an image (Windows: `alt+v`)
`ctrl+x ctrl+k`	Kill running agents

The Chat context leaves readline editing keys (ctrl+a, ctrl+e, ctrl+f, and so on) free for cursor movement, which is why extra actions use the ctrl+x chord prefix.

Autocomplete popup

Key	Action
`tab`	Accept the suggestion
`escape`	Dismiss
`up` / `down`	Previous / next suggestion

Lists and selection

The Select context drives menus such as /model, /resume and permission prompts.

Key	Action
`up` / `k` / `ctrl+p`	Move up
`down` / `j` / `ctrl+n`	Move down
`enter`	Accept the selection
`escape`	Cancel

Confirmation dialogs

Key	Action
`y` / `enter`	Confirm
`n` / `escape`	Reject
`up` / `down`	Navigate list options
`tab`	Next field
`space`	Toggle the option
`shift+tab`	Cycle mode (permission and teams dialogs)
`ctrl+e`	Toggle the permission explanation
`ctrl+d`	Toggle permission debug info

Settings / config panel

Key	Action
`up` / `k` / `ctrl+p`	Move up
`down` / `j` / `ctrl+n`	Move down
`space`	Toggle / activate the selected setting
`enter`	Save and close
`escape`	Dismiss
`/`	Enter search mode
`r`	Retry loading usage data (only on error)

Transcript view

Key	Action
`ctrl+e`	Toggle show-all
`escape` / `q` / `ctrl+c`	Exit

History search

Key	Action
`ctrl+r`	Next match
`enter`	Execute the selected entry
`escape` / `tab`	Accept
`ctrl+c`	Cancel

Scrolling and copy

Key	Action
`pageup` / `pagedown`	Scroll one page
`ctrl+home` / `ctrl+end`	Jump to top / bottom
`ctrl+shift+c`	Copy the selection
`cmd+c`	Copy the selection (kitty-protocol terminals only)

Tabs and footer

Key	Action
`tab` / `right`	Next tab
`shift+tab` / `left`	Previous tab
`up` / `ctrl+p`	Footer indicator up
`down` / `ctrl+n`	Footer indicator down
`enter`	Open the selected footer item
`escape`	Clear the footer selection

Other dialogs

Context	Key	Action
Task	`ctrl+b`	Send a running foreground task to the background (in tmux, press twice)
Theme picker	`ctrl+t`	Toggle syntax highlighting
Attachments	`left` / `right`	Previous / next attachment
Attachments	`backspace` / `delete`	Remove the attachment
Diff dialog	`up` / `down`	Previous / next file
Diff dialog	`left` / `right`	Previous / next source
Diff dialog	`enter`	View details
Plugin dialog	`space`	Toggle the plugin
Plugin dialog	`i`	Install the plugin
Rewind / message selector	`up` / `down` / `j` / `k`	Navigate messages
Rewind / message selector	`enter`	Select the message

Reserved shortcuts

Some keys cannot be rebound because Theus handles them directly or the terminal / OS intercepts them.

Key	Why
`ctrl+c`	Interrupt / exit — hardcoded, uses double-press timing
`ctrl+d`	Exit — hardcoded
`ctrl+m`	Identical to `enter` in terminals (both send carriage return)
`ctrl+z`	Unix process suspend (SIGTSTP)
`ctrl+\`	Terminal quit signal (SIGQUIT)

On macOS, the system also intercepts cmd+c, cmd+v, cmd+x, cmd+q, cmd+w, cmd+tab and cmd+space, so binding to those is discouraged.

Customizing your bindings

Run the slash command to open (or create) your personal keybindings file:

/keybindings

This writes a fully documented template to ~/.theus/keybindings.json with every default binding, ready to edit. The file has a bindings array of context blocks:

{
  "$schema": "https://www.schemastore.org/theus-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+g": "chat:externalEditor"
      }
    }
  ]
}

Set an action to null to unbind a key. Your overrides are merged over the defaults, so you only need to list the keys you want to change. The file is watched and reloaded automatically while Theus is running.

If your keybindings.json is malformed (for example, it lacks the bindings array), Theus falls back to the defaults and reports the parse error rather than starting with no shortcuts.

Theus — local-first multimodel coding agent · Made in Peru