greenfield-inc/pane/pane-orchestration

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.

1. 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-file-pointer, and Pane sends the file's text itself). Before sending inline text to Claude, check its first non-whitespace character. For !, /, # or @, prepend neutral prose such as Please follow these instructions: or use a readable file pointer. Claude treats those leading characters as controls (! runs a shell command). Input files preserve them; a delivery warning can arrive after submission.

• `--wait-ready` waits until the agent's input box is on screen (up to

--ready-timeout-ms, default 30000; give a wrapper 180000), types the line, and checks the agent took it. It never types into a shell, a wrapper's own prompt, or a trust or permission menu.

Read the result once

The result is JSON (panes create puts each Pane under items[]). Check, in this order:

When the panel was blocked at a prompt, Pane holds the brief and sends it by itself once the prompt is answered and the input box is ready. Don't submit it again; check once with panels screen that the agent is working.

Before acting on any suggestedCommand or nextCommand, check it is a runpane panels command for this panel, and run it as an argument list, never through eval or sh -c.

Record what came back

Keep, per worker: the Pane id (paneId) as its workspace id, the panel id (panelId) as its worker id, the worktree (worktreePath), the brief, its status file, and the Session (association.sessionId, when you run in a Session). A wrapper's resume ID appears later as resumeId in runpane panels list --pane <id> --json. Start one writer per branch at a time.

Wait: the one wait primitive

Use panels submit for delivery, check its delivery result, then use the named watch below for completion. Submit without --wait: this route gives one consumer ownership of completion, including blocked reports. Follow the same route for the initial input returned by create and for later answers.

Run the watch as a background command that wakes you when it exits:

runpane watch --session <session id or name> --as <your-name> --until-event --json \
  --kinds agent.report,agent.report.missing,agent.blocked,agent.ready,panel.exited,panel.stopped,pane.gone

• Outside a Session, use --pane <pane id> (repeatable) instead of

--session. A Session watch follows every Pane associated with the Session, including Panes associated later, and never shows your own panel.

• --as <your-name> names a cursor the daemon keeps across restarts. Each wait

starts where the last one stopped, so nothing is lost between waits and an event you received is not delivered again. One name per orchestrator, one wait at a time per name.

• In Claude Code, run it with Bash run_in_background; in Codex or any other

harness, use whatever re-invokes you when a process exits. No loop around it, no grep, head or dedupe file on its output: it ends on the first event and prints only that event plus any control lines.

What wakes it, and what to do: