Gas Town: Multi-Agent Orchestrator for Claude Code
Steve Yegge's open source system for coordinating 20-30 Claude Code agents in parallel. Here's how to set it up and start scaling your AI-assisted development.
What is Gas Town?
Gas Town is Steve Yegge's open source multi-agent orchestration system for Claude Code. It coordinates 20-30 AI coding agents working in parallel, using git-backed "Hooks" for persistent work state that survives crashes and restarts. You communicate with "The Mayor" (your AI coordinator), which spawns and manages worker agents called "Polecats." Think of it as Kubernetes for coding agents—powerful, but expensive to run.
TL;DR
- •Scale to 20-30 agents: Coordinate multiple Claude Code instances working on different tasks simultaneously
- •Persistent work state: Git-backed Hooks survive agent crashes and restarts—no more lost context
- •The Mayor pattern: Talk to one AI coordinator that orchestrates all your worker agents automatically
- •Built on Beads: Git-backed issue tracking with unique IDs (gt-abc12) for structured work management
- •Expensive but powerful: Expect ~10x token costs vs standard Claude Code—roughly $100/hour of parallel work
If you've spent any time with Claude Code, you've probably experienced the frustration: you're deep into a complex feature, the agent is making progress, and then... context lost. Session ends. You start over, re-explaining everything.
Now imagine running thirty Claude Code instances in parallel. The coordination nightmare is obvious. That's exactly the problem Steve Yegge—ex-Amazon, ex-Google, ex-Sourcegraph engineer with 30+ years of experience—set out to solve.
Gas Town is his answer: an open source orchestration system that treats AI coding agents like a fleet of workers. You talk to "The Mayor" (your AI foreman), and it coordinates however many agents your budget can handle.
The name comes from the oil refinery citadel in Mad Max—and the Mad Max theme runs throughout the architecture: Rigs (projects), Polecats (workers), Convoys (work bundles). It's theatrical, but the engineering underneath is serious. Let's break down how to actually use it.
01.Core Concepts: The Gas Town Architecture
Before diving into installation, you need to understand the key components. Gas Town uses Mad Max-inspired terminology, but each concept maps to a concrete technical function.
| Component | What It Is | Technical Reality |
|---|---|---|
| Town | Your workspace | Root directory (~/gt/) containing all projects and config |
| The Mayor | AI coordinator | Claude Code instance with full workspace context |
| Rigs | Projects | Containers wrapping git repositories |
| Polecats | Worker agents | Ephemeral Claude instances that spawn, work, disappear |
| Hooks | Persistent storage | Git worktree-based state that survives crashes |
| Beads | Work items | Git-backed issues with IDs like gt-abc12 |
| Convoys | Work bundles | Groups of Beads assigned to agents for tracking |
The key insight is persistent work state. Traditional Claude Code sessions are ephemeral—crash and you lose everything. Gas Town stores work state in git worktrees (Hooks), so agents can pick up exactly where they left off. This is what enables coordination at scale.
02.Installation: Getting Gas Town Running
Prerequisites
- Go 1.23+ — Gas Town is written in Go
- Git 2.25+ — Requires worktree support for Hooks
- Beads 0.44.0+ — The work tracking system
- tmux 3.0+ — Recommended for multi-agent orchestration
- Claude Code CLI — Or another supported runtime (Codex, Cursor, Gemini)
- SQLite3 — For convoy queries
Installation Options
Option 1: Homebrew (macOS/Linux)
brew tap steveyegge/gastown && brew install gtOption 2: npm
npm install -g @gastown/gtOption 3: From Source
go install github.com/steveyegge/gastown/cmd/gt@latestInitial Setup
Step 1: Initialise Your Town
gt install ~/gt --git
cd ~/gtThis creates your workspace directory with git tracking enabled.
Step 2: Add Your First Rig (Project)
gt rig add myproject https://github.com/you/repo.gitStep 3: Create Your Crew Workspace
gt crew add yourname --rig myprojectStep 4: Attach to The Mayor
gt mayor attachThis starts your AI coordinator session. You're now ready to orchestrate agents.
03.Working with The Mayor
The Mayor is the heart of Gas Town. Rather than managing individual agents, you communicate your goals to the Mayor, and it handles orchestration. This abstraction layer is what makes coordinating dozens of agents manageable.
The Mayor Workflow
Describe Your Goal
Tell the Mayor what you want to build. Be specific about features, requirements, and priorities.
Mayor Creates Beads
The Mayor breaks down your goal into discrete work items (Beads) with unique IDs.
Polecats Are Spawned
Worker agents spin up to handle individual Beads in parallel.
Work State Persists
Hooks store progress in git worktrees, surviving any crashes or restarts.
Mayor Reports Progress
Track convoy status, completed Beads, and overall progress through the dashboard.
Essential Mayor Commands
# Attach to Mayor session
gt mayor attach
# Create a convoy with multiple work items
gt convoy create "Feature X" gt-abc12 gt-def34 --notify
# List all active convoys
gt convoy list
# Show convoy details
gt convoy show
# Add more issues to existing convoy
gt convoy add <convoy-id> gt-xyz99
# List all active agents
gt agents
# Recover context after crash
gt prime04.Convoys and Beads: Tracking Work at Scale
When you're running 20+ agents, tracking what's happening becomes critical. Gas Town uses Beads (individual work items) grouped into Convoys (trackable bundles) to provide visibility.
Bead ID Format
Every Bead has a unique identifier:
prefix-xxxxx
Examples:
gt-abc12 # Gas Town workspace bead
hq-x7k2m # Headquarters/town-level bead
myrig-def34 # Project-specific beadThe prefix indicates origin/scope, followed by 5 alphanumeric characters.
Manual Work Assignment
For more control, you can manually assign Beads to agents:
# Assign a bead to a specific rig
gt sling gt-abc12 myproject
# The agent picks up work from its mailbox
claude --resume
# Agent completes work, reports back to convoyCost Warning
Gas Town burns through tokens fast. Steve Yegge calls it "a machine for spending hundreds of dollars a day on Claude Code." Real-world reports show ~$100 per hour of parallel agent work. This is roughly 10x the cost of standard Claude Code sessions. Make sure your budget can handle it before scaling up.
05.Advanced Features: Formulas and Multi-Runtime
Formula Workflows
Formulas are predefined, repeatable processes stored as TOML files. Perfect for standardised tasks like releases, deployments, or code reviews.
# List available formulas
bd formula list
# Execute a formula with variables
bd cook release --var version=1.2.0
# Create trackable instance
bd mol pour release --var version=1.2.0Formulas live in .beads/formulas/ directory.
Multiple AI Runtimes
Gas Town isn't locked to Claude Code. Configure different runtimes per-rig:
- •Claude Code — Primary runtime with hook-based mail injection
- •Codex — Set
project_doc_fallback_filenames = ["CLAUDE.md"] - •Cursor — IDE-integrated agent preset
- •Gemini — Google's coding assistant
- •Auggie, Amp — Custom presets available
# Configure custom agent
gt config agent set myagent "custom-command --args"
# Set default runtime
gt config default-agent claude
# View current config
gt config show06.Real-World Usage: What to Expect
Gas Town has been described as operating in "limitless mode"—output streams rapidly across multiple terminals, making real-time comprehension difficult. Here's what experienced users report:
The Experience
"There's really too much going on for you to reasonably comprehend." Users report the parallel execution feels overwhelming at first. The Mayor abstraction helps, but you're still watching multiple agents work simultaneously.
Costs in Practice
One DoltHub engineer reported spending approximately $100 in Claude tokens for 60 minutes of parallel work fixing four test files. The agents created four separate PRs automatically.
Quality Considerations
Autonomous operation requires "proper guard rails." Without careful setup, agents may produce work that isn't production-ready. Start small, validate outputs, and gradually increase parallelism.
"Gas Town is more like a coding agent factory than a coding agent—you talk to the Mayor (factory foreman), and it coordinates as many workers as needed."
07.Frequently Asked Questions
What is Gas Town?
Gas Town is a multi-agent orchestration system created by Steve Yegge that coordinates multiple Claude Code instances working in parallel. It solves the problem of context loss between agent sessions by using git-backed persistent storage called Hooks, and can scale to manage 20-30 concurrent AI coding agents.
How much does Gas Town cost to run?
Gas Town is free and open source (MIT licence), but it significantly increases Claude API costs. Users report spending roughly 10x the token cost of standard Claude Code sessions per unit time. One user reported approximately $100 in Claude tokens for 60 minutes of parallel agent work. Steve Yegge describes it as "a machine for spending hundreds of dollars a day on Claude Code."
What are Beads in Gas Town?
Beads are the atomic unit of work in Gas Town—essentially git-backed issue tracker items. Each Bead has a unique ID (prefix + 5 alphanumeric characters like gt-abc12), description, status, and assignee. Beads are stored as JSON and tracked in Git, providing persistent work state that survives agent crashes and restarts.
What is the Mayor in Gas Town?
The Mayor is your primary AI coordinator—a Claude Code instance with full context about your workspace, projects, and agents. Instead of managing individual agents directly, you communicate with the Mayor about what you want built, and it orchestrates the spawning and coordination of worker agents (Polecats) automatically.
Does Gas Town work with other AI tools besides Claude Code?
Yes, Gas Town supports multiple AI coding runtimes including Claude Code (primary and recommended), Codex, Cursor, Gemini, Auggie, and Amp. You can configure different runtimes per-rig in the settings/config.json file.
Getting Started with Gas Town
Gas Town represents a significant step forward in AI-assisted development—moving from single-agent sessions to coordinated multi-agent workflows. The persistent work state through git-backed Hooks solves real problems that anyone scaling Claude Code has experienced.
That said, this is power-user territory. The costs are substantial, the learning curve is real, and the Mad Max terminology takes some getting used to. Start with a small project, run a single convoy, and gradually scale up as you understand the system.
For teams and enterprises managing large-scale AI development, Gas Town might be exactly what you need. For solo developers, consider whether the coordination overhead justifies the cost—or explore lighter-weight approaches first.
Try Gas Town
Gas Town is free and open source. Clone the repo and start coordinating your Claude Code agents today.