Skip to content

keybindings.md

Latest commit

 

History

History
75 lines (53 loc) · 3.23 KB

keybindings.md

File metadata and controls

75 lines (53 loc) · 3.23 KB
Raw

Keybindings

Edit keybindings from Settings → Keybindings. That page lists every command, its current shortcut, whether it is a default or your own, and warns about conflicts.

The same configuration lives in ~/.t3/userdata/keybindings.json on the machine running the server, if you prefer editing it directly. T3 Code writes the built-in defaults into that file on first run, and adds any new defaults on later startups unless a rule of yours already claims the command or the shortcut.

The file is a JSON array of rules.

[
  { "key": "mod+g", "command": "terminal.toggle" },
  { "key": "mod+shift+g", "command": "terminal.new", "when": "terminalFocus" }
]

Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.

Rule Shape

  • key (required): shortcut string, like mod+j, ctrl+k, cmd+shift+d
  • command (required): the command ID to run
  • when (optional): boolean expression controlling when the shortcut is active

Key Syntax

Modifiers: mod (cmd on macOS, ctrl elsewhere), cmd / meta, ctrl / control, shift, alt / option.

Examples: mod+j, mod+shift+d, ctrl+l, cmd+k.

Commands

Commands are IDs like terminal.toggle, commandPalette.toggle, preview.refresh, and chat.new. Project scripts are addressable as script.{id}.run, for example script.test.run.

The command palette searches active thread titles, projects, branches, user messages, and final agent responses across connected environments. Message matches show one labeled excerpt while keeping the thread's project, branch, and machine context visible. Message search begins after two characters and uses SQLite's ASCII case-insensitive matching.

The full command list and the current defaults are shown in Settings → Keybindings, which always matches the build you are running. Use that rather than a copied list.

Note that chat.new and chat.newLocal both create a thread through the same path. A new thread inherits the project you were in, along with model and mode selections. Branch, worktree, and environment mode always come from your configured defaults, not from the thread you were looking at. To keep a worktree, use the explicit "new thread in this worktree" action in the branch toolbar. The only difference between the two commands: with the current sidebar and more than one project, chat.new opens a project chooser first.

when Conditions

A when expression is evaluated against context keys describing the current UI state. The keys the app supplies today are terminalFocus, terminalOpen, previewFocus, previewOpen, and modelPickerOpen. The set is open and grows over time, so treat that as the current list rather than a fixed one. Any key the running app does not supply evaluates to false.

Operators: ! (not), && (and), || (or), and parentheses.

Examples:

  • "when": "terminalFocus"
  • "when": "terminalOpen && !terminalFocus"
  • "when": "!terminalFocus"

Precedence

  • Rules are evaluated in array order.
  • For a key event, the last rule where both key matches and when evaluates to true wins.
  • Precedence is across commands, not only within the same command. A later rule for a different command can take a key away from an earlier one.