Orchestrator Pattern on Claude Code

This is the Claude Code side of the orchestrator pattern: what the orchestrator skill is doing under the covers when it runs here, and the gotchas to know before your first run. Everything below was checked against Claude Code 2.1.278.

Sessions talk to each other by name

Claude Code has three ways to run more than one agent, and the pattern uses one of them:

• Cross-session messaging. Separately launched sessions send each other messages by name with SendMessage. This is what the orchestrator and workers run on. It's on by default in current versions.
• Subagents. Spawned inside a session with the Agent tool, and the result comes back to the caller. Workers use these inside their slice to implement and review code.
• Agent teams. Experimental and off by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). The pattern doesn't use them.

A session's name is its address, so the first thing the skill does is name the orchestrator (<initiative>-orchestrator, via claude --name or /rename). Every brief it writes carries that name, and every worker gets a unique name of its own. If a name is already taken by a live session, Claude Code renames the newcomer, and messages meant for the original name land in the wrong place. ListAgents (or /list-agents) shows who a session can reach.

Keep the orchestrator and workers on one machine. Sessions on other machines or in the cloud only show up while connected to Remote Control, and a cloud session can receive a message but can't reply.

How a worker gets started

The orchestrator builds each slice's worktree itself with git worktree add, based on the integration branch or on another slice's branch when it needs unmerged work. It uses Git directly because claude --worktree always branches from the remote's default branch (origin/HEAD), or from the current local HEAD when worktree.baseRef is set to "head". It can't start from a named branch.

Then it hands you a launch command, cd .claude/worktrees/<slice> && claude --name <slice>. Once that session is up, the orchestrator either sends it the brief with SendMessage, or gives you the brief to paste as the first message. The worker's first move is checking git log to confirm its branch has what the brief says it depends on.

Worktree gotchas

• A worktree is a fresh checkout. Gitignored files like .env aren't there unless they're listed in a .worktreeinclude file at the project root, and dependencies need installing.
• Copied versus symlinked data. A gitignored database copied into a worktree is a private copy. A symlinked data folder is one shared copy across every worktree, which is the shared state the orchestrator serializes. Know which one your project has.
• Isolation depends on how the session started. Sessions started with --worktree (or moved with EnterWorktree) are blocked from editing the main checkout. A session started by cd-ing into a git worktree add folder is an ordinary session, so the brief tells it to stay in its folder.
• Keep the worktree on exit. Claude Code asks whether to keep or remove a worktree with work in it. Removing it deletes the folder and its branch, so keep it until the orchestrator has merged the slice.

Delivered isn't the same as read

A successful send means the message reached the session, not that Claude read it.

• Match permission modes. A session that bypasses permission prompts holds messages from one that doesn't (and the reverse) until you approve them, and a held message expires after five minutes by default. Plan mode counts as bypassing in an interactive terminal. The sender gets a notice when a message is held.
• Messages arrive between tool calls. A busy session reads a message after its current tool call. An idle session starts a new turn. So replies come on a later turn, and workers keep working in the meantime.
• @ mentions attach nothing. The receiving session sees the literal text, so the full report goes in the message.
• No polling. To hear when a worker finishes, the orchestrator sends with notify_when_idle: true and gets one notice when that session goes idle.

Inside a slice

Each worker splits models by job with the Agent tool's model parameter: implementation subagents on a fast model (Sonnet), and a code-review subagent on a stronger model (Opus) before the slice is done.

Permissions stay with each session

A message from another session is coordination, never your approval, and it can't answer a pending permission prompt. Anything one session is blocked from doing comes back to you instead of going to a peer.

If a session can't message at all (started with --bare, SendMessage denied by permission rules, or an old version), the worker prints its completion report for you to paste to the orchestrator.

The short version

The skill handles the naming, the worktrees, the briefs, and the merges. Keep your sessions on one machine, in one permission mode, and let the orchestrator run the build.