Gas Town
Kubernetes for AI coding agents. A Mayor coordinates 20–30 Claude Code workers in parallel tmux sessions, with persistent git-backed work tracking via Beads.
What Is Gas Town?
Not another AI coding assistant. An orchestration system that turns one developer into a factory floor of coordinated AI workers.
Gas Town is a multi-agent workspace manager for Claude Code. Instead of one conversation with one AI, you run a Mayor agent that coordinates an entire fleet of worker agents — each in its own tmux terminal, its own git worktree, working on a distinct task in parallel.
The core problem it solves: when you scale from 1 agent to 10+, you lose the ability to track what each is doing. Context gets lost on restart. Work states vanish from agent memory. Merge conflicts multiply. Gas Town treats these as infrastructure problems, borrowing from Kubernetes-style orchestration: persistent state, reconciliation loops, and a declarative control plane.
Steve Yegge describes it as targeting developers at "level 6+" in his 8-stage progression model — people already running multiple parallel CLI agents who need centralized management. If you are not already juggling multiple Claude Code sessions daily, Gas Town will feel counterproductive.
| Kubernetes | Gas Town | Shared Concept |
|---|---|---|
| Control plane | Mayor agent | Central coordination |
| Pods (ephemeral) | Polecats (ephemeral) | Sessions are cattle, not pets |
| etcd (persistent state) | Beads (git-backed) | Source of truth survives restarts |
| Reconciliation loop | Deacon patrol | Desired state vs. actual state |
| Node monitoring | Witness | Health checks on workers |
If you have ever thought "I wish I had 100 Claude Codes," Gas Town is for you.
— DoltHub, "A Day in Gas Town"The Mayor/Worker Model
A hierarchy of seven specialized agent roles, each with a distinct responsibility. Sessions are ephemeral; identities and work state persist in git.
Mayor
Your primary interface. A Claude Code instance with full workspace context. You tell it what to build; it decomposes work, creates convoys, and delegates to workers. Start every session here with gt mayor attach.
Polecats
Worker agents with persistent identity but ephemeral sessions. Spawned by the Mayor for specific tasks. They code in isolated git worktrees, push branches, open PRs. When they crash, the next session picks up from the last checkpoint.
Refinery
Manages the merge queue. When 20 agents are all producing branches, something has to prevent collisions. The Refinery serializes merges and handles conflicts.
Witness
Health monitor for worker agents. Detects stuck or crashed sessions. Feeds status back to the Mayor and Deacon for recovery decisions.
Deacon
Runs patrol loops — the reconciliation engine. Periodically checks whether desired state (tasks assigned) matches actual state (tasks completed). Nudges idle agents within 30–60 seconds.
Dogs
Handle maintenance tasks: cleanup, housekeeping, and background operations that keep the town running smoothly without human intervention.
Crew
Your personal workspace within a rig. Where you do hands-on work alongside the agents — reviewing output, making design decisions, and collaborating on architecture.
Nondeterministic Idempotence
Unlike Temporal's deterministic replay (which Yegge tried and abandoned in his v1 prototype), Gas Town achieves durability differently. If an agent crashes mid-step, the next session resumes from that point. The agent may take a completely different approach the second time — the path is nondeterministic — but the outcome converges because the workflow definition persists and each step has explicit acceptance criteria.
This is the key architectural insight: nothing is permanently lost, even though work can be chaotic in the moment.
Gas Town was like riding a wild stallion that needed to be tamed.
— DoltHub engineer, after first day testing Gas TownThe Beads Ecosystem
Beads is the distributed, git-backed graph issue tracker that serves as Gas Town's memory, control plane, and work tracking system. Both a standalone tool and Gas Town's backbone.
Beads replaces ad-hoc markdown planning files with a structured, queryable dependency graph. Every task, bug, and work item is a "bead" with a hash-based ID (e.g., bd-a3f8) that prevents merge collisions across multi-agent workflows. The terms "bead" and "issue" are used interchangeably.
Backed by Dolt — a version-controlled SQL database — Beads gets cell-level merge, native branching, and sync via Dolt remotes. Work is expressed as "molecules": chained sequences of small tasks. Each step declares dependencies and acceptance criteria.
Agent-Optimized
JSON output, dependency tracking, auto-ready task detection. Built for machines to read and write, not humans to browse.
Zero Conflict
Hash-based IDs prevent merge collisions when 20+ agents create issues simultaneously across branches.
Compaction
Semantic "memory decay" that summarizes closed tasks. Conserves context window space during long sessions.
Hierarchical IDs
Three-level structure: bd-a3f8 (epic) → bd-a3f8.1 (task) → bd-a3f8.1.1 (subtask).
Messaging
Dedicated message issue type supporting threading and ephemeral lifecycle. Agents communicate through mail beads.
Graph Links
Relationship types: relates_to, duplicates, supersedes, replies_to. Full dependency graph.
# Essential Beads commands
bd ready # List tasks with no open blockers
bd create "Fix auth bug" -p 0 # Create priority-0 task
bd update bd-a3f8 --claim # Atomically claim a task
bd dep add bd-a3f8.1 bd-a3f8 # Link dependency
bd show bd-a3f8 # Show details + audit trail
bd issues --status open # Filter by status
Installation & Prerequisites
Gas Town has a real dependency chain. This is infrastructure software, not a quick npm install.
# Install Gas Town
brew install gastown # Homebrew (recommended)
npm install -g @gastown/gt # npm alternative
go install github.com/steveyegge/gastown/cmd/gt@latest # from source
# Initialize workspace
gt install ~/gt --git # Create town with git init
cd ~/gt
# Add a project
gt rig add myproject https://github.com/you/repo.git
# Create your crew workspace
gt crew add yourname --rig myproject
# Start the Mayor
gt mayor attach # Enter the Mayor's office
How It Works
A step-by-step walkthrough of a typical Gas Town session, from giving the Mayor a directive to reviewing completed work.
Attach to the Mayor
Open a terminal and connect to the Mayor's tmux session. This is your single point of interaction with the entire fleet.
gt mayor attachGive a Natural Language Directive
Tell the Mayor what you want to build or fix. "Add OAuth support to the API" or "Fix the 4 failing integration tests." The Mayor decomposes this into discrete, scoped tasks.
Mayor Creates a Convoy
A convoy bundles related beads (issues) into a trackable work unit. Each bead has acceptance criteria and dependency links. The convoy is the unit of coordination.
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notifyWorkers Spawn Automatically
Polecats spin up in separate tmux sessions, each with its own git worktree. They claim tasks atomically, code, run tests, commit, and push branches. 20+ agents can run simultaneously.
gt sling gt-x7k2m myprojectMonitor Progress
Watch the live activity feed or check convoy status. The Witness monitors agent health. The Deacon nudges idle agents. You can also switch tmux panes to watch individual workers.
gt feed gt convoy list gt feed --problemsWork Persists in Hooks
Agent state is stored in git-backed hooks (worktrees), not in agent memory. If a worker crashes or hits context limits, the next session picks up from the last checkpoint. Nothing is permanently lost.
Review and Merge
Workers open PRs. The Refinery manages the merge queue. The Mayor consolidates status and presents a summary. You review, approve, and the cycle continues.
The bottleneck is no longer the agents themselves. It's keeping them fed with work.
— Nate's Newsletter, on running 10–20 parallel Gas Town agentsConfiguration
Gas Town supports multiple AI runtimes and per-rig configuration. Key options for tuning the system.
Runtime Configuration
Per-rig settings live in settings/config.json. Gas Town ships with built-in presets for multiple runtimes.
| Command | Purpose |
|---|---|
| gt config agent list | Show available agent presets (claude, gemini, codex, cursor, auggie, amp) |
| gt config agent set NAME "cmd" | Define a custom agent preset, e.g., gt config agent set claude-glm "claude-glm --model glm-4" |
| gt config default-agent NAME | Set the default runtime for new workers |
| gt config show | Display current configuration |
| gt mayor start --agent NAME | Start the Mayor with a specific agent alias |
| gt sling ID RIG --agent NAME | Override runtime for a specific task assignment |
| gt prime | Context recovery inside an existing session (re-injects role and state) |
Workflow Modes
Mayor Workflow (recommended): Full orchestration. Mayor decomposes, delegates, monitors. Best for complex multi-issue work.
Minimal Mode (no tmux): Run individual runtime instances manually. Gas Town just tracks state via convoys. Good for getting started.
Beads Formula Workflow: Predefined, repeatable TOML-based processes. Each step declares needs dependencies. Think CI pipelines for agent work.
Manual Convoy: Direct control over work distribution. Create convoys by hand, assign to agents explicitly.
Cost
Running 20+ parallel Claude instances is expensive. Here are real numbers from practitioners.
Yegge runs 3 concurrent Claude Max accounts ($100/mo each) to maintain throughput. This is the floor — just the subscription cost before any API overages.
Running 12–30 parallel agents burns tokens rapidly. One early adopter reported approximately $100/hour in API credits during peak orchestration. Roughly 10x a single Claude Code session.
Compared to a standard single-agent Claude Code session. The cost scales linearly with agent count. You are trading money for parallelism and throughput.
Is It Worth It?
Yegge's position: the bottleneck has shifted from agent capability to work supply. If you can keep 20 agents fed with well-scoped tasks, the throughput is genuinely real — Gas Town can run overnight unattended. The question is whether your project benefits from that parallelism enough to justify the cost. Greenfield projects with clear decomposition benefit most. Complex existing codebases with tight coupling benefit least.
Key Quotes
Steve Yegge on vibe coding, agent orchestration, and where software development is headed.
Trust equals predictability, not capability. It takes roughly 2,000 hours of daily use before you can reliably predict LLM behavior.
— Steve Yegge, Latent Space podcastIf you're still using an IDE to develop code by January 1st, you're a bad engineer.
— Steve Yegge, AI Engineer SummitJoel Spolsky's "never rewrite" rule is now obsolete for a growing class of codebases. Rewriting from scratch is now faster than refactoring.
— Steve Yegge, on the economics of AI-generated codeCurrent tools — Claude Code, Cursor — are already obsolete. The future is agent orchestration dashboards. Factory farming of code.
— Steve Yegge, Latent Space podcastGas Town isn't super vertically scalable. A town is about machine-sized. Gas Town scales by having lots of towns, much like Git scales by having lots of repos.
— Steve Yegge, "The Future of Coding Agents"From Vibecoder to VC to Gas Town
Gas Town is v3 of Yegge's orchestration vision. Each iteration taught hard lessons about what works.
v1: Vibecoder (TypeScript + Temporal)
350K lines of TypeScript. Built on Temporal, the gold standard for workflow orchestration. Proved cumbersome — the workflows being orchestrated turned out to be micro-workflows, since you have to severely decompose tasks for LLMs to reliably follow them. Temporal's deterministic replay was too heavy for this pattern.
v2: VC (Go, Simple Event Loop)
Complete rewrite in Go. Dropped Temporal for a simple event loop. AI-supervised issue workflow: claim issue, assess strategy, execute, analyze output, run quality gates, decide next steps. Achieved 90.9% quality gate pass rate over 24 missions. Self-hosted — the system improves its own codebase. Beads v0.12.0 (SQLite-backed) delivered 100x performance over the prior shell-based CLI.
v3: Gas Town (Go, Full Orchestration)
The current system. Adds the Mayor/worker hierarchy, tmux-based multi-agent sessions, Convoys for work tracking, the Refinery merge queue, and the full Beads ecosystem backed by Dolt. 100% vibe coded — ~130K lines of Go, roughly half tests. Tens of thousands of users on Beads alone. MIT licensed.
Limitations & Trade-offs
Yegge himself is transparent about these. Gas Town is powerful but not for everyone.
Expensive at Scale
~$100/hour at full speed. Requires multiple Claude Max subscriptions. The cost-benefit ratio only makes sense if your project genuinely benefits from parallel throughput.
Expert-Only Tool
Targets developers already running 10+ parallel CLI agents daily. Yegge's own progression model puts this at "level 6+" out of 8. Most developers will find it counterproductive.
Chaotic Parallelism
Bugs can get fixed multiple times by different agents. Designs occasionally go missing. Workers may autonomously merge PRs despite failing tests. It is described as "managing a very fast, very junior dev team."
YOLO Defaults
Out of the box, agents can merge PRs without adequate human gates. Early adopters report needing to force-push to recover from premature merges. Requires careful configuration of guardrails.
Better for Greenfield
Complex existing codebases with tight coupling produce poor results. DoltHub's test on their established codebase: 4 PRs created, all eventually closed as inadequate. Greenfield projects with clear task decomposition benefit most.
Horizontal Scaling Only
A single town is "about machine-sized." Gas Town scales by having lots of towns — like Git scales by having lots of repos — which pushes the scaling problem onto the user.
Security Requires Vigilance
Agents can accidentally expose credentials or make costly errors. Never give agents access to sensitive accounts without controls. All AI output requires stringent review and QA.
Heavy Dependency Chain
Requires Go, Git 2.25+, Dolt, Beads, sqlite3, tmux, and a Claude Code subscription. This is not a self-contained tool — it is infrastructure.
Links & Resources
Primary sources used in this deep dive.