# Gas Town: features, protocols, quickstart

## TL;DR

Gas Town is an MIT-licensed Go CLI, hosted in the gastownhall GitHub organization, that coordinates many coding agents through tmux. A Mayor agent assigns work items called beads, workers keep git-backed state, and a merge queue lands results. The README targets 20 to 30 agents; it suits experienced users who accept the setup overhead.

## Key facts

| Field | Value |
| --- | --- |
| Type | Orchestrator |
| Languages / SDKs | Go |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 18,219 (as of 2026-09-30) |
| GitHub forks | 1,676 |
| Last push | 2026-09-29 |
| Latest release | v1.2.1 |
| Repository | [gastownhall/gastown](https://github.com/gastownhall/gastown) |
| Documentation | [github.com](https://github.com/gastownhall/gastown/tree/main/docs) |
| Last verified | 2026-09-30 |

## Key features

- A Mayor, a Claude Code instance by default, acts as the coordinator that creates convoys and slings work items (beads) to agents. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Worker agents (polecats) have persistent identity but ephemeral sessions; their work state lives in git worktree-based hooks and the Beads ledger. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Built-in agent presets include claude, codex, opencode, gemini, cursor, copilot, amp, pi and others, and a per-sling `--agent` flag overrides the runtime. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- A Refinery processes a per-rig merge queue, running verification gates and merging with a bisecting queue; failed merge requests are isolated. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- A three-tier watchdog (Witness, Deacon, Dogs) detects stuck agents, and `gt feed --problems` lists agents that need human intervention. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Severity-routed escalation (`gt escalate`) passes blockers up through Deacon, Mayor and a human Overseer. ([source](https://github.com/gastownhall/gastown/blob/main/docs/design/escalation.md))
- A scheduler caps polecat dispatch concurrency to avoid API rate-limit exhaustion, and formulas (TOML) define repeatable multi-step workflows. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Wasteland links separate Gas Towns through DoltHub so rigs can post and claim work. ([source](https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md))

## Architecture and orchestration pattern

Pattern: Supervisor.

Gas Town keeps a town workspace (default `~/gt`) that contains rigs, one per git repository. Agents run as tmux sessions of ordinary coding-agent CLIs; Gas Town launches them, sends input with tmux and environment variables, and does not link against agent code. Roles are the Mayor (global coordinator), Deacon (background supervisor), per-rig Witness (lifecycle manager) and Refinery (merge queue), and workers: polecats (Witness-managed) and crew (user-managed clones).

Work is tracked as beads in the Beads git-backed issue store on Dolt, grouped in convoys and dispatched with `gt sling`. Polecat state is stored in git worktree-based hooks so a crashed or restarted session can resume; the Mayor and agents exchange mail and nudges. When a polecat finishes with `gt done`, the Refinery verifies and merges to main.

A minimal mode skips tmux: convoys and slings track state while the user runs `claude` or `codex` by hand. The Docker Compose setup runs the whole town in a container.

### Human in the loop

The human is the Overseer at the top of the escalation chain: agents that cannot resolve a blocker escalate to the Deacon, then the Mayor, then the Overseer, with CRITICAL and HIGH items also routed by email or SMS. Convoys can name subscribers with `--notify`, including `--human`, who are told when the convoy lands (all tracked issues closed). The user can attach to the Mayor session at any time and monitors work with `gt convoy list`, `gt agents` and `gt feed`. There is no documented per-action approval gate; the Refinery merges after its verification gates.

### Harnesses it can drive

- Claude Code ([evidence](https://github.com/gastownhall/gastown/blob/main/README.md))
- Codex ([evidence](https://github.com/gastownhall/gastown/blob/main/README.md))
- OpenCode ([evidence](https://github.com/gastownhall/gastown/blob/main/README.md))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Unknown (checked 2026-09-30) | — | Searched the README and docs folder. The docs mention MCP only as a threat vector in a design proposal and, in an integration guide, as a property of a separate messaging tool; no MCP client or server in Gas Town is documented. |
| A2A | Unknown (checked 2026-09-30) | — | Searched the README and docs for 'a2a' and 'agent2agent'; nothing found. Inter-agent communication uses Gas Town's own mail and nudges. |
| AG-UI | Unknown (checked 2026-09-30) | — | Searched the README, docs and file names for 'ag-ui'; nothing found. |

## Best for

- Experienced users coordinating 20 or more Claude Code, Codex or other CLI agents across several repositories, with a Mayor assigning work. ([shortlist](https://multiagentguide.top/best/parallel-coding-agents.md))
- Long-running work that must survive agent crashes and restarts, using git-backed hooks and the Beads ledger. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Repeatable multi-step processes expressed as formulas and molecules. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Routing blockers to a human by severity with `gt escalate`.

## Not for

- Newcomers wanting a quick start: native install needs Git, Go, Beads, Dolt, tmux and a coding-agent CLI.
- Native Windows users who want the full workflow: the README says tmux-backed workflows need WSL and native shells are minimal CLI-only.
- Anyone who needs sandboxed agent execution by default: a repository design proposal says polecats run on the host under the user's account.

## Quickstart

```sh
brew install gastown
```

Install not yet verified by this site.

```bash
brew install gastown                       # installs gt, bd and dolt (macOS)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

gt install ~/gt --shell --git             # create the town (HQ)
cd ~/gt
gt up                                      # start Dolt, daemon, Deacon, Mayor, Witnesses, Refineries
gt doctor --fix

gt rig add myproject https://github.com/you/repo.git
gt mayor attach                            # tell the Mayor what to build

gt convoy create "Feature X" gt-abc12 --notify --human   # inside the Mayor session
gt sling gt-abc12 myproject                # assign a bead to a worker
gt convoy list
gt agents
```

### Common pitfalls

- Native installs need Git 2.20+, Go 1.26.2+ (Linux, Windows, source builds), Beads (`bd`) 0.57.0+, sqlite3, tmux 3.0+ and a coding-agent CLI (Claude Code is the default runtime).
- On macOS use `brew install gastown`; the README says `go install` produces a binary that Gatekeeper kills.
- Windows: full tmux-backed workflows need WSL; native shells are minimal CLI-only, and source builds need an MSYS2 toolchain with ICU.
- Rig names allow letters, digits and underscores only (`my_project`, not `my-project`).
- For Codex, set `project_doc_fallback_filenames = ["CLAUDE.md"]` in `~/.codex/config.toml`; runtimes without hooks get a startup fallback.
- The GitHub Copilot preset uses `--yolo` and needs a Copilot seat.
- With Docker Compose, do not point FOLDER at a workspace a native install is using, and treat the dashboard port as a trusted local-network surface.

Official quickstart: https://github.com/gastownhall/gastown/blob/main/README.md

## Pros

- Persistent work state in git worktree hooks and a ledger, so agents can be restarted without losing context. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Agent-agnostic through presets and a documented tiered integration model; any terminal CLI works at tier zero. ([source](https://github.com/gastownhall/gastown/blob/main/docs/agent-provider-integration.md))
- Built-in supervision: watchdog roles, stuck-agent detection, a merge queue and severity-based escalation. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Minimal mode and a Docker Compose setup give lighter or containerized ways to run it. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- MIT licensed, with active commits in September 2026. ([source](https://github.com/gastownhall/gastown))

## Cons

- Heavy prerequisites and vocabulary (rigs, beads, convoys, molecules, Dolt, tmux) make setup and learning slow. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- A design proposal in the repo states polecats run on the host under the user's account with full filesystem, network and credential access; sandboxed execution was a proposal. ([source](https://github.com/gastownhall/gastown/blob/main/docs/design/sandboxed-polecat-execution.md))
- The Refinery merges verified work to main automatically; the docs describe no per-merge human approval step. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- Native Windows is limited to minimal CLI-only use; full workflows need WSL. ([source](https://github.com/gastownhall/gastown/blob/main/README.md))
- The latest tagged release (v1.2.1) is from 2026-06-06 while main continues to receive commits, so releases lag the repository. ([source](https://github.com/gastownhall/gastown/releases))

## Alternatives

- [Claude Squad](https://multiagentguide.top/tools/claude-squad.md)
- [Vibe Kanban](https://multiagentguide.top/tools/vibe-kanban.md)
- [Ruflo](https://multiagentguide.top/tools/ruflo.md)
- [Orca](https://multiagentguide.top/tools/orca.md)
- [Herdr](https://multiagentguide.top/tools/herdr.md)

## FAQ

### Does Gas Town support MCP?

Not according to the README or docs I read, so the record marks it unknown. It coordinates agents through tmux, mail and its own CLI.

### Which coding agents does it run?

Claude Code is the default runtime. Built-in presets include Codex, OpenCode, Gemini, Cursor, Copilot, Amp and others, and any CLI that runs in a terminal works at the basic integration tier. OpenClaw and Hermes are not listed.

### Is Gas Town free?

Yes. It is MIT licensed and no paid product is documented. Your coding agents' own usage costs are separate, and the scheduler can cap concurrent workers.

### How does it isolate parallel work?

Polecat work state lives in git worktree-based hooks, and crew members have their own clones. The docs describe worktrees for state, not a sandbox for execution.

### Does it require tmux?

The tmux-backed roles (Mayor, Witnesses, Refineries, polecats) need tmux 3.0+. A minimal mode without tmux only tracks state while you run the agent CLIs yourself.

## Sources

- [Gas Town GitHub repository](https://github.com/gastownhall/gastown)
- [Gas Town README](https://github.com/gastownhall/gastown/blob/main/README.md)
- [Gas Town docs folder](https://github.com/gastownhall/gastown/tree/main/docs)
- [Docs: Escalation protocol](https://github.com/gastownhall/gastown/blob/main/docs/design/escalation.md)
- [Docs: Wasteland](https://github.com/gastownhall/gastown/blob/main/docs/WASTELAND.md)
- [Docs: Convoys](https://github.com/gastownhall/gastown/blob/main/docs/concepts/convoy.md)
- [Docs: Agent provider integration guide](https://github.com/gastownhall/gastown/blob/main/docs/agent-provider-integration.md)
- [Docs: Sandboxed polecat execution (proposal)](https://github.com/gastownhall/gastown/blob/main/docs/design/sandboxed-polecat-execution.md)
- [Gas Town releases](https://github.com/gastownhall/gastown/releases)

## Unknown fields

homepage is null: the GitHub snapshot has no homepage and no official site was found in the README. protocols.mcp, a2a, agui: nothing found in the README or docs beyond incidental mentions (MCP as a threat vector in a proposal). The README credits Steve Yegge's repository path for clone commands; the current repository is under gastownhall. Cost of running many agents is not documented in the README.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/gastown