Using Sinclair

Productivity

Beyond drawing a fast grid, Sinclair ships the features that make day-to-day terminal work quicker: searching scrollback and every tab at once, following links and selecting text from the keyboard, grabbing a command's output in one keystroke, fuzzy pickers for snippets/profiles/clipboard history/emoji, regex output triggers, secret redaction, per-line timestamps and annotations, recording and export, and a drop-down quick terminal always a keystroke away.

Search

Press ⌘F (toggle_search) to open an in-place search overlay over the current pane's scrollback. As you type, every match is highlighted live and the view scrolls to the nearest hit. The query is fully editable — a caret tracks your position and the cursor keys move through it — and a case toggle switches between case-insensitive and case-sensitive matching. Use the next/previous controls to walk through matches in order; press ⎋ to dismiss the overlay and return to the buffer.

Semantic search

⌘⇧F (toggle_semantic_search) searches at a higher level: instead of matching raw text lines, it searches across logical prompt/output blocks — each command you ran and the output it produced. This makes it easy to find "the command that printed this" rather than scrolling line by line.

Note

Semantic search relies on knowing where commands begin and end, so it requires shell integration (below) to be active.

Shell integration

Shell integration is on by default (the shell-integration config key). Sinclair injects OSC 133 prompt marks and OSC 7 working-directory reporting into zsh, bash, and fish purely through environment variables — it never edits your .zshrc, .bashrc, or fish config. Those marks let Sinclair understand the structure of your session, which powers jump-to-prompt, working-directory inheritance for new tabs and splits, semantic search, and the pacing of macro replay.

Note

The integration is transparent and reversible: it is just an environment injection, so nothing is written to your shell startup files and setting shell-integration = false turns it off completely.

Autosuggestions & completion

As you type a command, Sinclair suggests how to finish it. The default is fish-style inline ghost text: a dimmed completion appears past the cursor, and → or End accepts it. Suggestions are drawn from your captured command history, a built-in list of common commands, and filesystem paths under the working directory, ranked by the local assist model. Nothing leaves your machine.

Three more behaviors are available, each toggled independently:

Completion popup — a dropdown of ranked candidates under the cursor; ↑/↓ to move, Enter to accept, Esc to dismiss.
Tab-cycle — press Tab to cycle through inline completions instead of forwarding Tab to the shell.
AI suggestions — when nothing local matches, ask Claude for the next command (requires AI enabled).

Config key	Default	What it does
`autosuggest-ghost`	`true`	Inline ghost text; accept with `→`/`End`
`autosuggest-popup`	`false`	Completion dropdown under the cursor
`autosuggest-tab`	`false`	`Tab` cycles completions
`autosuggest-ai`	`false`	Claude fallback when nothing local matches
`autosuggest-history`	`true`	Suggest from command history
`autosuggest-commands`	`true`	Suggest from the common-command list
`autosuggest-paths`	`true`	Complete filesystem paths
`autosuggest-assist`	`true`	Rank with the local assist model

Note

Autosuggestions read the line you're typing from the shell-integration input mark, so they need shell-integration on (the default) with zsh or bash. Fish provides its own native autosuggestions.

Jump to prompt

With shell integration active, ⌘↑ and ⌘↓ (jump_to_prompt:-1 and jump_to_prompt:1) move the viewport between shell prompts recorded in the scrollback. This is the fastest way to skip back over a long block of output to the command that produced it, or forward again to the latest prompt.

Command blocks

Because shell integration marks where each command's output begins and ends, Sinclair can treat the space between two prompts as a "block". ⌘⇧O (copy_command_output) copies the output of the most recent finished command straight to the clipboard — the rows between the two newest prompt marks, or the last prompt to the bottom while a command is still running. No selecting or scrolling: run a command, then grab exactly what it printed.

Hint mode

⌘⇧U (hints) labels every visible URL with a short home-row keystroke, Vimium-style. Type a label to open that link in your browser — bare www.… domains get an https:// scheme automatically. Backspace corrects a mistyped label; ⎋ or any impossible prefix cancels. It's the fastest way to follow a link without reaching for the mouse.

Copy mode

