Claude Maestro: Multi-Agent Claude Code Orchestration

Run multiple Claude Code agents in parallel, each in its own tmux pane with an isolated git worktree. One script. No frameworks. No experimental flags.

Drop one shell script into your project. Get parallel agents with file locking, inter-agent messaging, and automatic branch management — zero configuration.

---

Table of Contents

1. The Problem
2. The Solution
3. How It Works
4. Setup (1 minute)
5. Usage
6. Communication Between Agents
7. Team Patterns
8. Customizing
9. FAQ
10. Architecture

---

The Problem

You're deep into a complex task with Claude Code. Maybe you need to:

• Refactor a module while another agent writes tests for the old behavior
• Have a security reviewer scanning your codebase while you implement features
• Run three agents with competing hypotheses about a bug, in parallel
• Split a large feature across multiple agents to finish faster

Running multiple terminals manually is chaos. Two agents edit the same file — merge conflict. No one knows what the other is doing. You spend more time coordinating than coding.

The alternatives aren't great either:

Approach	Problem
Multiple terminals manually	File conflicts, no coordination, chaos
Agent Teams (experimental)	Requires experimental flag, limited control
Python orchestrator frameworks	Heavy setup, dependencies, over-engineered
Single agent, sequential work	Slow — you're leaving parallelism on the table

---

The Solution

orchestra.sh — a single shell script (~400 lines) that:

• Creates a tmux session with one pane per agent (tiled grid)
• Gives each agent its own git worktree (isolated filesystem — zero merge conflicts)
• Sets up a shared .orchestra/ directory for inter-agent communication
• Provides a dashboard pane that live-updates agent statuses
• Cleans up everything (tmux session, worktrees, branches) when you're done

Each agent is a standard Claude Code instance with --resume --name. No forks, no wrappers, no monkey-patching. Just tmux + git worktrees + a coordination protocol.

---

How It Works

Three layers of isolation

1. Git worktrees — Each agent gets its own copy of the repository via git worktree. They can edit any file without conflicting with other agents. Each worktree is on its own branch (lead/working, agent-1/working, etc.).

2. Status files — Each agent maintains a diary in .orchestra/status/<name>.md declaring what it's working on and which files it has claimed. Other agents read these before starting work.

3. Coordination protocol — A COORDINATION.md file is automatically generated with rules that each Claude Code instance follows: read before you start, declare your work, respect file locks, check messages.

What happens when you run start

./orchestra.sh start -n 3 -t "Build a REST API"

1. Creates .orchestra/ directory with status files, task description, and coordination rules
2. Creates git worktrees in .worktrees/ — one per agent, each on its own branch
3. Copies the coordination directory into each worktree
4. Creates a tmux session with a tiled grid layout (agents + dashboard)
5. Launches claude --resume --name <agent> in each pane
6. Starts a watch loop in the dashboard pane showing live status
7. Attaches you to the tmux session

What happens when you run stop

./orchestra.sh stop

1. Kills the tmux session (all Claude Code instances terminate gracefully)
2. Removes all git worktrees in .worktrees/
3. Prunes stale worktree references from git

Pass --keep-worktrees to preserve the worktrees for later inspection.

What happens when you run collect

./orchestra.sh collect

1. Finds all agent branches (*/working, */feat-*, */fix-*, */refactor-*)
2. Counts commits on each branch relative to main
3. Merges each branch into main with --no-ff (preserving history)
4. Reports conflicts for manual resolution

Pass --dry-run to preview without merging.

---

Setup (1 minute)

Prerequisites

• tmux — brew install tmux (macOS) or apt install tmux (Linux)
• git — you already have this
• Claude Code CLI — installed and authenticated (claude in your PATH)

Install

# Option A: Download directly into your project
curl -o orchestra.sh https://raw.githubusercontent.com/lucasrosati/claude-maestro/main/orchestra.sh
chmod +x orchestra.sh

# Option B: Clone and copy
git clone https://github.com/lucasrosati/claude-maestro.git /tmp/claude-maestro
cp /tmp/claude-maestro/orchestra.sh ./
chmod +x orchestra.sh

# Option C: Global install (available everywhere)
curl -o ~/.local/bin/orchestra https://raw.githubusercontent.com/lucasrosati/claude-maestro/main/orchestra.sh
chmod +x ~/.local/bin/orchestra

First run

cd your-project/
./orchestra.sh start

That's it. Four Claude Code agents in a tmux grid, each with its own worktree.

---

Usage

Start a team

# Default: 4 agents
./orchestra.sh start

# Custom agent count
./orchestra.sh start -n 2

# With a shared task description
./orchestra.sh start -n 3 -t "Refactor the auth module into separate services"

# With specific roles and initial prompts
./orchestra.sh start \
  --lead "You are the architect. Design the API structure first, then coordinate." \
  --agent "You handle backend implementation. Wait for the architect's design." \
  --agent "You write tests. Follow the implementation agent's progress."

