Tutorial

Agent status at a glance

When you're running more than one agent, the hardest part isn't the work — it's knowing which one needs you. Sinclair gives every pane a semantic status dot: working, blocked, done, or idle. This walkthrough wires Claude Code's lifecycle hooks so that dot updates itself, then shows how to report status from anything else — a script, a build, or an agent on the mesh.

1. What the dots mean

Each tab carries a colored dot, and the Activity sidebar panel (the ◉ icon on the activity bar) rolls every tab up into one "who's blocked, working, or done" view — click a row to focus that tab. When a pane reports an agent state, its dot follows that state:

A pane that isn't reporting agent status falls back to the terminal's own signals — 🔴 for a bell or notification, 🟡 while a foreground command runs, 🟢 when idle — so the Activity panel is useful for plain shells too.

2. Install the Claude Code hooks

One command wires Claude Code to report its state automatically:

sinclair agent-hooks install

That writes a few hook entries into your Claude Code settings (~/.claude/settings.json). It's idempotent — running it again changes nothing — and the uninstall is surgical, touching only the entries Sinclair added. To scope the hooks to just the current repository instead, add --project (they land in the repo's .claude/settings.json, which you can commit so your whole team gets them):

sinclair agent-hooks install --project

3. See it work

Start a Claude Code session in a pane and give it a task. Watch the tab: the dot goes 🟡 working the moment you submit a prompt, flips to 🔴 blocked if Claude stops to ask you something, and settles on 🔵 done when the turn ends. Open the Activity panel and you can see that across every tab at once — the whole point when three agents are running and only one of them is stuck on a question for you.

4. What actually got wired

No magic — the hooks just map Claude Code's lifecycle events onto states, each one shelling out to sinclair agent-status:

The report travels over Sinclair's single-instance socket and is addressed by a SINCLAIR_PANE token that every session gets in its environment — that's how the status lands on the right tab even when it comes from a background hook process.

5. Report status from anything

The hooks are just a convenience wrapper. Any command can report a state directly, which is handy for a long build, a deploy script, or a coding tool that isn't Claude Code:

sinclair agent-status working
long-build-or-deploy
sinclair agent-status done

It's best-effort and never blocks — if no window is listening it just exits. Optional flags let a wrapper target a specific pane or thread a session id: --pane <token>, --name <n>, --session <id>. See the CLI reference.

6. Status on the mesh

Agents launched by the relay don't need the hooks at all — they report the same states over the bus with the report_status tool, and their status shows up in the Relay panel alongside the roster. Even better, one agent can wait on another's status — the reviewer calls the wait_status tool to park until both workers finish, then reviews exactly once:

# the reviewer's tool calls, not shell commands
wait_status(name: "frontend", status: "done")
wait_status(name: "backend",  status: "done")

wait_status blocks for free on the shared wake signal and returns the status the moment it's reached (or on timeout — call again to keep waiting). It turns "are you done yet?" polling into a single cheap call.

7. Removing the hooks

Changed your mind, or want them out of a repo? The uninstall removes only Sinclair's entries:

sinclair agent-hooks uninstall
sinclair agent-hooks uninstall --project   # the project-scoped ones

Where to next