Multi-agent orchestration system for Claude Code, GitHub Copilot, and other AI agents with persistent work tracking
Gas Town is a workspace manager that lets you coordinate multiple AI coding agents (Claude Code, GitHub Copilot, Codex, Gemini, and others) working on different tasks. Instead of losing context when agents restart, Gas Town persists work state in git-backed hooks, enabling reliable multi-agent workflows.
| Challenge | Gas Town Solution |
|---|---|
| Agents lose context on restart | Work persists in git-backed hooks |
| Manual agent coordination | Built-in mailboxes, identities, and handoffs |
| 4-10 agents become chaotic | Scale comfortably to 20-30 agents |
| Work state lost in agent memory | Work state stored in Beads ledger |
graph TB
Mayor[The Mayor
AI Coordinator]
Town[Town Workspace
~/gt/]
Town --> Mayor
Town --> Rig1[Rig: Project A]
Town --> Rig2[Rig: Project B]
Rig1 --> Crew1[Crew Member
Your workspace]
Rig1 --> Hooks1[Hooks
Persistent storage]
Rig1 --> Polecats1[Polecats
Worker agents]
Rig2 --> Crew2[Crew Member]
Rig2 --> Hooks2[Hooks]
Rig2 --> Polecats2[Polecats]
Hooks1 -.git worktree.-> GitRepo1[Git Repository]
Hooks2 -.git worktree.-> GitRepo2[Git Repository]
style Mayor fill:#e1f5ff,color:#000000
style Town fill:#f0f0f0,color:#000000
style Rig1 fill:#fff4e1,color:#000000
style Rig2 fill:#fff4e1,color:#000000
Your primary AI coordinator. The Mayor is a Claude Code instance with full context about your workspace, projects, and agents. Start here - just tell the Mayor what you want to accomplish.
Your workspace directory (e.g., ~/gt/). Contains all projects, agents, and configuration.
Project containers. Each rig wraps a git repository and manages its associated agents.
Your personal workspace within a rig. Where you do hands-on work.
Worker agents with persistent identity but ephemeral sessions. Spawned for tasks, sessions end on completion, but identity and work history persist.
Git worktree-based persistent storage for agent work. Survives crashes and restarts.
Work tracking units. Bundle multiple beads that get assigned to agents. Convoys labeled mountain get autonomous stall detection and smart skip logic for epic-scale execution.
Git-backed issue tracking system that stores work state as structured data.
Bead IDs (also called issue IDs) use a prefix + 5-character alphanumeric format (e.g., gt-abc12, hq-x7k2m). The prefix indicates the item's origin or rig. Commands like gt sling and gt convoy accept these IDs to reference specific work items. The terms "bead" and "issue" are used interchangeably—beads are the underlying data format, while issues are the work items stored as beads.
Workflow templates that coordinate multi-step work. Formulas (TOML definitions) are instantiated as molecules with tracked steps. Two modes: root-only wisps (steps materialized at runtime, lightweight) and poured wisps (steps materialized as sub-wisps with checkpoint recovery). See Molecules.
A three-tier watchdog system keeps agents healthy:
Per-rig merge queue processor. When polecats complete work via gt done, the Refinery batches merge requests, runs verification gates, and merges to main using a Bors-style bisecting queue. Failed MRs are isolated and either fixed inline or re-dispatched.
Severity-routed issue escalation. Agents that hit blockers escalate via gt escalate, which creates tracked beads routed through the Deacon, Mayor, and (if needed) Overseer. Severity levels: CRITICAL (P0), HIGH (P1), MEDIUM (P2). See Escalation.
Config-driven capacity governor for polecat dispatch. Prevents API rate limit exhaustion by batching dispatch under configurable concurrency limits. Default is direct dispatch; set scheduler.max_polecats to enable deferred dispatch with the daemon. See Scheduler.
Session discovery and continuation. Discovers previous agent sessions via .events.jsonl logs, enabling agents to query their predecessors for context and decisions from earlier work.
gt seance # List discoverable predecessor sessions
gt seance --talk <id> -p "What did you find?" # One-shot question
Federated work coordination network linking Gas Towns through DoltHub. Rigs post wanted items, claim work from other towns, submit completion evidence, and earn portable reputation via multi-dimensional stamps. See Wasteland.
New to Gas Town? See the Glossary for a complete guide to terminology and concepts.
brew install dolt on macOS, or see github.com/dolthub/doltbrew install gastown, or see github.com/steveyegge/beads# Install Gas Town
$ brew install gastown # Homebrew (recommended)
$ npm install -g @gastown/gt # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest # From source (Linux only)
# macOS: go install produces unsigned binaries that macOS will SIGKILL.
# Use brew install (above) or install Dolt and clone/build with make:
$ brew install dolt
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ make build && mv gt $HOME/go/bin/
# Windows (or if go install fails): clone and build manually
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ go build -o gt.exe ./cmd/gt
$ mv gt.exe $HOME/go/bin/ # or add gastown to PATH
# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$HOME/go/bin"
# Create workspace with git initialization
gt install ~/gt --git
cd ~/gt
# Add your first project
gt rig add myproject https://github.com/you/repo.git
# Create your crew workspace
gt crew add yourname --rig myproject
cd myproject/crew/yourname
# Start the Mayor session (your main interface)
gt mayor attach
export GIT_USER="<your name>"
export GIT_EMAIL="<your email>"
export FOLDER="/Users/you/code"
export DASHBOARD_PORT=8080 # optional, host port for the web dashboard
docker compose build # only needed on first run or after code changes
docker compose up -d
docker compose exec gastown zsh # or bash
gt up
gh auth login # if you want gh to work
gt mayor attach
Run
gt install ~/gt --git &&
cd ~/gt &&
gt config agent list &&
gt mayor attach
and tell the Mayor what you want to build!
sequenceDiagram
participant You
participant Mayor
participant Convoy
participant Agent
participant Hook
You->>Mayor: Tell Mayor what to build
Mayor->>Convoy: Create convoy with beads
Mayor->>Agent: Sling bead to agent
Agent->>Hook: Store work state
Agent->>Agent: Complete work
Agent->>Convoy: Report completion
Mayor->>You: Summary of progress
# 1. Start the Mayor
gt mayor attach
# 2. In Mayor session, create a convoy with bead IDs
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human
# 3. Assign work to an agent
gt sling gt-abc12 myproject
# 4. Track progress
gt convoy list
# 5. Monitor agents
gt agents
Best for: Coordinating complex, multi-issue work
flowchart LR
Start([Start Mayor]) --> Tell[Tell Mayor
what to build]
Tell --> Creates[Mayor creates
convoy + agents]
Creates --> Monitor[Monitor progress
via convoy list]
Monitor --> Done{All done?}
Done -->|No| Monitor
Done -->|Yes| Review[Review work]
Commands:
# Attach to Mayor
gt mayor attach
# In Mayor, create convoy and let it orchestrate
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify
# Track progress
gt convoy list
Run individual runtime instances manually. Gas Town just tracks state.
gt convoy create "Fix bugs" gt-abc12 # Create convoy (sling auto-creates if skipped)
gt sling gt-abc12 myproject # Assign to worker
claude --resume # Agent reads mail, runs work (Claude)
# or: codex # Start Codex in the workspace
gt convoy list # Check progress
Best for: Predefined, repeatable processes
Formulas are TOML-defined workflows embedded in the gt binary (source in internal/formula/formulas/).
Example Formula (internal/formula/formulas/release.formula.toml):
description = "Standard release process"
formula = "release"
version = 1
[vars.version]
description = "The semantic version to release (e.g., 1.2.0)"
required = true
[[steps]]
id = "bump-version"
title = "Bump version"
description = "Run ./scripts/bump-version.sh {{version}}"
[[steps]]
id = "run-tests"
title = "Run tests"
description = "Run make test"
needs = ["bump-version"]
[[steps]]
id = "build"
title = "Build"
description = "Run make build"
needs = ["run-tests"]
[[steps]]
id = "create-tag"
title = "Create release tag"
description = "Run git tag -a v{{version}} -m 'Release v{{version}}'"
needs = ["build"]
[[steps]]
id = "publish"
title = "Publish"
description = "Run ./scripts/publish.sh"
needs = ["create-tag"]
Execute:
# List available formulas
bd formula list
# Run a formula with variables
bd cook release --var version=1.2.0
# Create formula instance for tracking
bd mol pour release --var version=1.2.0
Best for: Direct control over work distribution
# Create convoy manually
gt convoy create "Bug Fixes" --human
# Add issues to existing convoy
gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x
# Assign to specific agents
gt sling gt-m3k9p myproject/my-agent
# Check status
gt convoy show
Gas Town supports multiple AI coding runtimes. Per-rig runtime settings are in settings/config.json.
{
"runtime": {
"provider": "codex",
"command": "codex",
"args": [],
"prompt_mode": "none"
}
}
Notes:
.claude/settings.json (managed via --settings flag) for mail injection and startup.project_doc_fallback_filenames = ["CLAUDE.md"] in
~/.codex/config.toml so role instructions are picked up.gt prime, optional gt mail check --inject
for autonomous roles, and gt nudge deacon session-started.copilot) is a built-in preset using --yolo for autonomous
mode. It uses executable lifecycle hooks in .github/hooks/gastown.json (same events
as Claude: sessionStart, userPromptSubmitted, preToolUse, sessionEnd). Uses a
5-second ready delay instead of prompt detection. Requires a Copilot seat and org-level
CLI policy. See docs/INSTALLING.md.gt install <path> # Initialize workspace
gt rig add <name> <repo> # Add project
gt rig list # List projects
gt crew add <name> --rig <rig> # Create crew workspace
gt agents # List active agents
gt sling <bead-id> <rig> # Assign work to agent
gt sling <bead-id> <rig> --agent cursor # Override runtime for this sling/spawn
gt mayor attach # Start Mayor session
gt mayor start --agent auggie # Run Mayor with a specific agent alias
gt prime # Context recovery (run inside existing session)
gt feed # Real-time activity feed (TUI)
gt feed --problems # Start in problems view (stuck agent detection)
Built-in agent presets: claude, gemini, codex, cursor, auggie, amp, opencode, copilot, pi, omp
gt convoy create <name> [issues...] # Create convoy with issues
gt convoy list # List all convoys
gt convoy show [id] # Show convoy details
gt convoy add <convoy-id> <issue-id...> # Add issues to convoy
```bash
gt config agent set c
$ claude mcp add gastown \
-- python -m otcore.mcp_server <graph>