/coordinate-agents

name: coordinate-agents
description: Drive another Sidecar-managed agent from a shell — discover targets, create the layout, start a provider, prompt and wait, read before sending keys, broadcast to every live agent, and stay out of the user's way. Use when you need a second agent to review a diff, run a long task in parallel, tell every live agent something, or when a coordinated agent comes back blocked. Covers sidecar agent list/get/start/prompt/wait/read/send-keys/broadcast and the refusal codes they return.
user-invocable: false

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:

| Code | Meaning | | --- | --- | | `agent_pane_busy` | the pane is running a command, an editor, another agent, or is in copy mode. There is no `--force`; wait or use a different shell. | | `agent_kind_mismatch` | a different provider owns the pane. | | `agent_start_failed` | the process exited befo