⌘⇧Space (copy_mode) drops a vi-style keyboard cursor onto the viewport and scrollback so you can select text without touching the mouse. Movement follows vi conventions:

h j k l or the arrow keys — move the cursor (it scrolls the view when it leaves the screen)
w / b — step a column; 0 / $ — line start / end; g / G — top / bottom
v — begin a selection; move to extend it
y or Enter — yank the selection (redacted, see below) and exit; ⎋ — exit

Smart selection

Double-clicking selects the whole meaningful token under the pointer — a URL, an email address, a filesystem path, or a git-style hex hash — instead of a single whitespace-delimited word, falling back to word selection when there's no token there. It's on by default; set smart-select = false to restore plain word selection. Triple-click still selects the whole logical line.

Global search across tabs

Where ⌘F searches the current pane, ⌘⌥F (search_all) opens a fuzzy picker over recent output from every tab. Type to filter across all your sessions at once; each result is labelled with its tab number, and choosing one focuses that tab. Ideal for "which window did I run that in?"

Macros

A macro records a sequence of typed commands and replays them on demand. The macro_record action starts and stops capturing the commands you type; while recording, a floating pill shows the state with a red ● REC indicator. Replay a saved macro with the macro:NAME action, bound to a key of your choosing.

Macros are stored as plain text under ~/.config/sinclair/macros/<name>.macro — one command per line, with # comment lines — so you can edit them by hand or check them into version control. Replay paces itself off shell-integration prompt marks, waiting for each command's prompt before sending the next rather than blasting them all at once.

// ~/.config/sinclair/settings.json
{
  "keybind": [
    "cmd+shift+m=macro_record",
    "cmd+shift+1=macro:deploy"
  ]
}

# ~/.config/sinclair/macros/deploy.macro
# one command per line
git pull --rebase
cargo build --release
./scripts/deploy.sh

Session recording

Recording captures a pane to an asciinema v2 .cast file. Toggle it with toggle_recording (default ⌘⇧R); a blue indicator shows while capture is running. Play the result back with asciinema play <file>.cast or embed it on a page.

Tip

Recording and macros are two distinct features. Recording produces a .cast screencast of everything that happened in a pane; macros replay a list of commands you typed. Use recording to show a session, macros to repeat one.

Exporting a recording

A .cast plays in asciinema, but for a README, a chat, or a pull request you usually want a GIF or a video. Export Recording — in the File menu and the command palette, as export_recording — renders your most recent recording in the background and posts a notification when the file is ready. GIF needs no external tools; MP4 needs ffmpeg on your PATH.

The same renderer is available from the command line as sinclair export <in.cast> <out.gif|mp4|mov|webm>, with controls for frame rate, playback speed, idle-gap collapsing, size, and theme. On macOS it can render through the app's own text system (--fidelity) so the exported frames carry the same ligatures, fonts, and crisp box-drawing you see in the terminal. See the CLI page for the full option list.

Saving the buffer

Save Buffer — in the File menu and the command palette, as save_buffer (default ⌘S) — writes the focused terminal's whole buffer to a plain text file. It captures every scrollback row plus the live screen, independent of what you have selected or scrolled to, so you get the full session rather than just the visible viewport. A native save dialog opens in the terminal's working directory with a filename suggested from the tab title; the file is written in the background and a notification confirms when it's saved.

Notifications

Commands can raise native desktop banners. A program can emit OSC 9, OSC 777, or OSC 99 escape sequences itself, or you can post a banner from the command line with sinclair notify [--title T] <message> — handy for agent hooks and scripts that cannot emit an escape sequence directly. See the CLI page for sinclair notify.

When a background tab posts a notification, it shows a yellow attention dot until you focus it, so you can see at a glance which session needs you.

Quick terminal

The quick terminal is a Quake-style drop-down pane that slides in over your screen and tucks away again. Toggle it with ⌘⌥T (toggle_quick_terminal). On Wayland, where a global hotkey is owned by the compositor, you can summon it from a compositor keybind that runs sinclair --toggle-quick — this signals the running instance and exits. See the CLI page for that flag.

Snippets & workflows

