Tutorial

Automate your terminal with MCP

Sinclair gives you three layers of automation that stack: let an AI client drive your live window over MCP, record the keystrokes you repeat into replayable macros, and have the terminal react to its own events with triggers. This walkthrough wires up all three around one example — an agent that runs your tests, a macro for the setup you type every morning, and a trigger that notifies you when a long job fails.

1. Let an agent drive your terminal

sinclair mcp is a Model Context Protocol server. It's a thin stdio process that forwards every tool call to your already-running Sinclair window over a per-user socket — so the agent acts in the same terminal you're looking at, not a hidden headless one. First enable it in Settings → AI (⌘,):

// ~/.config/sinclair/settings.json
{
  "ai-enabled": true,
  "mcp-server-enabled": true
}

Then point a client at it. With Claude Code that's one line:

claude mcp add sinclair -- sinclair mcp

Any MCP client works — the generic form is just a command to spawn:

{
  "mcpServers": {
    "sinclair": { "command": "sinclair", "args": ["mcp"] }
  }
}

2. What the agent can do

Now the client sees a set of tools that act on your real window. Ask it something like "open a split, run the test suite there, and tell me if anything fails," and it strings these together:

And it doesn't stop at the built-ins: every plugin tool joins this list automatically. Install a plugin that queries your database or reads host stats, and the same agent driving your terminal can call it too. The full table is on the MCP & automation reference.

3. Record a macro for what you repeat

Some sequences you type by hand every day — activate a venv, export a couple of vars, start a dev server. Record them once. Run macro_record — from the command palette (⌘⇧P), or bind it to a key — type the commands, then run it again to stop and name the macro. It's stored as plain text you can version-control, and you replay it with a keybinding or macro:NAME:

// bind a recorded macro to a key, in ~/.config/sinclair/settings.json
{
  "keybind": ["cmd+ctrl+m=macro:morning-setup"]
}

Replay is paced by shell prompt marks when they're available, so a macro waits for one command's prompt before sending the next instead of dumping everything at once. Because macros are exposed as run_macro, your agent can trigger the exact same setup — one definition, two callers.

4. React to events with a trigger

The third layer runs without you or an agent asking: a plugin trigger hooks a terminal event and fires one action. The classic is "tell me when a long job fails" — a folder with a plugin.toml is the whole thing:

# plugins/alert/plugin.toml
id = "alert"
name = "Failure alert"

[[trigger]]
on = "command_finished"    # fires on OSC 133 command-end marks
when = "nonzero"           # only when the exit code is non-zero
notify = "A command failed"

Triggers can hook a bell, a title change, a notification, a process exit, a command finishing, a directory change, or a worktree being created or removed — and instead of notify they can run a command or invoke a plugin method. The exit-code and substring filters keep them from crying wolf. For the config-only cousin — regex output triggers plus notifications, timestamps, and annotations — see Triggers, notifications & annotations.

5. Record and share the result

Automated a nice workflow? Capture it. toggle_recording records the focused pane to an asciinema .cast; Export Recording as GIF/MP4 (File menu or command palette) renders it to a shareable GIF or video, carrying the same ligatures, fonts, and box-drawing you see on screen — the full walkthrough is in Record & share your terminal. From the CLI:

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

Putting it together

The three layers cover the three shapes of repetition: MCP for the work an agent should do for you, macros for the keystrokes you repeat, and triggers for the things that should just happen on their own. They share the same surface — a macro is an MCP tool, a trigger can run any command, an agent can fire a macro — so you rarely define the same thing twice.

Where to next