# Without worktrees (shared filesystem — use when agents edit different files)
./orchestra.sh start --no-worktrees

# Without dashboard pane
./orchestra.sh start --no-dashboard

# With a specific model
./orchestra.sh start --model sonnet

Send messages

# Message a specific agent
./orchestra.sh msg agent-1 "Use JWT for auth, not sessions"

# Broadcast to all agents
./orchestra.sh broadcast "Pause and commit your current work before continuing"

Messages appear as files in .orchestra/messages/. Each agent is instructed (via COORDINATION.md) to periodically check this directory.

Monitor status

./orchestra.sh status

Output:

═══════════════════════════════════════
         Orchestra Status
═══════════════════════════════════════

  ● lead
    Status: working
    Task: Designing API routes
    Branch: lead/working
    Files: src/routes/index.ts, docs/api.md

  ● agent-1
    Status: working
    Task: Implementing user endpoints
    Branch: agent-1/working
    Files: src/routes/users.ts, src/models/user.ts

  ○ agent-2
    Status: idle
    Task: —

  tmux session active (5 panes)

Collect and merge

# Preview what would be merged
./orchestra.sh collect --dry-run

# Merge all agent branches into main
./orchestra.sh collect

Tear down

# Stop everything and clean up
./orchestra.sh stop

# Stop but keep worktrees for inspection
./orchestra.sh stop --keep-worktrees

---

Communication Between Agents

Agents communicate through the filesystem — no IPC, no sockets, no network calls. This is deliberate: it's simple, debuggable, and works across any environment.

Status files (agent → world)

Each agent maintains .orchestra/status/<name>.md:

# agent-1 — Session Diary

Status: working
Task: Implementing user CRUD endpoints
Branch: agent-1/working
Files: src/routes/users.ts, src/models/user.ts
Started: 2026-04-15 14:30
Notes: Need access to src/middleware/auth.ts after lead finishes

The Files field acts as a mutex. If lead claims src/middleware/auth.ts, other agents know not to edit it. When lead finishes and removes it from their list, it's free.

Messages (user/agent → agent)

Point-to-point messages go to .orchestra/messages/:

# From terminal
./orchestra.sh msg agent-1 "Switch to using Zod instead of Joi"

Creates .orchestra/messages/2026-04-15_14-30-to-agent-1.md:

# Message to agent-1

**From:** user
**Time:** 2026-04-15 14:30:00

Switch to using Zod instead of Joi

Broadcasts go to all agents:

./orchestra.sh broadcast "Everyone commit your work — merging in 5 minutes"

Coordination protocol

The auto-generated COORDINATION.md instructs each agent to:

1. Read all status files before starting any task
2. Declare work by updating their own status file
3. Respect file locks — never edit a file another agent claimed
4. Check messages periodically
5. Update status to "done" when finished
6. Stay on their own branch — never commit to main

This is a cooperative protocol. Claude Code instances follow it because it's in their context. There's no enforcement mechanism — it works because agents read and respect the rules.

---

Team Patterns

Feature Team

One architect, N implementers, one tester. The architect designs first, then the implementers build in parallel, and the tester follows behind.

./orchestra.sh start \
  --lead "Design the auth system: data model, API routes, middleware. Write the plan to .orchestra/task.md" \
  --agent "Implement the API endpoints. Wait for lead's design in .orchestra/task.md" \
  --agent "Write integration tests for each endpoint as agent-1 implements them"

See examples/feature-team.sh.

Review Team

Multiple reviewers analyzing the same codebase from different angles, in parallel.

./orchestra.sh start --no-worktrees \
  --agent "Security review: check for OWASP Top 10 vulnerabilities" \
  --agent "Performance review: find N+1 queries, missing indexes, memory leaks" \
  --agent "Test coverage: identify untested critical paths and write tests"

See examples/review-team.sh.

Debug Team

Competing hypotheses. Each agent investigates a different theory about a bug.

./orchestra.sh start --no-worktrees -t "Users report 500 errors on /api/checkout" \
  --agent "Hypothesis: race condition in inventory check. Investigate concurrency." \
  --agent "Hypothesis: payment gateway timeout. Check external API calls." \
  --agent "Hypothesis: data corruption. Check recent migrations and data integrity."

See examples/debug-team.sh.

---

Customizing

Number of agents

The default is 4 (lead, agent-1, agent-2, agent-3). Change with --agents:

./orchestra.sh start --agents 2    # just 2
./orchestra.sh start --agents 6    # go wide

Or use --name for custom names:

./orchestra.sh start --name frontend --name backend --name devops

Agent definitions

If you have custom agents in .claude/agents/, give each orchestra agent a prompt referencing them:

./orchestra.sh start \
  --agent "Run the red-team-scanner agent on this codebase" \
  --agent "Run the blue-team-defender agent after the scanner finishes"

Model selection

./orchestra.sh start --model opus       # maximum capability
./orchestra.sh start --model sonnet     # balanced (default)
./orchestra.sh start --model haiku      # fast and cheap

