Tutorial

Run your first agent team

One agent is an assistant. A team is a supervisor delegating to workers that message each other, run in their own panes, and park for free between tasks. In about ten minutes you'll enable Sinclair's built-in relay, open a team into a tiled tab, give the supervisor a job, and watch the work flow across the bus.

1. Turn on the relay

Open Settings → AI with ⌘, and flip on two switches: Enable AI features (the master switch — off means no network activity at all) and Relay agent mesh. That's enough; the relay daemon starts on demand. The same settings round-trip through the config file:

// ~/.config/sinclair/settings.json
{
  "ai-enabled": true,
  "relay-enabled": true,
  "relay-start-on-launch": true   // optional: bring the mesh up automatically
}

With the mesh on, an AI menu appears in the menu bar and a live status dot shows next to the setting — green when the server is listening. The relay is a separate sidecar process, so a hang in the mesh can never take down your terminal.

2. Open a team the fast way

The quickest start is a built-in team. In the AI menu, open Teams ▸ web. Sinclair opens a fresh tab, tiles it into four panes, and launches an agent in each:

The lead is interactive — it hands control back to you so you can type. The three workers park: each registered under its name, joined its channel, and is now sitting in a single blocking wait call, burning no tokens until a message arrives.

3. Give the supervisor a job

Click the lead pane and type a task as you would to any coding agent — but phrased as something to delegate:

Add a dark-mode toggle to the settings page. Have frontend build the UI and
backend add the preference endpoint, then ask reviewer to check both.

The supervisor's role brief already tells it how to coordinate: it messages frontend and backend over the bus, they wake from wait, do the work in their own panes, report back, and call wait again. You watch it happen across the four panes.

4. Watch the bus

To see the cross-agent traffic in one place, open AI → Open Feed (⌘⇧I). It streams every message on the bus — who said what to whom — as a running log. This is the single view of how the team is actually talking:

lead      → #frontend   build a dark-mode toggle in settings
lead      → #backend    add GET/PUT /prefs/theme
frontend  → lead         done — toggle wired to prefs.theme
backend   → lead         done — endpoint live, tests green
lead      → reviewer     please review the frontend + backend changes

Meanwhile each pane's tab carries a status dot — working, blocked, done, or idle — so you can read the whole team at a glance without watching every pane. The Agent status tutorial covers that in depth.

5. Build your own team

The web team is just a starting point. Two ways to make your own, no TOML required:

• Add one agent at a time. AI → Agents ▸ Define Agent… opens a dialog: pick a provider, name it, and choose a role preset (frontend, backend, reviewer, devops, qa, …) or toggle Custom to describe it in your own words. Create adds it as a split and saves the definition, so it reappears under Agents ▸ to relaunch with one click.
• Design a whole team. AI → Teams ▸ Build Team… opens a builder. Pick Manual to choose a layout and add member rows (name + role + agent), or Guided to describe the team in plain English and let Claude draft it — the draft drops into the Manual form for review before you save.

6. The same thing from the CLI

The relay is a standalone binary, so you can drive all of this without the GUI — over SSH, in CI, from a script. The verbs mirror the menu:

relay start                         # start the server (background daemon)
relay launch lead --role supervisor --lead     # interactive supervisor in this pane
relay launch fe   --role frontend --background # parked worker, monitored by the server
relay launch be   --role backend  --background
relay ps                            # registered agents + background workers
relay feed --follow                 # tail the bus
relay team list                     # available teams (project → user → built-in)

A foreground launch replaces the calling shell with the agent so you can steer it; --background hands it to the server, which respawns it on crash and logs its output. Roles are reusable identities managed like git config (relay role list|info|create|edit|delete) and layered project → user → built-in, so a repo can ship its own team.

How the coordination actually works

Every agent gets an opening harness and coordinates through a small set of MCP tools it calls: register once, send/post/broadcast to message an agent / a channel / everyone, wait to block for free until messages arrive, and report_status to publish its state. A supervisor can even grow its own team with spawn. The one idea that makes it cheap:

Where to next