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

Invocation	What it does
`sinclair`	Load config and launch the GUI (opens a default window).
`sinclair mcp`	Run the Model Context Protocol server over stdio, bridging tool calls into a running GUI instance.
`sinclair notify [--title T] <message>`	Post a desktop notification.
`sinclair agent-status <state>`	Report an agent's semantic state (working/blocked/done/idle) to the running window.
`sinclair agent-hooks <install\|uninstall> [--project]`	Wire (or remove) the Claude Code lifecycle hooks that drive the status dots.
`sinclair export <in.cast> <out.gif\|mp4\|mov\|webm>`	Render a session recording to a GIF or video file.
`sinclair --toggle-quick`	Tell a running instance to summon/hide the quick terminal, then exit.

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 ✓"

Note

From inside a shell session you can also trigger notifications directly with OSC escape sequences (OSC 9 / 777 / 99) — sinclair notify is the out-of-band equivalent for tools that only have a shell command.

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

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.

Tip

Agents on the relay mesh don't need the hooks — they can report the same states with the report_status tool. See the Agent mesh.

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.

Tip

Inside the app, Export Recording (in the File menu and the command palette) runs this in the background on your most recent recording and posts a notification when the file is ready.

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

Tip

Everything sinclair does beyond launching is also reachable from inside the app — see Productivity and MCP & automation.