Keybinds

Keybinds (keyboard shortcuts) let you customize how you interact with the opencode terminal user interface. You can rebind default shortcuts, create new shortcuts for custom commands, and configure navigation patterns.

Configuration

tip

Keybinds are defined in tui.json, not opencode.json. Make sure you edit the right file.

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p",
    "switch_agent": "tab",
    "variant_cycle": "ctrl+t"
  }
}

Using OPENCODE_TUI_CONFIG

If your tui.json is in a non-standard location:

export OPENCODE_TUI_CONFIG=/path/to/custom/tui.json

Leader Key

The leader key is a prefix key that creates namespaced multi-key shortcuts. Press and release the leader key, then press the next key to trigger the action.

{
  "keybinds": {
    "leader": "ctrl+x"
  }
}

Leader Timeout

The leader_timeout setting controls how long (in milliseconds) opencode waits for the second key after the leader is pressed:

{
  "keybinds": {
    "leader": "ctrl+x",
    "leader_timeout": 2000
  }
}

note

If no second key is pressed within the timeout, the leader key press is discarded.

Default Keybindings

Leader Prefix Shortcuts (Ctrl+X by default)

All shortcuts below use the leader key as a prefix unless otherwise noted.

Shortcut	Action	Description
Leader + C	compact	Toggle compact mode
Leader + E	editor	Open current file in external editor
Leader + Q	exit	Quit opencode
Leader + X	export	Export conversation to markdown
Leader + M	models	Open model picker
Leader + N	new	Start a new session
Leader + R	redo	Redo last undone action
Leader + L	sessions	Show session list
Leader + T	themes	Open theme picker
Leader + U	undo	Undo last action
Leader + Down	session_down	Navigate to child session
Leader + Up	session_up	Navigate to parent session
Leader + Right	session_next	Cycle to next sibling session
Leader + Left	session_prev	Cycle to previous sibling session

Direct Shortcuts (no leader prefix)

Shortcut	Action	Description
Ctrl+P	command_list	Open command palette
Tab	switch_agent	Cycle through available agents
Ctrl+T	variant_cycle	Cycle through model variants

All Keybind Actions

Action ID	Default Binding	Description
compact	Leader + C	Toggle compact UI mode
editor	Leader + E	Open current file in system editor
exit	Leader + Q	Quit opencode
export	Leader + X	Export current session as markdown
models	Leader + M	Open model selection picker
new	Leader + N	Create a new conversation session
redo	Leader + R	Redo the last undone change
sessions	Leader + L	Show session management panel
themes	Leader + T	Open theme picker
undo	Leader + U	Undo the last change
session_down	Leader + Down	Navigate into child session
session_up	Leader + Up	Navigate to parent session
session_next	Leader + Right	Cycle to next sibling session
session_prev	Leader + Left	Cycle to previous sibling session
command_list	Ctrl+P	Open the command palette
switch_agent	Tab	Switch to the next configured agent
variant_cycle	Ctrl+T	Cycle through model variants
find	(none)	Search within the current session
scroll_up	(none)	Scroll the view up
scroll_down	(none)	Scroll the view down
page_up	(none)	Scroll up one page
page_down	(none)	Scroll down one page
goto_top	(none)	Scroll to the top of the session
goto_bottom	(none)	Scroll to the bottom of the session
copy	(none)	Copy selected text
paste	(none)	Paste from clipboard
cancel	Esc or Ctrl+C	Cancel current operation
confirm	Enter	Confirm current selection/prompt

Custom Keybind Examples

Vim-Style Navigation

{
  "keybinds": {
    "leader": "ctrl+space",
    "leader_timeout": 1500,
    "session_down": "ctrl+j",
    "session_up": "ctrl+k",
    "session_next": "ctrl+l",
    "session_prev": "ctrl+h"
  }
}

Minimalist Setup

{
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+space",
    "switch_agent": "ctrl+a",
    "variant_cycle": "ctrl+v"
  }
}

Emacs-Inspired

{
  "keybinds": {
    "leader": "ctrl+z",
    "leader_timeout": 3000,
    "undo": "ctrl+/",
    "redo": "ctrl+?",
    "find": "ctrl+s"
  }
}

Function Key Layout

{
  "keybinds": {
    "models": "f1",
    "themes": "f2",
    "sessions": "f3",
    "command_list": "f4",
    "switch_agent": "f5",
    "variant_cycle": "f6"
  }
}

Session Navigation

Session Tree Structure

Main Session (root)
├── Follow-up question (child)
│   └── Deeper investigation (grandchild)
├── Alternative approach (child)
└── Bug fix task (child)
    └── Test verification (grandchild)

Navigation Actions

Action	Description
session_down	Enter the currently selected child session
session_up	Return to the parent session
session_next	Cycle to the next sibling session
session_prev	Cycle to the previous sibling session

Example: To navigate to a child session and back:

Leader + Down  → enter child
Leader + Up    → return to parent
Leader + Right → go to next sibling
Leader + Left  → go to previous sibling

Keybind Syntax

Keys are specified as strings using the following syntax:

Pattern	Example	Description
ctrl+<key>	ctrl+p	Control key combination
alt+<key>	alt+b	Alt (Meta) key combination
shift+<key>	shift+enter	Shift key combination
<key>	tab, f1, esc	Single key (function keys, arrows, etc)
Leader + <key>	built-in	Leader prefix sequence (configurable)

Valid key names:

• Modifiers: ctrl, alt, shift, meta
• Printable keys: a-z, 0-9, space, -, =, [, ], \, ;, ', ,, ., /, `
• Special keys: tab, enter, esc, backspace, delete, home, end, pageup, pagedown, up, down, left, right
• Function keys: f1 through f24

Keybind Override Precedence

Unbinding a Default Shortcut

To disable a default keybind without replacing it:

{
  "keybinds": {
    "switch_agent": null
  }
}

Binding Multiple Keys to the Same Action

{
  "keybinds": {
    "command_list": ["ctrl+p", "f4"]
  }
}

Provide an array of key strings to bind multiple shortcuts to the same action.

Checking Active Keybinds

/help

Or from the CLI:

opencode config show

The active configuration display includes the resolved keybindings.