Gas Town

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
      

Agent hierarchy — solid lines = commands, dotted = monitors/verifies

Mayor Town
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
        
Protocol Message Types
POLECAT_DONE MERGE_READY MERGED MERGE_FAILED REWORK_REQUEST RECOVERED_BEAD RECOVERY_NEEDED HELP HANDOFF
7 — Command Reference
Work Dispatch Core
CommandPurpose
gt sling <bead> [target]Assign work to an agent — THE primary command for dispatching workAuto-creates convoy, spawns polecat, hooks work, starts session
gt hookShow what's on your hook (current work assignment)Also: gt hook attach, gt hook detach, gt hook clear
gt doneComplete work — push branch, submit to merge queue, clear hook, go idleExit statuses: COMPLETED (default), ESCALATED, DEFERRED
gt handoffEnd current session, hand off to fresh agent with preserved contextFlags: -c auto-collect state, --cycle for compaction recovery
gt unslingRemove work from hook without completing (revoke assignment)
gt close <bead>Close an issue manuallyAccepts multiple bead IDs: gt close gt-abc gt-def
Convoy Orchestration Batch
CommandPurpose
gt convoy create <name> [beads...]Create a tracked work batchFlags: --notify <addr>, --merge <strategy>
gt convoy listDashboard view of all active convoysFlags: --all, --status, --json, --tree
gt convoy status [id]Detailed convoy progress and worker status
gt convoy add <id> <beads...>Add beads to an existing convoy (auto-reopens if closed)
gt convoy land [id]Land completed convoy, clean up worktreesFlags: --keep, --dry-run, --force
gt convoy close [id]Close convoy (verifies all items done first)
Agent Control Agents
CommandPurpose
gt mayor start|attach|stopMayor lifecycle — start coordinator, attach to session, or stop
gt deacon start|attach|stop|statusWatchdog lifecycle — start daemon, check health, force-kill agents
gt witness start|attach|stop <rig>Per-rig polecat monitor lifecycle
gt refinery start|attach|stop [rig]Merge queue processor lifecycle
gt polecat list|status|nuke|gcWorker management — list polecats, check status, destroy sandboxes, garbage collect
gt crew add|list|statusPersistent worker managementgt crew add max --rig gastown
gt agentsList all active agent sessionsAlso: gt agents menu for interactive switching, gt agents fix for cleanup
Communication Comms
CommandPurpose
gt mail send <addr> -s "..." -m "..."Send persistent message (creates bead)Types: task, notification, reply. Priority: 0 (urgent) to 4 (backlog)
gt mail inbox [address]Check inbox for messages
gt nudge <target> "msg"Ephemeral real-time ping via tmuxModes: wait-idle, queue, immediate
gt escalate "problem" --severity criticalRoute critical issues to handlersSeverity: critical (P0), high (P1), medium (P2), low (P3)
Workspace Setup
CommandPurpose
gt install [path]Initialize Gas Town workspace (HQ)Flags: --git, --github <user/repo>, --shell, --supervisor
gt rig add <name> <url>Register a project repoCreates config, beads DB, refinery clone, witness dir, polecats dir
gt rig listShow all registered rigs with status
gt rig boot <rig>Start witness + refinery for a rig
gt up / gt downStart or stop all subsystems (dolt server, agents, daemon)
Monitoring Observe
CommandPurpose
gt feedReal-time activity TUI dashboardFlags: --problems (stuck agents view), --plain, --since 1h
gt dashboard [--port 3000]Web UI dashboard for browser monitoringFlag: --open to launch browser
gt statusQuick workspace status overview
gt agentsList all active agent sessions with health
Diagnostics & Workflows
CommandPurpose
gt doctor [--fix]Diagnose workspace issues and auto-fix common problems
gt primeRestore agent context — outputs role context for current directory
gt whoamiCurrent agent identity
gt config agent set <name> "<cmd>"Define custom agent runtime command
gt config default-agent <name>Set default agent for spawning
gt mol status|list|showMolecule workflow management and tracking
gt patrol newStart a new patrol cycle (Deacon/Witness/Refinery)
gt patrol report --summary "..."Complete patrol cycle + start next one atomically
gt dnd on|offToggle Do Not Disturb (suppress nudges)
gt show <bead-id>View full issue details
8 — Quick Start
# 1. Install Gas Town workspace
gt install ~/gt

# 2. Add your project
gt rig add myproject https://github.com/user/repo

# 3. Boot the rig (starts Witness + Refinery)
gt rig boot myproject

# 4. Start the Mayor (coordinator)
gt mayor start

# 5. Assign work to an agent
gt sling gt-abc myproject

# 6. Monitor everything
gt feed
9 — Key Flags for gt sling
--agent <alias>Override runtime: claude, codex, gemini, cursor, copilot
--merge <strategy>Merge strategy: direct (push main), mr (merge queue, default), local (keep branch)
--no-convoySkip auto-convoy creation
--forceForce spawn even if agent has unread mail
--createCreate polecat identity if it doesn't exist
-s "subject"Context subject for the work assignment
-m "message"Natural language instructions for the executor
--var key=valueFormula variables (repeatable for multiple vars)
--max-concurrent NLimit concurrent spawns in batch mode
-n, --dry-runShow what would happen without doing it
10 — Architecture
~/gt/ — Town root (HQ)
  town.json — Town identity & metadata
  mayor/ — Mayor workspace
    rigs.json — Registry of managed rigs
    rig/ — Mayor's reference clone
  settings/ — Town-wide config (agents, theme, timeouts)
  .beads/ — Town-level issue tracking (hq-* prefix)
  <rig>/ — Per-rig workspace
    config.json — Rig configuration
    .beads/ — Rig-level issues (gt-* prefix)
    polecats/ — Worker git worktrees
      Toast/ — Polecat sandbox (isolated clone)
      Smokey/ — Another polecat
    crew/ — Human/bot workspaces
    witness/ — Witness agent workspace
    refinery/ — Merge queue + canonical clone
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.