/pane-orchestration

name: pane-orchestration
description: How any orchestrator drives worker agents through Pane with the runpane CLI - one Pane per feature, launching a worker as a new Pane or tab (built-in agents or a wrapper --tool-command such as agent-farm run), the one wait primitive, worker reports and status files, answering workers, resuming after a restart or sleep, showing pages beside the person, shared-checkout and port etiquette, handoff and cleanup. Use when you start, wait on, answer, or recover workers in Pane, from a Pane Session or any other harness.

Orchestrating workers in Pane

This is Pane's one guide to the mechanics of driving workers. It holds for any orchestrator in any harness: a Pane Session, a Claude Code or Codex session in a Pane terminal, or a wrapper such as Agent Farm.

Read it from anywhere with `runpane docs read --doc skills/pane-orchestration/SKILL.md`. For a command's exact flags and result shape, run `runpane agent-context --command "<command>" --json`.

Who owns what

Pane is the transport: workspaces, terminals, input delivery, events, resume. Your protocol (roles, routing, the status-file schema, question and decision IDs, approvals, review policy) stays yours; Pane carries it and never parses it. Where this guide and your protocol both speak, Pane wins on a mechanic and your protocol wins on roles, approvals and review.

Before the first command: `runpane` must be on `PATH` (or use `npx --yes runpane@latest` in its place), and `runpane doctor --json` must pass. If it fails, stop and say what failed; don't fall back to raw `git worktree` checkouts for work that belongs in a Pane.

The loop

1. Write the worker's starting message (its brief) to a file. 2. Launch the worker in the feature's Pane, delivering that file. 3. Wait with the one wait primitive. It exits when something happens. 4. On wake, read the worker's report and its status file, then act: answer it, relay a question to the person, start the next worker, or resume one. 5. Wait again.

One Pane per feature

**1 feature = 1 worktree = 1 branch = 1 Pane; every other agent for it (implementer, reviewer, follow-up reviewer, QA, fixer) is a tab in that Pane.** A new Pane creates a worktree that checks out, installs and often builds, so create one only when the work's branch has none. Split work across Panes only for independent packages, each with its own branch.

Find a feature's Pane before creating one: your own records first, then `runpane panes list --repo <repo> --json`, matching the branch (for a PR, `gh pr view <n> --json headRefName`) against `git -C <worktreePath> branch --show-current`. `panes create --branch <name>` refuses a branch another Pane has checked out (`ERR_RUNPANE_BRANCH_HAS_PANE`, naming that Pane).

Launch a worker

The feature's first worker creates its Pane; every later worker is a new tab:

# first worker: a new Pane (and worktree)
runpane panes create --repo <repo> --name <slug> [--base <ref>] [--branch <name>] \
  --agent <claude|codex> --tool-command "<agent command>" \
  --initial-input-file <brief file> --as-file-pointer \
  --source agent --no-focus --wait-ready --yes --json

# later workers: a tab in the feature's Pane
runpane panels create --pane <feature pane id> --title <role> \
  --agent <claude|codex> --tool-command "<agent command>" \
  --initial-input-file <brief file> --as-file-pointer \
  --source agent --no-focus --wait-ready --yes --json

• **Built-in agents:** leave out `--tool-command`; `--agent` picks Pane's template.
• **Wrappers:** `--tool-command` runs any launcher unchanged, for example

`"agent-farm run <profile>:<variant> --arg parent=<absolute status file> --arg source=<absolute source>"`. Pass `--agent` with the agent the wrapper runs, so Pane treats the tab as that agent from the start: readiness, delivery checks, BLOCKED and EXIT events, resume. Put every choice on the command line. A wrapper that asks before it starts the agent (Agent Farm's variant picker when the command names no variant, its workspace-trust question) holds the tab. Pane reports that as BLOCKED, and reports BUSY and READY, even before it has identified the agent behind the wrapper.

• **The brief:** `--as-file-pointer` copies the file into the worker's own

worktree, at `.pane/prompts/<timestamp>.md` (Pane adds `/.pane/prompts/` to the repository's `.git/info/exclude`, so it is never committed), and types the single line `Read and follow .pane/prompts/<file>.md` into the agent's input box, so a long brief never passes through the shell or the terminal. The path in that line is relative to the worktree, where the agent starts; the result's `promptFile` is absolute. Pane does not read the brief: check it has every field your protocol requires before you launch. Use absolute paths in it for sources, the status file, and any skill to follow (a worker in another repository has none of your skills installed).

• **Files the worker needs go with the brief.** Add `--attach <file>`

(repeatable, with `--as-file-pointer`) to copy mockups, plans or dispatch notes beside the brief; the pointer line lists the copies. A worker whose harness refuses reads outside its working directory (Claude Code with `permissions.blockReadsOutsideWorkingDirectories`, or a sandbox) can read both without a prompt. A worker in a Session's Pane also gets the Session folder as `PANE_SESSION_DIR` (read-only for built-in Claude Code); write its absolute path into the brief rather than the variable. Details, including what each agent gets, are in `docs/SESSIONS.md`, section "Worker file access".

• **Without a local git worktree** (a folder that isn't the top of a checkout,

or a WSL repo), the brief goes to `<pane-dir>/prompts/` with an absolute pointer, outside the worker's working directory. Such a worker can stop on "Read outside the working directories" and wake you with BLOCKED; send a short brief inline instead (drop `--as-