Reference

CLI reference

The shipped binary is sinclair. It dispatches on its arguments before starting the GUI, so the same binary is the terminal, the MCP server, a notifier, and a quick-terminal toggle.

Modes at a glance

sinclair

With no arguments, sinclair reads your config (Configuration) and opens a window running your login shell. Subsequent launches reuse the running app where appropriate.

sinclair mcp

Runs a Model Context Protocol server on stdio and forwards each tool call to the live terminal over Sinclair's single-instance socket. Point an MCP client (Claude Desktop, Claude Code, …) at this command to let it drive your terminal. The full tool list and setup are on the MCP & automation page.

# what an MCP client runs under the hood
sinclair mcp

sinclair notify

Posts a native desktop notification. --title (or -t) sets the title (default Sinclair); the remaining arguments form the body. This is handy for agent and build hooks that can't emit an OSC 9/777/99 escape themselves.

sinclair notify "build finished"
sinclair notify --title "CI" "tests passed ✓"

sinclair agent-status

Reports the calling pane's semantic work state back to the running window, which draws it as a colored dot on the tab and rolls it up in the Activity panel. The state is one of working, blocked (waiting on you), done, or idle. It travels over Sinclair's single-instance socket and is addressed by the SINCLAIR_PANE token that every session gets, so it lands on the right tab even from a background process. It's best-effort and never blocks — if no window is listening, it simply exits.

sinclair agent-status working
sinclair agent-status blocked
sinclair agent-status done

Optional flags let a wrapper address a specific pane or carry a session id: --pane <token>, --name <n>, and --session <id>. You rarely call this by hand — the hooks below wire it into Claude Code's lifecycle for you.

sinclair agent-hooks

Installs (or removes) the Claude Code lifecycle hooks that report status automatically, so a Claude Code session running in a pane lights up its tab as it works. It is idempotent — installing twice is a no-op — and the uninstall is surgical, touching only the entries Sinclair added.

sinclair agent-hooks install              # wire hooks in ~/.claude/settings.json
sinclair agent-hooks install --project    # scope them to this repo's .claude/settings.json
sinclair agent-hooks uninstall            # remove Sinclair's entries again
sinclair agent-hooks status               # per agent: installed / outdated / missing
sinclair agent-hooks install --agent codex # ~/.codex/hooks.json (approve with /hooks in Codex)

With no --agent it acts on every agent whose config directory exists (CLAUDE_CONFIG_DIR / CODEX_HOME are honoured). The same install is in the command palette as Install Sinclair for Agents. Each session start also tells the agent it is inside Sinclair and which pane it is in.

The hooks map Claude Code's events onto states: session start → idle, a submitted prompt → working, a notification (Claude is waiting on you) → blocked, and stop → done. Each one shells out to sinclair agent-status. See the Agent status at a glance tutorial for the full workflow.

sinclair keymap

Prints the keymap the app would use right now — defaults, plugin bindings and your settings.json, layered the same way — one row per binding: trigger, key mode (if any), action, and source (default, plugin, or settings.json:LINE). Entries that didn't take effect (a misspelled action, an unknown key, an enter_mode naming a mode nothing defines) are listed after, with their line. It reads the config directly, so no running instance is needed. --json prints the same data as one JSON object with bindings, modes, and problems arrays. See Keybindings.

sinclair keymap
sinclair keymap --json | jq '.problems'

sinclair export

Renders a session recording — a .cast captured with toggle_recording — to a shareable file. The output format is chosen by the extension: .gif needs no external tools, while .mp4, .mov, and .webm are encoded with ffmpeg (which must be on PATH).

sinclair export session.cast demo.gif
sinclair export session.cast demo.mp4 --fidelity --fps 30

Timing and layout are tunable: --fps, --speed, --idle-cap (collapse long idle gaps, default 2s), --tail, --font-px, --cols/--rows, and --theme. On macOS, --fidelity renders through the app's gpui text system for ligatures, exact fonts, and box-drawing geometry (--scale sets the device-pixel scale); other platforms fall back to the bundled software renderer.

sinclair --toggle-quick

Signals a running instance to toggle the Quake-style quick terminal, then exits. The app normally binds this to ⌘⌥T (toggle_quick_terminal); this flag exists so a Wayland compositor (which can't deliver a global hotkey to the app directly) can bind a key to it:

# example: a Sway/Hyprland-style global binding
bindsym $mod+grave exec sinclair --toggle-quick