Configuration

Keybindings & actions

Every command in Sinclair is an action, and any action can be bound to any key combination from your config file. Sinclair ships with a sensible default keymap so it works the moment you launch it, but nothing is fixed: override a default, remove one you never use, or invent entirely new shortcuts — including chords and bindings that drive plugin commands. Changes take effect the instant you save the file.

Syntax

Keybindings live in your settings file ($XDG_CONFIG_HOME/sinclair/settings.json or ~/.config/sinclair/settings.json). Each binding is one entry in the keybind array:

"keybind": ["trigger=action"]   // optionally with a :param

The keybind array takes as many entries as you like. A trigger is one or more modifiers and a key, joined with +:

Note

cmd is Command on macOS and Ctrl on Linux/Windows. Write your bindings with cmd and they map to the platform's primary modifier automatically.

Chain keys into a chord with > — the binding fires only when the keys are pressed in sequence (for example ctrl+a>n means "press ⌃A, then N").

keybind = cmd+t=new_tab
keybind = cmd+shift+d=new_split:down
keybind = ctrl+a>n=next_tab

Customizing

Your bindings are merged on top of the defaults, so you only declare what you want to change:

# Override: make Cmd+T open a split instead of a tab
keybind = cmd+t=new_split:right

# Unbind: reclaim Cmd+K for the shell
keybind = cmd+k=unbind

# Chord: leader key for jumping to the first tab
keybind = ctrl+b>1=goto_tab:1

# Bind a plugin command
keybind = cmd+shift+j=plugin_command:git/status
Tip

Sinclair watches your config file. Edits to your keybindings apply live the moment you save — no restart needed.

Key modes

A key mode is a named set of bindings that only applies while the mode is entered. Prefix a trigger with mode/ to put the binding in that mode; bind something to enter_mode:NAME to get into it. While a mode is active a pill in the bottom-right corner names it, and Esc always leaves the innermost mode.

"keybind": [
  // ⌘⌥R enters resize mode…
  "cmd+alt+r=enter_mode:resize",
  // …where the bare arrows move the divider until Esc
  "resize/left=resize_split:left",
  "resize/right=resize_split:right",
  "resize/up=resize_split:up",
  "resize/down=resize_split:down",
  "resize/e=equalize_splits",
  "resize/enter=exit_mode",

  // A tmux-style prefix: ⌃A, then one key, then back to normal
  "ctrl+a=enter_mode_once:tmux",
  "tmux/c=new_tab",
  "tmux/n=next_tab",
  "tmux/p=previous_tab"
],
// Optional: declare a mode to set options on it
"keymode": ["resize:exclusive"]

Seeing and changing the keymap

sinclair keymap prints every effective binding — trigger, mode, action, and where it came from (default, plugin, or settings.json:LINE) — followed by every entry that didn't take: misspelled actions, bad triggers, an enter_mode naming a mode nothing defines. Add --json for a machine-readable copy. The palette's Show Keymap opens the same listing in a tab.

The palette's Change Shortcut… picks an action, then records the next key combination you press and writes it to settings.json (comments and formatting kept). If the combination already does something else it says what and asks before replacing it. The action's previous shortcut is removed, defaults included.

Default keybindings

These bindings are active out of the box. (⌘ is Command on macOS and Ctrl on Linux/Windows.)