Worktree vs shared filesystem

By default, each agent gets its own git worktree (isolated copy of the repo). This prevents file conflicts but uses more disk space.

For read-heavy tasks (reviews, audits, debugging), use --no-worktrees:

./orchestra.sh start --no-worktrees    # all agents share the same filesystem

Adding to CLAUDE.md

For the best coordination, add this section to your project's CLAUDE.md:

## Orchestra Coordination

### Before starting any task
1. Read ALL files in `.orchestra/status/` to know what other agents are doing
2. Update your own status file with your task and claimed files

### File locking
If another agent listed a file in their "Files" field, DO NOT edit that file.
Wait or write a note in your status file requesting coordination.

### Git
- Work on your own branch
- Never commit directly to main
- Never merge other agents' branches

---

FAQ

Do I need any special setup? No. Just tmux, git, and Claude Code CLI. No Python, no Docker, no experimental flags.

How do agents know about each other? Through the .orchestra/ directory. The auto-generated COORDINATION.md tells each agent to read status files and check for messages before starting work.

Can agents actually read each other's messages? Yes. Each Claude Code instance has access to the filesystem. The coordination protocol instructs them to periodically check .orchestra/messages/ for files addressed to them.

What prevents two agents from editing the same file? Git worktrees give each agent its own copy of the repo, so file edits never physically conflict. Additionally, the status file protocol lets agents declare which files they're working on, creating a cooperative lock.

How much does it cost? Each agent is a separate Claude Code session, so you pay for N sessions. Use fewer agents for cost-sensitive work, or use --model haiku for cheaper agents.

Can I add or remove agents while the session is running? Not with the script directly. But you can manually split a tmux pane (Ctrl-b %) and launch claude --resume --name extra-agent in it.

What if an agent ignores the coordination protocol? The protocol is cooperative — there's no enforcement. In practice, Claude Code follows instructions in COORDINATION.md reliably. Git worktrees provide a hard safety net regardless.

Can I use this with Agent Teams (experimental)? Yes, but they solve different problems. Agent Teams provides built-in messaging and task sharing. Orchestra provides filesystem isolation via worktrees and a simpler, more controllable setup. You can use both if you want.

Does it work on Linux? Yes. The script uses POSIX-compatible commands. Just install tmux and git.

What about Windows? Use WSL. Install tmux and git inside WSL, then run the script normally.

tmux Quick Reference

Action	Shortcut
Switch between panes	Ctrl-b + arrow keys
Zoom into a pane	Ctrl-b + z (toggle)
Scroll up in a pane	Ctrl-b + [ (then arrows, q to exit)
Detach from session	Ctrl-b + d
Reattach later	tmux attach -t orchestra
List sessions	Ctrl-b + s

---

Architecture

your-project/
├── orchestra.sh                  # The script (this is all you need)
│
├── .orchestra/                   # Created by `start`, coordination hub
│   ├── COORDINATION.md           #   Rules for agents (auto-generated)
│   ├── task.md                   #   Shared task description (optional)
│   ├── status/                   #   Agent status files
│   │   ├── lead.md               #     "Status: working, Files: ..."
│   │   ├── agent-1.md
│   │   ├── agent-2.md
│   │   └── agent-3.md
│   └── messages/                 #   Inter-agent messages
│       ├── ...-to-agent-1.md     #     Point-to-point
│       └── ...-broadcast.md      #     Broadcast to all
│
└── .worktrees/                   # Created by `start`, git worktrees
    ├── lead/                     #   Full repo copy for lead
    │   ├── src/
    │   ├── .orchestra/ (copy)
    │   └── ...
    ├── agent-1/                  #   Full repo copy for agent-1
    ├── agent-2/
    └── agent-3/

Git branches (auto-created):
  main                            # Protected — no direct commits
  ├── lead/working                # Lead's worktree branch
  ├── agent-1/working             # Agent 1's branch
  ├── agent-2/working             # Agent 2's branch
  └── agent-3/working             # Agent 3's branch

Data flow

User gives task to each agent (via tmux pane)
        │
        ▼
Agent reads .orchestra/status/*.md  ← What are others doing?
        │
        ▼
Agent updates .orchestra/status/<me>.md  ← I'm working on X, editing files Y
        │
        ▼
Agent works on its own worktree/branch  ← Isolated filesystem
        │
        ▼
User checks progress: ./orchestra.sh status
        │
        ▼
User sends coordination: ./orchestra.sh msg agent-1 "..."
        │
        ▼
Agent checks .orchestra/messages/  ← Any messages for me?
        │
        ▼
Agent finishes, updates status to "done"
        │
        ▼
User merges: ./orchestra.sh collect  ← All branches → main

---

Credits & Links

• Claude Code — Anthropic's coding agent
• Claude Code Agents — Custom agent documentation
• Git Worktrees — Isolated working copies from one repo
• tmux — Terminal multiplexer

---

If this helped you ship faster with parallel agents, give the repo a star and share it with other devs using Claude Code.