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 +:
- Modifiers:
cmd,ctrl,alt,shift(superis accepted as an alias forcmd). - Keys: the alphanumerics (
a–z,0–9); the named keysenter,tab,escape,space,backspace,delete,insert,up,down,left,right,home,end,page_up,page_down,f1–f12; and the punctuation namesplus,minus,equal,comma,period,slash,backslash,semicolon,apostrophe,grave_accent,bracket_left,bracket_right.
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 a default by binding the same trigger to a different action.
- Remove a default by binding its trigger to
unbind. - Add new shortcuts freely — including chords and plugin commands.
# 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
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"]
enter_mode:NAMEstays until Esc orexit_mode.enter_mode_once:NAMEleaves after the next key the mode binds fires; other keys leave it in place.- Modes nest. The most recently entered mode is checked first, then the ones below it, then the always-on bindings.
exit_all_modesleaves all of them. - Keys a mode doesn't bind still reach the terminal, unless the mode is declared
exclusiveinkeymode— then they are dropped, so a stray key can't type into the shell. Always-on shortcuts like ⌘T keep working either way. - A mode exists as soon as a binding names it;
keymodeis only needed for options. Mode names use letters, digits,_and-.
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.)
| Shortcut | Action | What it does |
|---|---|---|
| ⌘N | new_window | Open a new window |
| ⌘T | new_tab | Open a new tab |
| ⌘⇧T | new_os_tab | Open the OS Tabs picker — run a fresh container-backed tab |
| ⌘⇧C | attach_container | Open the Attach to Container picker — drop a shell into a running container |
| ⌘W | close_surface | Close the focused pane |
| ⌘⌥W | close_tab | Close the tab and all its panes |
| ⌘⇧W | close_window | Close the window |
| ⌘⌥⇧W | close_all_windows | Close every window |
| ⌘S | save_buffer | Save the focused terminal's buffer to a text file |
| ⌘D | new_split:right | Split the pane to the right |
| ⌘⇧D | new_split:down | Split the pane downward |
| ⌘⇧[ | previous_tab | Switch to the previous tab |
| ⌘⇧] | next_tab | Switch to the next tab |
| ⌘1…⌘9 | goto_tab:N | Jump to tab N (1-based) |
| ⌘E | tab_peek | Peek at every tab as a strip of live previews; arrows walk it, Return switches, Escape dismisses |
| ⌘⌥↑ | goto_split:up | Focus the pane above |
| ⌘⌥↓ | goto_split:down | Focus the pane below |
| ⌘⌥← | goto_split:left | Focus the pane to the left |
| ⌘⌥→ | goto_split:right | Focus the pane to the right |
| ⌘C | copy_to_clipboard | Copy the selection |
| ⌘V | paste_from_clipboard | Paste from the clipboard |
| ⇧ arrows | adjust_selection:<dir> | Extend the selection by a cell (falls through to the app when none) |
| ⌥⇧ + ←→ | adjust_selection:word_left / word_right | Extend the selection by a word (starts at the cursor) |
| ⌘⇧ + ←→ | adjust_selection:line_start / line_end | Extend the selection to the line start / end (starts at the cursor) |
| ⌘+ | increase_font_size:1 | Increase the font size |
| ⌘= | increase_font_size:1 | Increase the font size |
| ⌘- | decrease_font_size:1 | Decrease the font size |
| ⌘0 | reset_font_size | Reset the font size |
| ⌘K | clear_screen | Clear the screen and scrollback |
| ⌘F | toggle_search | Toggle the search bar |
| ⌘⇧F | toggle_semantic_search | Toggle semantic search |
| ⌘⇧E | explain_output | Explain the output (AI) |
| ⌘⇧G | compose_command | Compose a command (AI) |
| ⌘⇧B | toggle_broadcast | Toggle input broadcast to all panes |
| ⌘⇧P | command_palette | Open the command palette |
| ⌘P | quick_open | Quick open |
| ⌘⇧R | toggle_recording | Toggle session recording |
| ⌘↑ | jump_to_prompt:-1 | Jump to the previous prompt |
| ⌘↓ | jump_to_prompt:1 | Jump to the next prompt |
| ⌘⇧O | copy_command_output | Copy the last command's output (OSC 133 blocks) |
| ⌘⇧U | hints | Hint mode: label visible URLs, type to open |
| ⌘⇧Space | copy_mode | Copy mode: vi-style keyboard selection |
| ⌘⇧Y | clipboard_history | Clipboard-history picker |
| ⌘⌥F | search_all | Global search across all tabs |
| ⌘⌥E | unicode_picker | Emoji / symbol insert picker |
| ⌘⌥S | snippets | Snippet / workflow picker |
| ⌘⌥P | profiles | Launch-profile picker (opens a command tab) |
| ⌘⌥A | annotate | Annotate the current line with a note |
| ⌘⌥N | notes | Open the Notes markdown-vault surface |
| ⌘B / ⌘⌥B | sidebar:left / sidebar:right | Toggle the left / right sidebar |
| ⌘, | toggle_settings | Toggle the settings panel |
| ⌘⌥T | toggle_quick_terminal | Toggle the quick terminal |
| ⌘Q | quit | Quit 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.
| Shortcut | Sends | What it does |
|---|---|---|
| ⌘← | 0x01 | Move to start of line |
| ⌘→ | 0x05 | Move to end of line |
| ⌘⌫ | 0x15 | Delete to start of line |
| ⌥← | ESC b | Move to previous word |
| ⌥→ | ESC f | Move to next word |
| ⌥⌫ | ESC DEL | Delete previous word |
| ⌘A | select_all | Select 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) | Params | Description |
|---|---|---|
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_split | DIR: right | down | left | up | Split the focused pane in the given direction |
goto_split | TARGET: up | down | left | right | next | previous | Move 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_split | DIR: up | down | left | right | Grow the focused pane in the given direction |
goto_tab | N: 1-based index; negative counts from the end | Switch to tab N |
previous_tab | — | Switch to the previous tab |
next_tab | — | Switch to the next tab |
move_tab | DELTA: signed integer | Move 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_selection | left, right, up, down, home, end, page_up, page_down, word_left, word_right, line_start, line_end | Extend the selection's moving end (word_* / line_* start at the cursor) |
text | BYTES: C-escapes \n \r \t \e \0 \\ \xNN | Send literal bytes to the terminal |
esc | BYTES: C-escapes \n \r \t \e \0 \\ \xNN | Send an escape sequence (prefixed with ESC) to the terminal |
increase_font_size | AMOUNT (optional) | Increase the font size by AMOUNT (default 1) |
decrease_font_size | AMOUNT (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_prompt | DELTA: signed integer | Jump 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_command | PLUGIN/COMMAND | Run a command contributed by a plugin |
macro_record | — | Start or stop recording a macro |
macro | NAME | Replay 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 |
tile | LAYOUT_ID | Apply a saved tile layout |
save_layout | — | Save the current layout |
worktree_create (worktree_new) | PATH; append @branch to name the branch | Create a git worktree branched from HEAD and open it in a new tab |
worktree_open | PATH | Open an existing git worktree in a new tab |
worktree_remove | PATH | Remove a git worktree (git worktree remove) |
sidebar | SIDE: left | right; optional :PANEL id | Toggle a sidebar (optionally a specific panel) |
enter_mode | NAME | Enter a key mode until Esc or exit_mode |
enter_mode_once | NAME | Enter 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 |