ShortcutActionWhat it does
⌘Nnew_windowOpen a new window
⌘Tnew_tabOpen a new tab
⌘⇧Tnew_os_tabOpen the OS Tabs picker — run a fresh container-backed tab
⌘⇧Cattach_containerOpen the Attach to Container picker — drop a shell into a running container
⌘Wclose_surfaceClose the focused pane
⌘⌥Wclose_tabClose the tab and all its panes
⌘⇧Wclose_windowClose the window
⌘⌥⇧Wclose_all_windowsClose every window
⌘Ssave_bufferSave the focused terminal's buffer to a text file
⌘Dnew_split:rightSplit the pane to the right
⌘⇧Dnew_split:downSplit the pane downward
⌘⇧[previous_tabSwitch to the previous tab
⌘⇧]next_tabSwitch to the next tab
⌘1…⌘9goto_tab:NJump to tab N (1-based)
⌘Etab_peekPeek at every tab as a strip of live previews; arrows walk it, Return switches, Escape dismisses
⌘⌥↑goto_split:upFocus the pane above
⌘⌥↓goto_split:downFocus the pane below
⌘⌥←goto_split:leftFocus the pane to the left
⌘⌥→goto_split:rightFocus the pane to the right
⌘Ccopy_to_clipboardCopy the selection
⌘Vpaste_from_clipboardPaste from the clipboard
⇧ arrowsadjust_selection:<dir>Extend the selection by a cell (falls through to the app when none)
⌥⇧ + ←→adjust_selection:word_left / word_rightExtend the selection by a word (starts at the cursor)
⌘⇧ + ←→adjust_selection:line_start / line_endExtend the selection to the line start / end (starts at the cursor)
⌘+increase_font_size:1Increase the font size
⌘=increase_font_size:1Increase the font size
⌘-decrease_font_size:1Decrease the font size
⌘0reset_font_sizeReset the font size
⌘Kclear_screenClear the screen and scrollback
⌘Ftoggle_searchToggle the search bar
⌘⇧Ftoggle_semantic_searchToggle semantic search
⌘⇧Eexplain_outputExplain the output (AI)
⌘⇧Gcompose_commandCompose a command (AI)
⌘⇧Btoggle_broadcastToggle input broadcast to all panes
⌘⇧Pcommand_paletteOpen the command palette
⌘Pquick_openQuick open
⌘⇧Rtoggle_recordingToggle session recording
⌘↑jump_to_prompt:-1Jump to the previous prompt
⌘↓jump_to_prompt:1Jump to the next prompt
⌘⇧Ocopy_command_outputCopy the last command's output (OSC 133 blocks)
⌘⇧UhintsHint mode: label visible URLs, type to open
⌘⇧Spacecopy_modeCopy mode: vi-style keyboard selection
⌘⇧Yclipboard_historyClipboard-history picker
⌘⌥Fsearch_allGlobal search across all tabs
⌘⌥Eunicode_pickerEmoji / symbol insert picker
⌘⌥SsnippetsSnippet / workflow picker
⌘⌥PprofilesLaunch-profile picker (opens a command tab)
⌘⌥AannotateAnnotate the current line with a note
⌘⌥NnotesOpen the Notes markdown-vault surface
⌘B / ⌘⌥Bsidebar:left / sidebar:rightToggle the left / right sidebar
⌘,toggle_settingsToggle the settings panel
⌘⌥Ttoggle_quick_terminalToggle the quick terminal
⌘QquitQuit Sinclair

macOS-only readline keys

On macOS, Sinclair maps the familiar Cocoa text-navigation shortcuts to the control sequences a readline shell expects, so line editing feels native.

ShortcutSendsWhat it does
⌘←0x01Move to start of line
⌘→0x05Move to end of line
⌘⌫0x15Delete to start of line
⌥←ESC bMove to previous word
⌥→ESC fMove to next word
⌥⌫ESC DELDelete previous word
⌘Aselect_allSelect all terminal text

Action catalog

Every action you can bind, with its config string and any parameters. Parameters follow the action after a colon (for example new_split:right). Where an action lists an alias, either name works in your config.

