# Gas Town: a workspace manager for running 20 to 30 AI coding agents

> Gas Town is a Go CLI that keeps multi-agent coding work in git-backed hooks and a Beads ledger so context survives agent restarts. It is a heavy install, and the README says it is aimed at fleets of 20 to 30 agents.

**gastownhall/gastown** — Gas Town - multi-agent workspace manager

- Repository: https://github.com/gastownhall/gastown
- Stars: 18,220 · Forks: 1,677
- Language: Go
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/gastownhall-gastown

## What Gas Town solves, and the agent count it assumes

The README frames the problem as context loss. An agent that restarts loses whatever it was holding in its session, and a human then has to reconstruct the task by hand. Gas Town's answer is to move work state out of the agent and into two persistent stores: git-backed hooks, which are git worktrees, and a Beads ledger, described as a git-backed issue tracking system that stores work state as structured data. The README's comparison table puts the intended scale at 20 to 30 agents, up from the 4 to 10 that it says become chaotic without coordination.

That number is the most useful thing in the README, because it tells you who the project is not for. One agent on one repository does not need a Mayor, rigs, a Refinery merge queue and a three-tier watchdog. Gas Town is for someone already running several Claude Code, Copilot, Codex or Gemini sessions in parallel and losing track of which one is doing what. The README lists those runtimes by name and calls Claude Code the default.

## Town, rigs, hooks and polecats: the actual layout

The workspace is a directory, shown as ~/gt/, called the Town. Inside it sit rigs, and a rig wraps one git repository together with the agents attached to it. Each rig contains a Crew Member workspace for hands-on work, hooks for persistent storage, and polecats, which are worker agents with a persistent identity but an ephemeral session. The README is explicit that a polecat's session ends when its task completes while its identity and work history persist, which is the mechanism behind the restart claim: the session is disposable, the identity is not.

Hooks are git worktrees, and the architecture diagram draws them pointing back at the underlying git repository. That choice matters. Because the storage is a worktree rather than a database, the state is inspectable with ordinary git commands and can be pushed like any branch. The Beads ledger supplies the structured side, with bead IDs in a prefix plus five-character alphanumeric format such as gt-abc12 or hq-x7k2m, and commands like gt sling and gt convoy accept those IDs. The README notes that bead and issue are used interchangeably.

Above the rigs sits the Mayor, described as a Claude Code instance with context about the workspace, projects and agents. The README says to start there and simply state what you want done. That is a design commitment worth noticing: the coordination layer is itself an AI agent, not a deterministic scheduler, so the quality of coordination depends on the model behind it.

## Installing Gas Town and running a first convoy

The README offers two paths: a native install on the host, or a Docker container. Native installs need Git 2.20+ for worktree support, Go 1.26.2+ as pinned in go.mod, Beads (bd) 0.57.0+, sqlite3 for convoy database queries, tmux 3.0+ for gt up and the tmux-backed roles, and ICU4C development headers if you compile the ICU-backed query layer. The README says Homebrew and Docker supply bd for you, and that the source and native Go paths install it with go install. Go is not needed for brew install gastown or for the Docker setup.

If you build from source, the Makefile produces three binaries into the repository root: gt, gt-proxy-server and gt-proxy-client. On macOS the Makefile detects the Homebrew icu4c prefix and exports the CGo flags itself, which is a small convenience that saves a common build failure.

```bash
make build
```

For a container instead, the compose file takes GIT_USER, GIT_EMAIL and FOLDER from the environment, mounts FOLDER at /gt, and puts Dolt data on a named volume rather than the bind mount. The comment above that volume says the reason is to avoid journal corruption from VirtioFS fsync semantics on macOS. The container runs sleep infinity, so you exec into it rather than attaching to a live process.

```bash
GIT_USER="Your Name" GIT_EMAIL="you@example.com" FOLDER="/Users/you/code" docker compose up -d
docker compose exec gastown zsh
```

Once a rig exists and work is in the ledger, a convoy is the unit that bundles beads for assignment. The README says convoys labeled mountain get autonomous stall detection and smart skip logic for epic-scale execution, which is the feature to reach for when a large piece of work needs to survive individual agent failures.

```bash
gt sling gt-abc12
gt convoy
```

## The watchdog tiers and the Refinery merge queue

Three components watch the fleet. The Witness is a per-rig lifecycle manager that monitors polecats, detects stuck agents, triggers recovery and handles session cleanup. The Deacon is a background supervisor running continuous patrol cycles across all rigs. Dogs are infrastructure workers the Deacon dispatches for maintenance, with Boot named as the triage worker. Read together, this is a supervisor hierarchy with escalating scope: one rig, then all rigs, then one-off tasks.

The Refinery is the part with the most conventional engineering behind it. When a polecat finishes via gt done, the Refinery batches merge requests, runs verification gates, and merges to main using what the README calls a Bors-style bisecting queue. Failed merge requests are isolated and either fixed inline or re-dispatched. If you have used Bors or a similar bisecting merge queue, the behaviour will be familiar, and the re-dispatch path is the interesting one because it feeds failures back to agents rather than parking them for a human.

Escalation closes the loop. An agent that hits a blocker calls gt escalate, which creates tracked beads routed through the Deacon, the Mayor and, if needed, an Overseer. Severity levels are CRITICAL (P0), HIGH (P1) and MEDIUM (P2). The routing order is the design statement here: most problems are expected to resolve below the human, and only the residue reaches the Overseer.

## Scheduler limits, Seance, and what the README leaves open

