Gas Town - multi-agent workspace manager
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.
…
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.
Choose one of the two setup paths below: install Gas Town on your host, or run it inside a Docker container.
Native installs require the host tools below. Docker installs only require Docker Compose on the host; the image supplies Go, Dolt, bd, tmux, and CLI utilities inside the container. The platform steps below say when a path installs gt, bd, and dolt for you and when you install them separately.
go.mod)
Required for the Linux and Windows paths and for macOS source builds. Not needed for brew install gastown or Docker setup.
Beads (bd)
0.57.0+
Required for native installs. Homebrew and Docker supply it; source/native Go paths install it with go install.
sqlite3
any
Used by convoy database queries. Usually pre-installed on macOS and Linux.
ICU4C dev headers
varies
Required for source builds that compile the ICU-backed query layer. Use libicu-dev on Debian/Ubuntu, libicu-devel on Fedora/RHEL, icu4c on macOS, and MSYS2 ICU packages for native Windows.
tmux
3.0+
Required for gt up and the tmux-backed roles (Mayor, Witnesses, Refineries, polecats). Optional only for minimal-mode workflows where you run runtime instances manually.
Claude Code CLI
latest
Default runtime. See Runtime Configuration for alternatives (Codex, Copilot, Gemini, Cursor).
Install the prerequisites listed above, then install gt for your platform.
Homebrew installs gt, bd, and dolt together.
brew install gastown
Avoid go install on macOS. The unsigned binary it produces gets killed by Gatekeeper. To build from source, install Dolt and ICU4C with Homebrew, install bd with Go, then build and install gt with make install. Put $HOME/.local/bin and $HOME/go/bin ahead of any stale binary locations on your PATH so the freshly installed gt and bd take precedence.
brew install dolt icu4c
go install github.com/steveyegge/beads/cmd/bd@latest
export PATH="$HOME/.local/bin:$HOME/go/bin:$PATH"
git clone https://github.com/steveyegge/gastown.git
cd gastown
make install
Install Dolt by following the Dolt installation guide, then install gt and bd with go install.
go install github.com/steveyegge/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest
Prepend the Go binary directory to your PATH if it is not already there, so freshly installed gt and bd binaries take precedence over stale copies. Append to ~/.zshrc instead if you use zsh.
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Install Dolt first by following the Dolt installation guide. Unlike the macOS Homebrew path, go install does not install Dolt. Then install gt and bd with go install.
go install github.com/steveyegge/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest
Both binaries land in %USERPROFILE%\go\bin\. Put that directory before older gt or bd install locations on PATH, then open a new shell for the change to take effect.
Native Windows source builds that compile the ICU-backed query layer need an MSYS2 UCRT64 or MinGW64 shell with matching icu, toolchain, and pkg-config packages; the repository's Windows CI uses pacboy -S icu:p toolchain:p pkg-config:p. Plain PowerShell/MSVC is not enough for that CGO build.
For full tmux-backed workflows on Windows, use WSL or another Linux environment. Native Windows shells are best treated as minimal CLI-only environments.
Run gt install to create your headquarters (HQ) at ~/gt. The --shell flag installs shell integration and enables Gas Town globally. The --git flag initializes the HQ as a git repository. Before using --git, set git config --global user.name and git config --global user.email so the initial commit has a valid identity.
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
gt install ~/gt --shell --git
cd ~/gt
Start the long-lived services. gt up boots Dolt, the daemon, the Deacon, the Mayor, and per-rig Witnesses and Refineries.
gt up
Verify the install. The --fix flag clears the warnings that gt install does not preempt.
gt doctor --fix
Use gt rig add to clone a repository into your HQ as a rig.
gt rig add myproject https://github.com/you/repo.git
Rig names accept letters, digits, and underscores. Hyphens, dots, spaces, and path separators are not allowed. Use my_project instead of my-project.
To set a custom beads prefix for the rig, pass --prefix.
gt rig add myproject https://github.com/you/repo.git --prefix mp
A crew workspace is a personal git clone where you do hands-on work.
gt crew add yourname --rig myproject
cd myproject/crew/yourname
The Mayor coordinates work across rigs.
gt mayor attach
docker-compose.yml runs Gas Town inside a sandbox container. The container hosts an HQ at /gt, which Compose bind-mounts from ${FOLDER} on the host. The entrypoint runs gt install /gt --git against that directory on first start, so FOLDER must point at an empty directory that you want to become the HQ or an existing Gas Town HQ. Set GIT_USER and GIT_EMAIL so git and Dolt commits do not use the default test identity. See the full Docker guide for lifecycle, storage, and security details.
export GIT_USER="<your name>"
export GIT_EMAIL="<your email>"
export FOLDER="/path/to/empty/dir" # empty directory or existing Gas Town HQ
export DASHBOARD_PORT=8080 # optional, host port for the dashboard
mkdir -p "$FOLDER"
docker compose build # only needed on first run or after code changes
docker compose up -d
docker compose logs -f gastown # wait for "HQ created successfully!", then Ctrl-C
docker compose exec gastown zsh # or bash
Inside the container, finish bootstrapping.
gt enable # enable Gas Town global state
gt shell install # install shell integration
gt up --restore # start services and restore worker settings
gh auth login # optional: required for private GitHub rigs
gt mayor attach
The dashboard port is exposed from the container to the host. Treat it as a trusted local-network surface, and do not point FOLDER at a host workspace that a native gt install is using at the same time.
Run
git config --global user.name "Your Name" &&
git config --global user.email "[email protected]" &&
gt compact is a no-op across all wisp categories while gt compact report counts tens of thousands as active
Hook durability silently broken: gt patrol report / gt hook leave agent hook_bead null, causing an orphaned patrol wisp every cycle
Dog molecule dispatch: pour emits N per burst, dispatcher consumes 0..1 with 4 idle workers — surplus roots closed unassigned in 0-6s, children orphaned (~52/h)
dolt_backup patrol queries dolt_remotes instead of dolt_backups — backups silently never run
bd record assignee/status spontaneously reverts to open/unassigned despite active heartbeated lease