Coordinate Agents

Coordinating another agent

Sidecar can start and coordinate a second agent in a shell it owns. The commands are headless, target-taking, and --json from birth, so everything here works from an ordinary shell with no TUI attached.

Agent control is behind a default-off feature flag. Check first:

sidecar agent list --json

If that answers {"error":{"code":"feature_disabled",...}}, agent control is off. Ask the user to enable it (agent_control under features.flags in ~/.config/sidecar/config.json) rather than turning it on yourself.

The safe sequence

Do these in order. Each step exists because skipping it is how a coordinated agent ends up wedged, duplicated, or typing into the wrong pane.

1. Discover

sidecar shell list --json     # what shells exist
sidecar agent list --json     # which of them have a live agent, and its status

A target is a Sidecar-managed shell. A bare target first matches an exact tmux session name. An ordinary display name such as rev U3-c or Shell 3 still resolves when unique; ambiguity refuses. A missing sidecar-sh-*, sidecar-ws-* or sidecar-tp-* target never falls back to a display name. name:DISPLAY explicitly selects a unique display name, including a session-shaped one, and session:NAME selects an exact session, including literal names starting with name: or session:. agent start --target SESSION and --exact-target interpret the target as a literal exact identity. Inside a managed shell you may omit the target entirely and the command addresses SIDECAR_SHELL. Outside one, name the target.

agent list reports each live pane once, under the project that owns it, however many registered projects can see its checkout. An explicit target is searched across every project; if the same exact session identity exists in several, the project your own shell belongs to breaks the tie, so a sibling worktree resolves from a managed shell without flags. Outside a managed shell the refusal lists the projects and names the fix: --project NAME (a slug, a path, or a worktree Sidecar created, by path or basename) or --shell NAME. Display-name ambiguity always refuses until --project explicitly narrows the search. Remote commands preserve these selector rules and carry parser guards; older owners refuse before mutation and must be upgraded. The project field of a create shell / create worktree --json result is the value --project accepts.

2. Create the layout separately

agent start never creates or moves a pane. Layout is sidecar create shell's job, and keeping them apart is what makes it safe to start an agent without also rearranging the user's screen.

Use --tab, not the default placement and not --split. Without --tab, create shell opens a beside-the-session terminal split (sidecar-tp-…) — a live terminal, not a managed shell: it has no workspace row, shell list does not show it, and agent start/agent prompt refuse it as agent_not_found since there is nothing there to target. --tab is what actually adds the workspace row a coordinated agent needs.

created=$(sidecar create shell --tab --name reviewer --json)
target=$(printf '%s\n' "$created" | jq -r '.shell.session')

To start a catalog family with provider arguments in the same step, both create shell and create worktree take them after --, as agent start does, and still record the family: sidecar create worktree orchestrate --agent claude --json -- --model fable. Usage refusals under --json arrive as {"error":{"code":"usage",...}} on stderr, like every other refusal here.

From inside a worktree shell, create shell --tab --agent KIND inherits your own worktree's directory (the workspace row is placed there, not in the main checkout) — no --worktree/--cwd flag is needed.

When the managed shell should belong to one project but start elsewhere, pass both facts explicitly: sidecar create shell --project sidecar --cwd ~/code/tui --name publisher --json. --cwd never chooses project ownership and always creates a managed workspace row, even inside an existing Sidecar shell. It is refused with --split because a live terminal split has no durable shell record. Relative paths resolve from the caller's directory, ~ and ~/path resolve from the caller's home, and the directory must exist before Sidecar creates tmux or durable state. The resolved path is the shell's live cwd, recorded workDir, provider launch cwd, and cold-restore cwd.

Creating a shell does not steal the user's focus. Do not rearrange panes the user set up, and never close a target you did not create.

3. Start the provider

sidecar agent start "$target" --kind codex --timeout 30s --json

agent start reserves -- for provider arguments. Use positional TARGET for a session or ordinary display name, name:DISPLAY for an explicit name, or --target SESSION for a literal exact session (including a leading dash).

This returns only when the expected provider is positively identified and ready for input. It is not "the bytes were sent". Refusals worth knowing:

4. Prompt, and wait under one pinned target

sidecar agent prompt "$target" "Review the current diff and report only actionable findings." --wait --timeout 2m --json

--wait submits and waits as one operation, so no second command can race a replacement occupant into the gap. Things to know:

• Read the receipt before retrying. Prompt JSON adds receipt.submission (submitted, not_submitted, or unknown), receipt.wait, and the exact pinned receipt.target. The receipt is present on success and inside the error envelope on failure. A timeout after delivery remains exit 1 with error code timeout, plus submission: "submitted" and wait: "timeout"; do not send the prompt again. unknown means a write or transport may have landed and is equally unsafe to retry automatically.

• Refusals happen before any byte is written. Feature-disabled, unknown-host, missing-target, not-found, and ambiguous-target failures carry submission: "not_submitted" and wait: "not_started" too, without inventing a pane identity. A blocked target gets agent_blocked; an unidentified or stale one gets agent_not_ready; a replaced one gets agent_replaced; and a dead pane, a pane in copy mode, or a session that no longer holds exactly one pane gets agent_pane_busy. Nothing is sent in any of them.

• There is no implicit timeout. --wait requires --timeout, and so does agent wait.

• Settled means idle, done, or blocked by default. Narrow it with repeated --until done, or widen it with --until working.

• A prompt that goes nowhere is reported, not hidden. If the lifecycle does not move within 5 seconds of a prompt sent from idle or done, you get agent_prompt_stalled. The bytes were written; the agent did not react. Read the screen before you send anything else.

• Prompting an already-working agent claims nothing. Sidecar will not pretend to know which turn is which, and completion of the turn already in flight may satisfy your --wait. Wait for it to settle first if you care.

To wait without prompting — for an agent somebody else started, or after send-keys:

sidecar agent wait "$target" --until done --timeout 5m --json

The wait stays pinned to the same session, pane, pane process, tmux server, and provider. If any of those change you get agent_replaced rather than a wait that a different process quietly satisfied.