Action (config string)ParamsDescription
new_window—Open a new window
new_tab—Open a new tab
close_surface—Close the focused pane
close_tab—Close the tab and all its panes
close_window—Close the window
close_all_windows—Close every window
new_splitDIR: right | down | left | upSplit the focused pane in the given direction
goto_splitTARGET: up | down | left | right | next | previousMove focus to an adjacent or sequential pane
zoom_split (toggle_split_zoom)—Toggle zoom on the focused pane
equalize_splits—Reset all split ratios to equal
resize_splitDIR: up | down | left | rightGrow the focused pane in the given direction
goto_tabN: 1-based index; negative counts from the endSwitch to tab N
previous_tab—Switch to the previous tab
next_tab—Switch to the next tab
move_tabDELTA: signed integerMove the current tab by DELTA positions
tab_peek (peek_tabs)—Toggle the tab peek: live miniatures of every tab, in a strip under the tab bar
copy_to_clipboard (copy)—Copy the selection
copy_command_output (copy_last_output)—Copy the last command's output between OSC 133 prompt marks
hints (open_url_hint)—Enter hint mode: label visible URLs, type a label to open
copy_mode (toggle_copy_mode)—Toggle vi-style keyboard selection
clipboard_history (paste_history)—Open the clipboard-history picker
search_all (global_search)—Fuzzy search recent output across all tabs
unicode_picker (insert_emoji)—Insert an emoji or symbol
snippets (workflows)—Insert a saved snippet into the focused pane
profiles (profile_picker)—Open a named launch profile in a new tab
annotate—Pin a note to the current line
notes—Open the Notes markdown-vault surface
paste_from_clipboard (paste)—Paste from the clipboard
select_all—Select all terminal text
adjust_selectionleft, right, up, down, home, end, page_up, page_down, word_left, word_right, line_start, line_endExtend the selection's moving end (word_* / line_* start at the cursor)
textBYTES: C-escapes \n \r \t \e \0 \\ \xNNSend literal bytes to the terminal
escBYTES: C-escapes \n \r \t \e \0 \\ \xNNSend an escape sequence (prefixed with ESC) to the terminal
increase_font_sizeAMOUNT (optional)Increase the font size by AMOUNT (default 1)
decrease_font_sizeAMOUNT (optional)Decrease the font size by AMOUNT (default 1)
reset_font_size—Reset the font size to the configured default
scroll_page_up—Scroll up one page
scroll_page_down—Scroll down one page
scroll_to_top—Scroll to the top of the scrollback
scroll_to_bottom—Scroll to the bottom (live output)
jump_to_promptDELTA: signed integerJump to a prompt relative to the current one
clear_screen—Clear the screen and scrollback
toggle_search—Toggle the search bar
toggle_semantic_search—Toggle semantic search
explain_output—Explain the output (AI)
compose_command—Compose a command (AI)
plugin_commandPLUGIN/COMMANDRun a command contributed by a plugin
macro_record—Start or stop recording a macro
macroNAMEReplay the named macro
command_palette—Open the command palette
quick_open—Quick open
toggle_settings (open_settings)—Toggle the settings panel
show_help (help)—Show the help screen
toggle_fullscreen—Toggle fullscreen
minimize_window (minimize)—Minimize the window
zoom_window—Zoom (maximize) the window
hide_all (toggle_visibility)—Hide or show all windows
bring_all_to_front—Bring all windows to the front
return_to_default_size (reset_window_size)—Restore the window to its default size
use_as_default—Save the current layout as the default
change_tab_title—Rename the current tab
change_terminal_title—Rename the current terminal
toggle_read_only—Toggle read-only mode for the pane
toggle_broadcast (broadcast_input)—Toggle input broadcast to all panes
toggle_recording (record_session)—Toggle session recording
export_recording (export_recording:mp4)—Export the latest recording to a GIF (or MP4 with :mp4)
save_buffer—Save the focused terminal's buffer (scrollback + screen) to a text file
toggle_quick_terminal (quick_terminal)—Toggle the quick terminal
sandbox_shell—Open a shell in this project's shared sandbox, starting or building it first
toggle_sandbox—Turn the shared sandbox on or off for this project (writes sandbox-enabled)
sandbox_start—Bring the sandbox container up without opening a pane
sandbox_stop—Stop the sandbox container; panes inside it end with it
sandbox_rebuild—Recreate the sandbox from current settings, discarding anything outside the project
sandbox_status—Show the sandbox in the Containers panel
tileLAYOUT_IDApply a saved tile layout
save_layout—Save the current layout
worktree_create (worktree_new)PATH; append @branch to name the branchCreate a git worktree branched from HEAD and open it in a new tab
worktree_openPATHOpen an existing git worktree in a new tab
worktree_removePATHRemove a git worktree (git worktree remove)
sidebarSIDE: left | right; optional :PANEL idToggle a sidebar (optionally a specific panel)
enter_modeNAMEEnter a key mode until Esc or exit_mode
enter_mode_onceNAMEEnter a key mode for one bound key
exit_mode—Leave the innermost key mode
exit_all_modes—Leave every key mode
show_keymap (keymap)—Open a tab listing every effective binding
change_shortcut—Pick an action and record a new shortcut for it
quit—Quit Sinclair
unbind—Remove a default binding for this trigger