Skip to main content

Gas Town Documentation

Gas Town is a multi-agent orchestration system that coordinates fleets of AI coding agents working on your projects simultaneously. Built on top of Claude Code, it scales from a single agent to 20-30 concurrent workers — all managed through the gt CLI.

What is Gas Town?​

Gas Town solves the hard problems of multi-agent AI development:

ChallengeGas Town Solution
Agents lose context on restartWork persists in git-backed hooks
Manual coordination breaks at scaleBuilt-in mailboxes, identities, handoffs
Chaos beyond 4-10 agentsScales to 20-30 agents comfortably
Lost work stateStored in Beads issue tracking system
No merge coordinationRefinery serializes merges to main

How It Works​

You talk to the Mayor, who coordinates everything. The Mayor creates Convoys (batches of work), assigns tasks to Polecats (ephemeral workers), while Witnesses monitor health and the Refinery handles merges.

Quick Start​

# Install
brew install gastown

# Create workspace
gt install ~/gt --git
cd ~/gt

# Add a project
gt rig add myproject https://github.com/you/repo.git

# Start the Mayor and give instructions
gt mayor attach

Then tell the Mayor what to build. It handles the rest.

Key Concepts at a Glance​

  • Town — Your workspace directory containing all projects
  • Rigs — Project containers wrapping git repositories
  • Beads — Git-backed issue tracking (bd CLI)
  • Convoys — Batches of related work items tracked together
  • Hooks — Persistent work state that survives crashes and restarts
  • Polecats — Ephemeral worker agents that spawn, complete a task, then exit
  • Molecules — Multi-step workflow execution units
SectionDescription
Getting StartedInstallation, setup, and first convoy
ArchitectureSystem design and agent hierarchy
CLI ReferenceComplete gt command reference
AgentsDetailed guide to each agent role
Core ConceptsBeads, hooks, convoys, molecules, and more
WorkflowsCommon workflow patterns
OperationsRunning, monitoring, and troubleshooting
GuidesUsage guide, philosophy, and tips

Origin​

Gas Town is created by Steve Yegge and named after the oil refinery citadel in Mad Max. The alternative name "Gastown" references Vancouver B.C.'s historic Gastown district.