Save frequently-typed commands as snippets and recall them from a fuzzy picker. Each snippet config entry is label | command; ⌘⌥S (snippets) opens the picker, and choosing one inserts the command into the focused pane so you can edit it before pressing Enter.

// ~/.config/sinclair/settings.json
{
  "snippet": [
    "deploy | git push origin main",
    "logs | kubectl logs -f deploy/api"
  ]
}

Launch profiles

Profiles are named launch setups — an SSH host, a REPL, a project environment. Each profile entry is label | command; ⌘⌥P (profiles) opens a picker, and choosing one opens a new tab running that command.

// ~/.config/sinclair/settings.json
{
  "profile": [
    "prod | ssh prod.example.com",
    "repl | python3"
  ]
}

Clipboard history

Every copy is recorded in a ring of recent entries (after redaction, below). ⌘⇧Y (clipboard_history) opens a fuzzy picker over them; choose one to paste it into the focused pane. Handy for pulling back something you copied three commands ago.

Unicode & emoji picker

⌘⌥E (unicode_picker) opens a searchable list of common emoji and symbols — arrows, math signs, box glyphs, and more — each named so you can fuzzy-find it. Pick one and Sinclair sends the glyph to the focused pane.

Output triggers

Triggers watch a pane's output and fire a desktop notification when a line matches a regular expression. Each trigger entry is a regex, optionally followed by | Title for a custom notification title. The matched line becomes the notification body. Useful for surfacing build failures or long-running jobs that finish while you're in another window.

// ~/.config/sinclair/settings.json
{
  "trigger": [
    "error|Build failed",
    "\\bDONE\\b | Job finished"
  ]
}

Secret redaction

Keep API keys and tokens off your clipboard. Each redact entry is a regex; anything it matches is masked with bullets (•) before the text ever reaches the clipboard — on an explicit copy, copy-on-select, copy-command-output, or a copy-mode yank alike.

// ~/.config/sinclair/settings.json
{
  "redact": [
    "sk-[A-Za-z0-9]{20,}",
    "ghp_[A-Za-z0-9]{36}"
  ]
}

Line timestamps

Set "timestamps": true to show a faint relative time (5s, 2m, 1h, 3d) beside each scrollback row, so you can see how long ago a line was printed. Times are captured as rows scroll into history and travel with the content.

Line annotations

⌘⌥A (annotate) pins a note to the current line: a small dialog takes the text, and it's drawn as a pill in that row's left gutter. Notes are keyed to a stable line sequence, so they scroll with the content and survive until the line falls off the scrollback — good for marking "the error is here" while you work.

Pane badges

A badge is a faint watermark drawn in each pane's corner. Set badge to any text; {cwd} and {host} are substituted per pane, so a badge like {host} · {cwd} keeps context visible at a glance.

Activity dashboard

The Activity sidebar panel (the ◉ icon on the activity bar) rolls every tab up to a status dot — who's blocked, working, done, or idle at a glance across your shell and agent panes. When an agent reports its state (see Agent status below) its dot follows that: 🔴 blocked, 🟡 working, 🔵 done, 🟢 idle. Otherwise the dot falls back to the terminal's own signals — 🔴 attention (a bell or an OSC 9 notification fired), 🟡 a foreground command is running, 🟢 idle. Click a row to focus that tab.

Agent status

Coding agents (Claude Code, Codex, and the rest) can report their state back to Sinclair so it shows up as a colored dot on the tab and in the Activity panel: working, blocked (waiting on you), done, or idle. Run sinclair agent-hooks install once to wire the Claude Code lifecycle hooks (add --project to scope it to the current repo); sinclair agent-hooks uninstall removes them again. Agents on the mesh can also call the report_status and wait_status tools to coordinate, and their state appears in the Relay panel. The Agent status at a glance tutorial walks through the whole setup.

Clipboard

Copy with ⌘C and paste with ⌘V. Enable copy-on-select to automatically copy any selection the moment you make it, and middle-click-paste to paste the current selection with a middle click (X-style). Remote programs can set your clipboard through OSC 52, and clipboard-paste-protection warns you before pasting content that looks risky — for example multi-line text or shell control characters. All copy paths honor secret redaction and feed clipboard history (both above).