The Scheduler is a capacity governor for polecat dispatch, and the README is blunt about why it exists: to prevent API rate limit exhaustion by batching dispatch under configurable concurrency limits. The default is direct dispatch, and deferred dispatch through the daemon turns on when you set scheduler.max_polecats. That default is a deliberate trade-off. Out of the box you get the simplest behaviour and no protection against hammering a provider, so anyone running a large fleet has to opt in to the governor.

Seance handles a different kind of continuity. It discovers previous agent sessions through .events.jsonl logs so an agent can query its predecessors for context and decisions. The README gives two forms, a listing and a one-shot question against a session id.

```bash
gt seance
gt seance --talk <id> -p "What did you find?"
```

Two things are conspicuously thin. The README does not document rollback or recovery for a corrupted hook worktree, and it does not state what happens to in-flight polecat sessions when the Deacon itself stops. Both are the kind of gap you would want closed before trusting the system with unattended overnight work. Molecules are documented separately in docs/concepts/molecules.md, where the README distinguishes root-only wisps, whose steps materialize at runtime, from poured wisps, whose steps materialize as sub-wisps with checkpoint recovery. The existence of two modes suggests the lightweight one is the common case and the checkpointed one is for work you cannot afford to redo.

## Alternatives, and where Gas Town is the wrong tool

The nearest comparison inside the material is Beads itself. Gas Town depends on github.com/steveyegge/beads and requires bd 0.57.0+ on native installs. Beads is the git-backed issue tracker; Gas Town is the layer that adds a workspace, agent identities, tmux-backed roles, a merge queue and watchdogs on top of it. If your problem is only that task state lives in a chat session, adopting Beads alone gives you the ledger without the fleet machinery. Choosing Gas Town means accepting the whole stack, including tmux and the Dolt-backed storage that the compose file takes care to place on a real volume.

A plain tmux session with a shell script is the other honest alternative, and for two or three agents it is probably enough. What it will not give you is the Refinery's bisecting merge queue or the Witness's stuck-agent detection. Conversely, if your agents already commit to branches and a human reviews every pull request, the Refinery is overhead rather than help.

Gas Town is the wrong tool when the work is not parallel. A single repository, a single agent and a single task gain nothing from rigs, convoys or severity routing, and the install cost is real: Go 1.26.2, ICU headers, tmux 3.0+, sqlite3 and a separate bd binary. It is also a poor fit where you cannot run tmux, since the README ties gt up and the Mayor, Witness, Refinery and polecat roles to it, leaving only minimal-mode workflows with manually started runtime instances.

## Licence, upgrade cost and the maintenance picture

Gas Town is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication visible here, and it is not legal advice. One practical consequence of MIT plus a Go module path of github.com/steveyegge/gastown is that forking is straightforward, but a fork inherits the dependency on github.com/steveyegge/beads, so a fork that diverges from upstream Beads will need to track two projects rather than one.

Upgrades are tag-based. The most recent release listed is v1.2.1 from 2026-06-06, following v1.2.0 on 2026-05-30 and v1.1.0 on 2026-05-07. The last push to the repository was on 2026-09-18, three days before the date used here, so the codebase is moving well ahead of the last tagged release. That gap is the upgrade cost in concrete terms: installing a release tag means installing something older than main, and the changelog is where you would look for what landed in between. The Makefile stamps version, commit and build time into the binary through ldflags, so gt built from a checkout will report the describe output rather than a release number, which makes it easy to tell a source build from a tagged one when you are debugging.

The repository carries a RELEASING.md, a CHANGELOG.md and a renovate.json, and the toolchain requirements are pinned tightly in go.mod at go 1.26.2. Pinning the Go version that precisely means an upgrade can require a toolchain bump before it will build at all.

## Conclusion

Adopt Gas Town if you already run several AI coding agents in tmux and lose work when their sessions restart; the git worktree hooks and the Beads ledger address exactly that. Do not adopt it for a single agent on one repository, because the Mayor, rigs, Refinery and watchdog tiers only pay for themselves at fleet scale. Before committing, verify that tmux 3.0+, Beads 0.57.0+ and Go 1.26.2+ are present on the host, and read docs/design/scheduler.md to understand the scheduler.max_polecats setting that governs dispatch.

## FAQ

### What is Gas Town for AI agents?

Gas Town is a multi-agent workspace manager for Claude Code, GitHub Copilot, Codex, Gemini and other AI coding agents. It persists work state in git-backed hooks and a Beads ledger so agents keep context across restarts, and the README puts its comfortable scale at 20 to 30 agents.

### How do you use Gas Town?

You create a Town workspace such as ~/gt/, add rigs that wrap your git repositories, and start with the Mayor, which the README describes as a Claude Code instance with context about your workspace. Work items are tracked as beads with IDs like gt-abc12, and commands such as gt sling and gt convoy take those IDs.

### How do you set up Gas Town?

The README gives two paths: a native install requiring Git 2.20+, Go 1.26.2+, Beads 0.57.0+, sqlite3 and tmux 3.0+, or a Docker Compose setup where the image supplies Go, Dolt, bd, tmux and CLI utilities. Homebrew and Docker install bd for you; the source and native Go paths install it with go install.

## Sources

- [gastownhall/gastown on GitHub](https://github.com/gastownhall/gastown)
- [Issues](https://github.com/gastownhall/gastown/issues)
- [License: MIT](https://github.com/gastownhall/gastown/blob/main/LICENSE)
- [README](https://github.com/gastownhall/gastown/blob/main/README.md)
- [Releases](https://github.com/gastownhall/gastown/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gastownhall-gastown