Deep Dive — Orchestration Tool

multiclaude

Why tell Claude what to do when you can tell Claude to tell Claude what to do? A multi-agent orchestrator built on the Brownian ratchet philosophy — chaos in, progress out.

Dan Lorenc Creator
Go Language
MIT License
6 Built-in Agents
Overview

What Is Multiclaude?

Multiclaude spawns multiple autonomous Claude Code instances to coordinate work on a single repository. Each agent gets its own tmux window and git worktree. A supervisor agent acts as air traffic control, assigning tasks and nudging stuck workers. The system operates like a ratchet: as long as CI passes, PRs get merged. Progress is permanent.

This isn't about replacing developers. It's about changing what developers do. Less typing, more thinking. Less implementation, more architecture. Less grunt work, more judgment.

— Dan Lorenc, "A Gentle Introduction to multiclaude"

Multiclaude frames software development as an MMORPG: your workspace is your character, workers are party members, the supervisor is the guild leader, and the merge queue is the raid boss guarding main. The system keeps running after you log off.

Under the Hood

Architecture

The Brownian ratchet model: multiple autonomous agents create apparent chaos, but CI serves as a one-way gate that converts chaos into permanent forward progress.

┌─────────────────────────────────────────────────────────────┐
│                     tmux session: mc-repo                   │
├───────────────┬───────────────┬───────────────┬─────────────┤
│  supervisor   │  merge-queue  │  workspace    │ worker-1  │
│  air traffic  │  CI bouncer   │  your shell   │ task agent │
└───────────────┴───────────────┴───────────────┴─────────────┘

Agent Activity (Chaotic)     CI Gate (Ratchet)     Main Branch (Progress)
─────────────────────── ──> ─────────────────── ──> ───────────────────
  worker-1: PR #42             tests pass?             merge #42
  worker-2: PR #43             tests pass?             merge #43
  worker-3: PR #44             tests fail              reject #44
  worker-3: PR #45 (fix)       tests pass?             merge #45
✶

Chaos is Expected

Redundant work is cheaper than blocked work. Multiple agents may independently solve overlapping problems — and that is by design.

⚠

CI is King

If tests pass, ship it. If tests fail, fix it. CI is the only quality gate. No human approval required in singleplayer mode.

⚡

Forward > Perfect

Three okay PRs beat one perfect PR. The system optimizes for throughput and momentum, not polish.

⚔

Humans Approve

Agents propose, humans decide. In multiplayer mode, every PR goes through human review before merge.

Getting Started

Installation & Setup

Multiclaude is a single Go binary with minimal dependencies.

Prerequisites

Install

# Install the latest version go install github.com/dlorenc/multiclaude/cmd/multiclaude@latest # Or build from source git clone https://github.com/dlorenc/multiclaude.git cd multiclaude go build ./cmd/multiclaude go install ./cmd/multiclaude

Quick Start

# 1. Start the multiclaude system multiclaude start # 2. Register a repository multiclaude repo init https://github.com/your/repo # 3. Spawn a worker with a task multiclaude worker create "Add unit tests for the auth module" # 4. Attach to the tmux session to watch agents work tmux attach -t mc-repo # 5. Detach with Ctrl-b d — agents keep running
Agent Roster

Built-in Agents

Six specialized agent roles, each defined by a Markdown prompt file. Custom agents can extend the roster.

Agent Role Description
Supervisor Air Traffic Control Coordinates all agents. Nudges stuck workers. Assigns and redistributes tasks.
Merge Queue CI Bouncer Singleplayer mode. Watches PRs, merges on CI pass. The ratchet mechanism.
PR Shepherd Review Coordinator Multiplayer mode. Coordinates human reviewers, manages review cycles.
Workspace Personal Shell Your direct Claude Code instance. Spawns workers on demand.
Worker Task Executor One task, one branch, one PR. The workhorse agent.
Reviewer Code Reviewer Reads PRs, leaves inline comments, checks quality.

Custom Agents

Agents are defined by Markdown files — no code required. Store custom agent definitions per-repo or globally.

# Per-repo custom agent ~/.multiclaude/repos/<repo>/agents/docs-reviewer.md # Team-shared agents (committed to repo) .multiclaude/agents/docs-reviewer.md # Spawn a custom agent multiclaude agents spawn --name docs-bot --class docs-reviewer --prompt-file docs-reviewer.md
Operational Modes

Singleplayer vs. Multiplayer

Fork detection is automatic. Initializing a fork enables PR Shepherd and disables Merge Queue.

Singleplayer

Full Autonomy

PRs auto-merge when CI passes. No human review required. The merge-queue agent acts as the gatekeeper. Best for personal projects or repos where you trust the test suite completely.

The system runs unsupervised — spawn workers, detach from tmux, come back to merged PRs.

multiclaude repo init https://github.com/you/repo
Multiplayer

Team Review

PRs require human review before merge. The PR Shepherd agent coordinates reviewers, responds to feedback, and manages the review cycle. Best for team repos or open-source projects.

Agents still do the work, but humans make the final merge decision.

multiclaude repo init https://github.com/you/fork
Reference

Usage & Commands

A minimal CLI surface. State lives in JSON files and the filesystem.

Command Purpose
multiclaude start Initialize the multiclaude system
multiclaude repo init <url> Register and configure a repository
multiclaude worker create "<task>" Spawn a new worker agent with a task description
multiclaude agents spawn Launch a named or custom agent
tmux attach -t mc-repo Attach to the tmux session to watch agents work
Ctrl-b d Detach from tmux (agents continue independently)

Agent Spawn Flags

multiclaude agents spawn \ --name docs-bot \ --class docs-reviewer \ --prompt-file docs-reviewer.md

Public Libraries

pkg/tmux

Programmatic tmux control with multiline support. Create sessions, windows, panes, and send commands.

pkg/claude

Launch and interact with Claude Code instances programmatically. The building block for custom orchestrators.

In Practice

Example Workflow

A real session adding features to a web application with three parallel workers.

01

Start and Initialize

Boot multiclaude and register your repo. The supervisor, merge-queue, and workspace agents spin up in tmux.

multiclaude start && multiclaude repo init https://github.com/you/webapp

02

Spawn Workers

Create three workers for independent tasks. Each gets its own git worktree and tmux window.

multiclaude worker create "Add OAuth2 login flow"

multiclaude worker create "Write unit tests for the API layer"

multiclaude worker create "Migrate CSS to Tailwind v4"

03

Agents Work Autonomously

Each worker creates a branch, makes changes, and opens a PR. The supervisor monitors progress and nudges stuck agents. You can watch via tmux attach -t mc-repo or walk away.

04

CI Runs, Merge Queue Acts

As PRs come in, CI runs tests. The merge-queue agent watches: pass = merge to main, fail = worker gets nudged to fix. Two workers might overlap — that's fine, the ratchet resolves it.

05

Come Back to Progress

Detach and return later. Workers that finished have their PRs merged. Workers that hit issues are waiting for your input or still iterating. Check main — it only moves forward.

multiclaude is a bet that the future of programming looks more like managing a team than writing code. Your job becomes setting direction, not typing characters.

— Dan Lorenc
Trade-offs

Limitations & Trade-offs

Every tool has edges. Multiclaude trades control for throughput.

Context

How It Compares

From Multiclaude's own documentation, comparing against Gas Town (Steve Yegge's orchestrator).

Dimension Gas Town Multiclaude
Complexity Higher Lower
Best For Solo / hobby projects Team workflows
Parallel Agents Stronger Weaker
Long Autonomous Runs Weaker Stronger