multi-agent orchestration for claude code — complete guide
1 — What Is Gas Town?
Gas Town is a multi-agent orchestration system written in Go that coordinates
20–30+ AI coding agents working on the same codebase simultaneously. It supports Claude Code, Codex,
Gemini, Cursor, Copilot, and more.
The core problem: AI agents lose context when they restart, crash,
or hit context limits. Gas Town persists all work state using git-backed storage (Dolt + worktrees),
so progress survives crashes and restarts. Work is tracked as beads, assigned via hooks,
and coordinated through convoys — all durable primitives that outlive any single session.
2 — The Cast of Characters
graph TD
Human["Human Operator"] --> Mayor
Mayor["Mayor\n(Town Coordinator)"] --> Deacon
Mayor --> W1["Witness\n(Rig A)"]
Mayor --> W2["Witness\n(Rig B)"]
Deacon["Deacon\n(Watchdog Daemon)"] -.->|"monitors"| W1
Deacon -.->|"monitors"| W2
Deacon --> Dogs["Dogs\n(Helpers)"]
W1 --> R1["Refinery\n(Merge Queue)"]
W1 --> P1["Polecat 1"]
W1 --> P2["Polecat 2"]
W1 --> P3["Polecat 3"]
W2 --> R2["Refinery\n(Merge Queue)"]
W2 --> P4["Polecat 4"]
W2 --> P5["Polecat 5"]
W1 -.->|"verifies"| R1
W2 -.->|"verifies"| R2
Human --> Crew["Crew\n(Long-lived Workers)"]
classDef town fill:#f59e0b22,stroke:#f59e0b,stroke-width:2px
classDef rig fill:#ea580c22,stroke:#ea580c,stroke-width:2px
classDef worker fill:#14b8a622,stroke:#14b8a6,stroke-width:1.5px
classDef human fill:#a855f722,stroke:#a855f7,stroke-width:2px
classDef helper fill:#65a30d22,stroke:#65a30d,stroke-width:1.5px
class Mayor,Deacon town
class W1,W2,R1,R2 rig
class P1,P2,P3,P4,P5 worker
class Human,Crew human
class Dogs helper
The orchestrator. Receives human instructions, creates convoys, coordinates cross-rig work, handles escalations. Singleton at town level. Inbox: mayor/
Deacon Town
The watchdog daemon. Monitors all Witnesses, detects stalled agents, triggers respawns, manages Dogs (helper agents). Runs continuous patrol cycles.
Witness Per-Rig
Monitors all polecats in a rig. Detects stalls/crashes, nudges sessions back to life, validates work quality before merge queue. Inbox: <rig>/witness
Refinery Per-Rig
The merge queue processor. Receives MRs, rebases onto main, runs tests, merges when clear. Handles conflicts by spawning fresh polecats. Inbox: <rig>/refinery
Polecats Workers
Ephemeral worker agents — the hands that do the coding. Each gets an isolated git worktree. Persistent identity but ephemeral sessions. States: Working → Idle → Stalled → Zombie.
Crew Per-Rig
Long-lived human/bot collaborators that persist across sessions and build up context over time. Unlike polecats, crew members maintain continuity.
Dogs Helpers
Background maintenance agents managed by the Deacon. The Boot dog checks Deacon health every 5 minutes. Custom dogs handle cleanup and other tasks.
3 — Key Concepts
Beads
Atomic work units stored in a Dolt database. Like issues with IDs such as gt-abc12. Have title, description, status, priority, dependencies, and custom fields. Lifecycle: created → assigned → in_progress → closed.
Hooks
A pinned bead on an agent's worktree — their current assignment. The durability primitive. Survives restarts, crashes, context compaction. gt hook to view, gt done to clear.
Convoys
Bundles of related beads tracked together. Auto-created when you sling work. Status: open → staged_ready → landed. Notifies subscribers when all work completes. gt convoy list for dashboard.
Rigs
Registered projects/repos managed by Gas Town. Each rig has its own Witness, Refinery, polecats, and crew. Add with gt rig add <name> <url>.
Formulas
TOML workflow templates — like recipes for multi-step processes. Define steps with dependencies and variables. Cooked into protomolecules, then instantiated.
Molecules
Active instances of formulas. Each step is tracked individually with checkpoint recovery. Steps shown inline via gt prime. Survive session death.
Mailboxes
Inter-agent messaging. Beads-backed for polecats (persistent), JSONL for crew. Messages survive session death. Used for protocol messages like MERGE_READY and HANDOFF.
Wisps
Ephemeral beads for transient work — never synced to main. Used for patrol cycles, temporary tracking, and formula steps that don't need permanent records.
4 — The Propulsion Principle
"If there is work on your Hook, YOU MUST RUN IT."
This is the heartbeat of Gas Town. When an agent finds work on its hook, it executes immediately
without waiting for confirmation. The hook is the durability primitive — it survives crashes,
restarts, and context compaction. The Witness enforces this by detecting any agent that has hooked
work but isn't running it.
5 — Complete Work Lifecycle
graph TD
A["1. CREATE\nHuman creates issue\nor Mayor creates convoy"] --> B["2. ASSIGN\ngt sling gt-abc rig"]
B --> C["Spawn Polecat\n+ Git Worktree"]
C --> D["Hook Work\nto Polecat"]
D --> E["Start Claude\nSession"]
E --> F["3. EXECUTE\ngt prime loads context"]
F --> G["Work Through\nFormula Steps"]
G --> H{"Crash or\nContext Limit?"}
H -->|"Yes"| I["Witness Detects\n+ Respawns"]
I --> F
H -->|"No"| J["4. COMPLETE\ngt done"]
J --> K["Push Branch\n+ Submit MR"]
K --> L["Clear Hook\nGo Idle"]
L --> M["5. MERGE\nRefinery Receives MR"]
M --> N["Rebase onto Main"]
N --> O{"Conflict?"}
O -->|"Yes"| P["Spawn Fresh\nPolecat to Resolve"]
P --> M
O -->|"No"| Q["Run Tests\n+ Validate"]
Q --> R["Merge to Main"]
R --> S["6. NOTIFY\nConvoy Detects Close"]
S --> T["Convoy Lands\nNotify Subscribers"]
classDef create fill:#a855f722,stroke:#a855f7,stroke-width:2px
classDef assign fill:#f59e0b22,stroke:#f59e0b,stroke-width:2px
classDef execute fill:#14b8a622,stroke:#14b8a6,stroke-width:2px
classDef complete fill:#65a30d22,stroke:#65a30d,stroke-width:2px
classDef merge fill:#ea580c22,stroke:#ea580c,stroke-width:2px
classDef notify fill:#fbbf2422,stroke:#fbbf24,stroke-width:2px
classDef recovery fill:#fb718522,stroke:#fb7185,stroke-width:1.5px
class A create
class B,C,D,E assign
class F,G,H execute
class J,K,L complete
class M,N,O,Q,R merge
class S,T notify
class I,P recovery
Full lifecycle from issue creation through merge — pink nodes are recovery paths
6 — Communication Protocol
gt nudge
Ephemeral • Zero Cost
Direct tmux send-keys or file queue. Lost if session dies.
Zero storage cost. Use for routine pings, health checks, simple instructions.
Delivery modes: wait-idle (default), queue, immediate.
gt mail send
Persistent • Beads-Backed
Creates a wisp bead in Dolt. Survives session death.
Use for handoff context, protocol messages (MERGE_READY, MERGED, REWORK_REQUEST), HELP escalations.
Rule: default to nudge; only use mail when message MUST survive.
Polecat → Witness → Refinery Protocol
sequenceDiagram
participant P as Polecat
participant W as Witness
participant R as Refinery
P->>P: gt done (push + submit MR)
P->>W: POLECAT_DONE
W->>W: Verify clean state
W->>R: MERGE_READY
R->>R: Rebase + validate
alt Success
R-->>W: MERGED
W->>W: Nuke sandbox
else Conflict
R-->>W: REWORK_REQUEST
W->>W: Spawn fresh polecat
else Test Failure
R-->>W: MERGE_FAILED
W->>W: Escalate
end
Key insight: Each polecat gets its own git worktree —
an isolated copy of the repo that shares the git object store but has independent HEAD, index, and working directory.
This means 20+ agents can work on different branches of the same repo simultaneously without conflicts.
The worktree is preserved between assignments (sandbox reuse) and only destroyed by explicit gt polecat nuke.