gastownhall/gastown

Gas Town – Multi‑agent orchestration for AI coding assistants

What it is – Gas Town is a command‑line workspace manager that lets you run many AI coding agents (Claude Code, GitHub Copilot, Codex, Gemini, etc.) on a set of projects while keeping every piece of work persisted in a Git‑backed ledger. The system supplies a hierarchy of concepts (Mayor, Town, Rigs, Crew, Polecats, Hooks, Convoys, Beads, etc.) that together provide:

Persistent state – each agent’s output is stored in a hook (a Git work‑tree) so a crash or restart never loses progress.
Built‑in coordination – a central AI coordinator called the Mayor creates convoys (work‑tracking units) made of beads (issue‑like IDs). The Mayor hands beads to worker agents (Polecats) and tracks completion.
Scalable orchestration – the architecture is designed to handle dozens of agents across many projects (called Rigs), with watchdog processes (Witness, Deacon, Dogs) that detect stuck agents and restart them.
Merge‑queue automation – a per‑rig Refinery batches finished work, runs verification gates and merges to the main branch using a Bors‑style queue.
Federated work sharing – the optional Wasteland layer lets multiple Gas Town installations exchange work items via DoltHub, earning reputation stamps.

Core concepts (quick reference)

Term	Role
Mayor	Primary Claude Code instance that knows the whole workspace and creates convoys.
Town	Root workspace directory (e.g. `~/gt/`).
Rig	A project container that wraps a Git repository and its agents.
Crew	Your personal clone inside a rig where you edit code.
Polecat	A worker AI agent with a persistent identity but short‑lived session.
Hook	Git work‑tree used as durable storage for an agent’s output.
Bead / Issue	Structured work item stored in the Beads ledger (`gt‑abc12`).
Convoy	A collection of beads that the Mayor dispatches together.
Molecule	A TOML‑defined workflow template that expands into a series of beads.
Witness / Deacon / Dogs	Watchdog processes that monitor health, run periodic maintenance, and handle escalations.
Refinery	Merge‑queue processor that batches and verifies completed work.
Scheduler	Configurable concurrency governor that prevents API‑rate‑limit exhaustion.
Seance	Session‑recovery tool that lets a new agent query logs of previous sessions.
Wasteland	Federation layer for sharing work across independent Gas Town installations.

Getting started (minimal steps)

# 1. Install prerequisites (Git 2.20+, Go 1.26+, Dolt, beads CLI, tmux)
# 2. Install the `gt` binary (Homebrew, `go install`, or Docker)
brew install gastown            # macOS shortcut (installs gt, bd, dolt)
# 3. Initialise a headquarters workspace
gt install ~/gt --shell --git
cd ~/gt && gt up               # start daemon, Deacon, Mayor, etc.
# 4. Add a project as a Rig
gt rig add myproj https://github.com/you/repo.git
# 5. Create a personal crew workspace
gt crew add alice --rig myproj
# 6. Attach to the Mayor and give it a goal
gt mayor attach
# (type your request, e.g. “Implement OAuth login for the API”)

The Mayor will automatically create a convoy, assign beads to available Polecats, and store all intermediate results in the Git‑backed hooks.

Typical workflow

Create a convoy – gt convoy create "Feature X" gt-abc12 gt-def34 (or let the Mayor create it automatically).
Dispatch work – gt sling gt-abc12 myproj sends bead gt‑abc12 to a Polecat running the configured runtime (Claude, Codex, etc.).
Agent works – the Polecat reads its mailbox, runs the AI tool, writes output to the hook, and calls gt done when finished.
Refinery merges – completed beads are batched, verified, and merged to the main branch.
Monitor – gt convoy list, gt agents, gt feed, or watch the TUI to see progress and any escalations.

Extending / customizing

Runtime configuration – per‑rig JSON (settings/config.json) lets you pick the provider (codex, gemini, copilot, etc.) and adjust command‑line arguments.
Formulas (Molecules) – reusable TOML recipes (e.g., a standard release process) are stored under internal/formula/formulas/. Use the bd CLI to list (bd formula list), execute (bd cook release --var version=1.2.0), or instantiate (bd mol pour release …).
Scheduler limits – set scheduler.max_polecats in the config to throttle how many agents are spawned concurrently.
Wasteland federation – gt wl join <remote> to connect to a shared DoltHub board, claim work, and submit evidence.

Who might use it?

Engineering teams that rely heavily on AI coding assistants and need a reliable way to keep work from being lost when the AI session ends.
Research labs experimenting with multi‑agent pipelines (e.g., one agent writes code, another reviews, a third runs tests) and want a Git‑native audit trail.
Solo developers who want to orchestrate several AI tools (Claude for design, Copilot for boilerplate, Gemini for tests) without manually copying snippets.

Where to find more

Documentation – docs/ folder contains detailed design notes (escalation.md, scheduler.md, WASTELAND.md, etc.) and a full glossary.
Source code – the repository is written in Go, uses the Beads issue‑tracking library, and ships a Docker Compose setup for sandboxed use.
Community – the project is maintained by steveyegge; issues and pull requests are the primary way to contribute.

Bottom line: Gas Town is a real, open‑source orchestration layer that turns a collection of AI coding agents into a coordinated, persistent, Git‑backed workflow engine, making large‑scale AI‑assisted development more reliable and auditable.