Gas Town

1 · What Gas Town Is

Gas Town is a workspace manager and multi-agent orchestration system: it coordinates multiple AI coding agents — Claude Code, GitHub Copilot, Codex, Gemini, and others — working on different tasks from one workspace. [README]

Its creator, Steve Yegge, frames it as “a new take on the IDE for 2026” — infrastructure for running fleets of Claude Code (and other) instances instead of babysitting them one at a time. He had predicted back in March 2025 that someone would “lash the Claude Code camels together into chariots”; when nobody built it, he built Gas Town himself to solve the “tedium of running lots of Claude Code instances.” [Welcome to Gas Town]

The project's current, more sober positioning (gastownhall.ai) calls it “an orchestration layer that treats AI agent work as structured data,” built to answer accountability questions (“Who did what? Which agent introduced this bug?”) and quality-tracking questions (“Which agents are reliable? Which need tuning?”) as agents become central to engineering work — every action attributed, every agent with a track record, all work carrying provenance. [docs.gastownhall.ai] The landing page's own tagline is blunter: “Scale without limits,” and it “Works with Claude Code, Codex, Gemini and more!” [gastownhall.ai]

The README pitches the same idea as four problem/solution pairs: agents losing 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 the Beads ledger. [README]

From babysitting one agent to running a fleet

Yegge frames Gas Town as the last rung of an eight-stage ladder he calls the “8 Stages of Dev Evolution”: stages 1–5 are a single agent with increasing autonomy; stage 6 is hand-running 3–5 parallel Claude Code instances; stage 7 is hand-managing 10+ agents — the practical limit for manual babysitting; stage 8 is building an orchestration system like Gas Town. He characterizes the whole arc as moving from “babysitting” individual agents, to supervising them, to managing fleets at scale — the framing this guide uses throughout. [Welcome to Gas Town]

Scale, and the Kubernetes comparison

Yegge says he personally runs “12 to 30 workers” depending on intensity, and claims Gas Town can run “20–30 at once, productively, on a sustained basis” — deliberately kept under 30 pending remote hyperscaler integration. As a scale demonstration he cites a “million-step wisp” run that solved the 20-disc Hanoi-towers MAKER problem “trivially.” At publication Gas Town was 17 days old — “75,000 lines of Go code across 2,000 commits” — with acknowledged high cost and operational overhead to run. [Welcome to Gas Town]

Yegge draws the Kubernetes comparison directly: “Both systems coordinate unreliable workers toward a goal. Both have a control plane (Mayor/Deacon vs kube-scheduler/controller-manager) watching over execution nodes (Rigs vs Nodes).” The stated difference is the goal itself: “Kubernetes asks, ‘Is it running?’ while Gas Town asks ‘Is it done?’” — Kubernetes maintains continuous desired state; Gas Town optimizes for completion — “finish this work, land the convoy, then nuke the worker and move on.” He candidly compares the system's overall complexity to “Kubernetes, or Temporal,” saying it grew by “adding components until it was a self-sustaining machine,” ending up with parts “that look a lot like Kubernetes mated with Temporal.” [Welcome to Gas Town]

The current README's scale language is more conservative in framing but higher in ceiling: “4-10 agents become chaotic” manually, Gas Town lets a team “Scale comfortably to 20-30 agents,” and its gt feed --problems view exists specifically because “At scale (20-50+ agents), spotting stuck agents in the activity stream becomes difficult.” A three-tier watchdog chain (Daemon → Boot → Deacon → Witnesses/Refineries) exists to keep agents healthy at that scale — echoing the control-plane-watching-nodes framing above. [README]

Sources: README · Welcome to Gas Town · docs.gastownhall.ai · gastownhall.ai

2 · The Mental Model

Five words carry almost all of Gas Town's vocabulary. Learn these and the rest of this guide is just detail.

Sources: Gas Town, Decoded · README · Welcome to Gas Town

Stage 03 · Town Up

Before there is a single rig or a single bead, there is the town's own infrastructure: a background daemon, a Dolt-backed datastore, and two singleton agents (the Mayor and the Deacon). Stage 0 is bringing that infrastructure up — and learning to read its status honestly, including the one time it lied to us.

Native prerequisites: Git 2.20+ (worktree support), Go 1.26.2+ (Linux/Windows and macOS source builds only), Beads bd 0.57.0+, Dolt, sqlite3 (convoy DB queries), ICU4C dev headers (source builds), tmux 3.0+ (required for gt up and the tmux-backed roles), and the Claude Code CLI as the default runtime. [README] On macOS, brew install gastown installs gt, bd, and dolt together — avoid go install there, since Gatekeeper kills the unsigned binary; Linux/Windows use go install plus a separate Dolt install. [README]

brew uninstall gastown
brew install gastownhall/gastown/gastown
gt version

gt install ~/gt --shell --git creates the headquarters (HQ) directory at ~/gt: --shell installs shell integration and turns Gas Town on globally, --git initializes HQ as its own git repo (set git config --global user.name/email first, so the initial commit has a valid identity). The quick-start one-liner strings the whole first run together: gt install ~/gt --shell --git && cd ~/gt && gt up && gt doctor --fix && gt config agent list && gt mayor attach — "and tell the Mayor what you want to build!" [README]

gt up boots all of it in one idempotent command — Dolt, the daemon, the Deacon, the Mayor, and (once rigs exist) per-rig Witnesses and Refineries. Verify afterward with gt doctor --fix, which clears warnings gt install doesn't preempt. Teardown is layered too: gt shutdown && gt up fixes env-var mismatches in a running session. The docs describe an emergency kill switch, gt stop --all / gt stop --rig <name> — but ground truth found this doesn't exist on v0.12.0 (Error: unknown command "stop" for "gt"). The real commands are gt down (infra only, reversible) or gt down --all (full shutdown, orphan cleanup) town-wide, and gt rig stop <name> per rig. [reference.md] [ground truth: local gt v0.12.0-197-gf28273a1]

gt status, line by line

Ground truth, before any service is started:

Services: daemon (stopped)  dolt (stopped, :3307)  tmux (-L default, PID 62915, 2 sessions, /tmp/tmux-501/default)
🎩 mayor ○ [zclaude/GLM-5]
🐺 deacon ○ [zclaude/GLM-5]
No rigs registered. Use 'gt rig add' to add one.

• daemon (stopped) / dolt (stopped, :3307) — neither service is running yet; :3307 is the port Dolt will bind to once it starts.
• tmux (-L default, PID 62915, 2 sessions, …) — the shared tmux server backing every role's session. These 2 sessions pre-date Gas Town entirely; nothing here ever touches them.
• 🎩 mayor ○ [zclaude/GLM-5] / 🐺 deacon ○ [zclaude/GLM-5] — the two singleton roles already show their resolved agent (here, the custom zclaude alias running model GLM-5) even while stopped; ○ means idle/no active turn, not "misconfigured."
• No rigs registered. — that's Stage 1, next.

[ground truth: local gt v0.12.0-197-gf28273a1]

Ground truth, after gt up:

Services: daemon (PID 10405)  dolt (PID 10948, :3307, ~/gt/.dolt-data)  tmux (-L default, PID 62915, 5 sessions, /tmp/tmux-501/default)
🎩 mayor  ○ [zclaude/GLM-5]
🐺 deacon  ○ [zclaude/GLM-5]
No rigs registered.

• daemon (PID 10405) — the watchdog process is alive.
• dolt (PID 10948, :3307, ~/gt/.dolt-data) — the Dolt SQL server is up, listening on 3307, storing its data under ~/gt/.dolt-data.
• tmux (…, 5 sessions, …) — grew by exactly 3: hq-boot, hq-deacon, hq-mayor, each its own tmux session named after its agent bead. The 2 pre-existing sessions are still there, untouched.
• 🎩 mayor ○ / 🐺 deacon ○ — still ○, and that's the trap: ground truth confirms this glyph tracks hook/heartbeat state, not raw tmux liveness — gt status -v printed hq-mayor stopped even while the hq-mayor tmux pane was demonstrably alive and running Claude Code. Don't read ○/"stopped" as "no tmux session"; check tmux ls directly if that distinction matters.
• No rigs registered. — unchanged; that's still Stage 1.

[ground truth: local gt v0.12.0-197-gf28273a1]

Sources: README · reference.md · glossary.md · Homebrew Core formula page · gastownhall/gastown issue #4179 · gastownhall/homebrew-gastown tap · ground truth (local gt v0.12.0-197-gf28273a1)

Stage 14 · First Rig, First Sling

A rig is Gas Town's word for a project. Stage 1 registers one, then puts a single unit of work on it — and, honestly, this is where our own dry run ran into this town's real, pre-existing Dolt schema defect for the first time.

gt rig add <name> <url> clones a repository into HQ as a rig (--prefix mp sets a custom beads prefix). Rig names accept letters, digits, and underscores only — no hyphens, dots, spaces, or path separators ("Use my_project instead of my-project"). Registration effects reach further than the clone itself: a rig config.json records type, name, git_url, default_branch (auto-detected from the remote — it becomes both the Refinery's merge target and the polecat base branch), and beads.prefix; and on every gt rig add, Claude settings hooks are auto-synced for all of the new rig's targets — crew, witness, refinery, polecats. [README · reference.md · HOOKS.md]

Crew and Polecats split the same rig two ways: Crew is persistent and human-managed — it pushes to main directly, and nothing patrols it — while Polecats are transient and Witness-managed, work on branches the Refinery merges, and are cleaned up automatically once done. [overview.md] gt sling <bead-id> <rig> assigns an existing bead to a polecat in that rig; add --agent codex to override the runtime for just this spawn, or --on gt-def <rig> to sling with a workflow (formula) template. The recommended order is convoy-first, then sling — but a bare sling auto-creates its own convoy, so "even a swarm of one gets convoy visibility." [reference.md]

When is a plain repo-as-rig the right call? Whenever there's a real, reachable git remote, gt rig add <name> <url> is the whole story. For a local, no-remote rig, the documented path is scripts/bootstrap-local-rig.sh (which wraps gt rig add <name> <git-url> --local-repo <path>) — not --adopt. --adopt is meant only for registering an already-assembled real rig whose directory shape Gas Town can trust as-is, and, as Lab 2 below found the hard way, it has sharp edges when there is no remote at all. [local-rig-bootstrap.md]

cd ~/gt && gt dolt cleanup --force
rm -rf ~/gt/gt_lab_scratch

Sources: README · reference.md · overview.md · HOOKS.md · local-rig-bootstrap.md · shell integration.go · ground truth (local gt v0.12.0-197-gf28273a1)

Stage 25 · Beads & Mail

Every unit of state in Gas Town — a task, a message, an agent's own identity — is a bead. Stage 2 is the CLI for working with them directly, plus the mail and escalation layers built on top of the same primitive.

Core bd verbs: bd ready (work with no blockers), bd list --status=open|in_progress, bd show <id>, bd create --title="..." --type=task, bd update <id> --status=in_progress, bd close <id>, and dependency edges via bd dep add <child> <parent> (the child depends on the parent). The documented state trio for an ordinary task bead is open → in_progress → closed. [reference.md]

A bead is bigger than "task," though. Ground truth's own bd list --include-infra --all at the town level returned a long tail beyond plain tasks: agent beads (hq-mayor, hq-deacon) and dozens of hq-wisp-* patrol/dog molecule beads — proof that "agent" and "wisp/molecule" are as real and listable a bead kind as "task." Mail is the same trick again: mail messages are type=message beads routed by gt mail. [mail-protocol.md] [ground truth: local gt v0.12.0-197-gf28273a1]

Routing runs on prefix: routes live in ~/gt/.beads/routes.jsonl — hq-* addresses route to ~/gt/.beads/ (Mayor mail, cross-rig coordination); <rig-prefix>-* routes to ~/gt/<rig>/mayor/rig/.beads/. Debug with BD_DEBUG_ROUTING=1 bd -C <owning-root> show <id>; note that bd --global is not the town database — it targets a separate shared-server beads_global. [reference.md]

Mail CLI: gt mail inbox, gt mail read <id>, gt mail ack <id>, gt mail send <addr> -s "Subject" -m "Body", or gt mail send --human -s "..." to reach the overseer directly. Addresses are <rig>/<role> or <rig>/<type>/<name> — e.g. greenplace/witness, greenplace/polecats/nux, mayor/, deacon/. Structured protocol messages carry their own types: POLECAT_DONE (polecat→witness), MERGE_READY (witness→refinery), MERGED / MERGE_FAILED / REWORK_REQUEST (refinery→witness), RECOVERED_BEAD / RECOVERY_NEEDED (witness→deacon), HELP (any→escalation target), and 🤝 HANDOFF (agent→self/successor). [mail-protocol.md]

Escalation shares the same infrastructure: gt escalate "topic" defaults to MEDIUM; -s CRITICAL|HIGH|MEDIUM picks a severity that routes per ~/gt/settings/escalation.json. Ground truth's own file matches the documented structure exactly:

critical → [bead, mail:mayor, email:human, sms:human]
high     → [bead, mail:mayor, email:human]
medium   → [bead, mail:mayor]
low      → [bead]
stale_threshold: 4h, max_reescalations: 2
contacts: {}

That last line is a real, honest detail: contacts: {} is empty on this install, so the email:human/sms:human routes exist structurally but have nobody configured to actually receive them yet. Round it out with gt escalate ack <bead-id>, gt escalate list [--stale|--unacked], gt escalate stale (bumps severity MEDIUM→HIGH→CRITICAL after the stale threshold, max 2 re-escalations), and gt escalate close <bead-id> --reason=.... [escalation.md] [ground truth: local gt v0.12.0-197-gf28273a1]

Sources: reference.md · mail-protocol.md · escalation.md · ground truth (local gt v0.12.0-197-gf28273a1)

Stage 36 · Convoys

A convoy is Gas Town's tracked batch of work: a persistent bead that bundles issues from any rig so their progress can be watched as one unit. Stage 3 is creating one, growing it, and — the honest part — finding out that this session's real Dolt schema defect blocked watching one actually serialize.

A convoy is a persistent tracking unit for batched work, stored as a town-level bead with ID prefix hq-cv-*; it can track issues from any rig via a tracks relation that is non-blocking, additive, and cross-rig. [convoy.md] Create one with gt convoy create "Feature X" gt-abc gt-def --notify overseer — single-issue convoys are normal too ("still creates convoy for dashboard visibility"); repeat --notify for multiple subscribers, e.g. --notify mayor/ --notify --human. [convoy.md]

Grow an existing convoy with gt convoy add hq-cv-abc gt-issue1 gt-issue2 ..., or build one straight from planning output with gt convoy create --from-epic gt-epic-abc, which BFS-walks the epic's parent-child hierarchy and tracks only slingable leaf types (task, bug, feature, chore — sub-epics and decisions are recursed into but not themselves tracked). A bare gt sling bd-xyz beads/amber with no existing convoy auto-creates one ("Work: bd-xyz") and tracks the issue — "Even a swarm of one gets convoy visibility." [convoy.md]

Convoy and swarm name different things: the convoy persists (hq-cv-*); the "swarm" is ephemeral — just whichever workers currently happen to be on the convoy's issues. A "stranded convoy" has ready work but no polecats assigned, and needs attention. Lifecycle runs open → (all tracked issues close) → closed/landed, with a "Convoy Landed" notification listing the issues and duration; adding an issue to a closed convoy auto-reopens it. [convoy.md]

Dependency edges are not a convoy-level concept — a convoy tracks a batch, it does not itself encode ordering. Ground truth's own gt convoy create --help confirms the real create syntax (gt convoy create <name> [issues...] [flags]) and confirms ordering between two tasks is expressed at the bead level instead: bd dep add <blocked-id> <blocker-id> (shorthand: bd dep <blocker-id> --blocks <blocked-id>). Two independent tasks in the same convoy run in parallel; a dependency edge between them forces serialization — the blocked bead simply never becomes ready until its blocker closes. [ground truth: local gt v0.12.0-197-gf28273a1]

View split: gt convoy status [convoy-id] is the cross-rig "status of this batch" view; gt rig status <rig> is "what's everyone in this rig working on." Dashboard commands: gt convoy list (active only), --all (include landed), --status=closed, --json. [convoy.md]

Better Stack's framing of the same machinery, in plainer language: the Mayor decomposes a request into beads and "groups [them] into Convoys for execution," which "allows Gas Town to track dependencies and manage the flow of work" — the convoy is the batch-visibility layer Stage 4's delegation flow (next) hangs its work on. [Better Stack guide]

Sources: convoy.md · README · Better Stack guide · ground truth (local gt v0.12.0-197-gf28273a1)

Stage 47 · Delegation

Stage 4 is the actual payoff of everything Stages 0–3 set up: stop typing individual commands and hand the Mayor a goal instead. Attach once, state what you want, and let decomposition, convoys, and the patrol loops keep work moving without you polling. Ground truth could only partly confirm the decomposition step this session — the honest version of that is below.

Entry point: gt mayor attach, then one comprehensive prompt covering everything — database, APIs, frontend, testing, deployment. "The more detail you provide upfront, the better the Mayor's plan will be." The documented flow: user goal → Mayor decomposes → beads grouped into convoys → polecats execute in parallel on isolated git branches — this is "stop babysitting," made concrete. [Better Stack guide]

GUPP is the engine underneath delegation staying unattended: the "Gas Town Universal Propulsion Principle" — "If there is work on your Hook, YOU MUST RUN IT." A delegated agent's startup contract is mechanical: (1) gt hook — work hooked → execute immediately; (2) hook empty → check mail for attached work; (3) nothing anywhere → escalate to the Witness. Orientation commands: gt hook, gt prime (inline formula checklist), bd show <issue-id>. [glossary.md] [propulsion-principle.md]

Completion path: a polecat runs gt done → branch pushed, MR bead created → the Refinery batches pending MRs, runs verification gates on the merged stack, merges all if green, bisects to isolate the failure if red — "a Bors-style merge queue — polecats never push directly to main." Merge-queue CLI: gt mq list|next|submit|status|retry|reject, plus integration branches for epics (gt mq integration create <epic-id> ... status ... land). [README] [reference.md]

Session cycling keeps long-running delegation from silently stalling: an agent notices context filling → gt handoff (mails itself) → the manager kills and restarts the session → the new session reads the handoff mail. gt handoff --shutdown terminates outright (polecats). Related: gt session stop <rig>/<agent>, gt peek <agent>, gt nudge <agent> "msg"; session archaeology via gt seance (lists discoverable predecessor sessions, --talk <id> for a full-context conversation). [reference.md]

The standing form of delegation is the patrol loop: Deacon, Witness, and Refinery each cycle gt patrol new (root-only patrol wisp) → gt prime (inline checklist) → work steps → gt patrol report --summary "...", which atomically closes the current cycle and starts the next — this is what keeps work moving between your check-ins without anyone babysitting it. Dispatch is throttle-able: default scheduler.max_polecats = -1 dispatches immediately on sling; gt config set scheduler.max_polecats 5 switches to daemon-managed deferred dispatch (gt scheduler status|pause|resume). [reference.md] [README]

Sources: Better Stack guide · glossary.md · propulsion-principle.md · README · reference.md · ground truth (local gt v0.12.0-197-gf28273a1)

8 · Mixing Models: Tiers, Runners, Aliases

Gas Town never assumes one model. Three separate mechanisms decide which runtime/model actually executes a given role or sling, and this session's own ps aux capture settled, with live process evidence rather than a docs guess, which one wins when they disagree.

Mechanism 1 — cost tiers. gt config cost-tier is a town-wide dial with named levels; ground truth exercised two of them directly. Baseline standard: all six roles (mayor, deacon, witness, refinery, polecat, crew) at (default/opus) — "All roles use Opus (highest quality)." Switching to economy produced a real, specific role-assignment table: mayor: claude-sonnet, deacon: claude-haiku, witness: claude-sonnet, refinery: claude-sonnet, polecat: (default/opus), crew: (default/opus) — "Patrol roles use Sonnet/Haiku, workers use Opus." Only standard and economy were exercised this session; whether a further, cheaper tier name exists beyond these two was not enumerated here, so this guide isn't going to invent one. [ground truth: local gt v0.12.0-197-gf28273a1]

Mechanism 2 — per-invocation overrides. Below the tier dial, any single sling or role-start can override the runtime for just that instance: gt sling <bead> <rig> --agent codex (real flags confirmed via gt sling --help: --agent string, --account string); gt mayor start|attach|restart --agent <alias>; gt deacon start|attach|restart --agent <alias>; gt start crew <name> --agent <alias> / gt crew at <name> --agent <alias>. At rig-bootstrap time, per-role mixing can be pinned permanently: bootstrap-local-rig.sh --polecat-agent claude --witness-agent codex --refinery-agent codex — Claude polecats supervised by a Codex witness/refinery is a documented, supported configuration. [reference.md] [local-rig-bootstrap.md]

Mechanism 3 — custom aliases. gt config agent set <alias> "<command>" defines a named runner; gt config default-agent <alias> makes it the town default; gt config agent list [--json] / get / remove round out the CRUD (built-ins are protected from removal). Ground truth's own town has exactly this configured for real, not as a docs example: a custom agent named zclaude, defined as zclaude --dangerously-skip-permissions --model GLM-5, set as default_agent in settings/config.json. gt config agent list lists it alongside the 10 real built-in presets it confirmed — amp, auggie, claude, codex, copilot, cursor, gemini, omp, opencode, pi — and prints Default: zclaude. [reference.md] [ground truth: local gt v0.12.0-197-gf28273a1]

Resolution order, as documented: rig-level (<rig>/settings/config.json's "agent" plus a per-rig "agents" map) → town-level (settings/agents.json, settings/config.json) → built-in presets. [reference.md]

claude --dangerously-skip-permissions --model GLM-5 [GAS TOWN] boot <- daemon • triage
claude --dangerously-skip-permissions --model GLM-5 [GAS TOWN] deacon <- daemon • patrol
claude --dangerously-skip-permissions --model GLM-5 [GAS TOWN] mayor <- human • cold-start

Runtime plumbing differs per agent underneath all three mechanisms: Claude and Gemini get lifecycle hooks via a managed .claude/settings.json (passed with --settings); OpenCode gets a JS plugin; Copilot gets executable JSON hooks in .github/hooks/gastown.json (a 5-second ready delay instead of prompt detection); Codex and others fall back to a startup-nudge. OpenCode's autonomous mode separately needs export OPENCODE_PERMISSION='{"*":"allow"}'. [HOOKS.md]

Pattern guidance, from the same notes: put cheap models where mistakes are cheap and iteration is frequent — patrol/coordination roles under economy (mayor/deacon/witness/refinery on Sonnet/Haiku) — and reserve the model actually writing and merging code (polecat/crew) for the strongest tier. Plugin molecules independently carry "tier:haiku" labels so routine maintenance scans run cheap by default. [reference.md] Where two agents review each other's work (e.g. a Codex witness supervising Claude polecats, Mechanism 2 above) — a documented, supported configuration, not just a hypothetical [local-rig-bootstrap.md] — this guide's own suggestion, not a claim either source makes, is that using a genuinely different model, not just a cheaper one, may help: a reviewer sharing the same training data and failure modes as the work it's reviewing could plausibly catch less than one that doesn't.

Sources: reference.md · local-rig-bootstrap.md · HOOKS.md · model-aware-molecules.md · ground truth (local gt v0.12.0-197-gf28273a1)

9 · Watching the Town & Troubleshooting

At 20–30 agents, "spotting stuck agents in the activity stream becomes difficult" by design — so Gas Town gives you tmux sessions to peek into, structured logs to tail, and a status line to read. This is also the one Lab in Part II where ground truth got a genuinely full observability capture, not a partial one — because watching the town worked even while the town's own schema defect was actively breaking things underneath it.

Where to look

Other daemon-directory files worth knowing, all confirmed via ls ~/gt/logs ~/gt/daemon: daemon/daemon.pid / daemon/dolt-state.json (small JSON/PID files tracking the daemon's and Dolt's own running state); daemon/state.json (daemon heartbeat counter/last-heartbeat timestamp); daemon/restart_state.json (crash-loop/backoff bookkeeping). [ground truth: local gt v0.12.0-197-gf28273a1]

Stuck-agent taxonomy, straight from gt feed --problems: GUPP Violation (hooked work, no progress for an extended period), Stalled, Zombie (dead tmux session), Working, Idle — with intervention keys n = nudge, h = handoff, right in the feed. Health-check tooling rounds it out: gt deacon health-check <agent> (ping + track response), gt deacon health-state (all agents); the watchdog chain is Daemon (3-min heartbeat) → Boot (triage) → Deacon (patrol) → Witnesses/Refineries. "IMPORTANT: Always use gt nudge to send messages to Claude sessions. Never use raw tmux send-keys" — nudge uses literal mode, debounce, and a separate Enter for reliable delivery. [README] [reference.md]

Troubleshooting playbook

Dolt-outage discipline, one level up from any single symptom above: for a Dolt outage or a behavior mismatch involving Dolt-backed state, attach the RCA capture checklist from docs/dolt-health-guide.md to the escalation before restarting services — exactly the discipline this guide's own schema-defect writeups (Stages 1–3) followed. [escalation.md]

Sources: heartbeats.md · README · reference.md · escalation.md · Better Stack guide · Welcome to Gas Town · ground truth (local gt v0.12.0-197-gf28273a1)

10 · A Day in Gas Town

DoltHub's own engineer spent a real day running Gas Town on the Dolt repo itself — fixing failing Bats integration tests. It's the single richest narrative account in the source set of what actually happens when delegation goes right, then wrong, then gets sorted out. Walking through it beat by beat, tied back to the sections that teach each piece, is a good comprehension check for everything above — including the places where the post's telling and this guide's own v0.12.0 ground truth visibly disagree. [A Day in Gas Town]

Sources: A Day in Gas Town · ground truth (local gt v0.12.0-197-gf28273a1)

11 · The Seven Roles

Part II put you through six labs wearing the overseer's hat, watching roles act (and, honestly, fail to act) around you. This section names the seven job descriptions properly — repo docs split them into infrastructure roles that "manage the Gas Town system itself" (Mayor, Deacon, Witness, Refinery) and worker roles that "do actual project work" (Polecats, Crew, Dogs) — and for each one ties its responsibility, trigger, hand-offs, and failure mode back to the specific moment (or specific gap) you already saw in Part II. [overview.md]

Every one of these is a bead, not a person: each agent is backed by a lifecycle "agent bead" (hq-mayor, hq-deacon, <rig>-witness, <rig>-refinery, <rig>-polecat-<name>, <rig>-crew-<name>) that references a global role-template bead via its role_bead field — and identity/attribution (BD_ACTOR, e.g. mayor, <rig>/witness, <rig>/polecats/<name>) is set at spawn: "Agents execute. Humans own." [architecture.md · identity.md]

Sources: overview.md · glossary.md · Gas Town, Decoded · architecture.md · dolt-storage.md · dog-infrastructure.md · dog-execution-model.md · polecat-lifecycle.md · polecat-lifecycle-patrol.md · persistent-polecat-pool.md · polecat-self-managed-completion.md · identity.md · reference.md · escalation.md · ground truth (local gt v0.12.0-197-gf28273a1)

12 · Internals: Beads on Dolt, GUPP, Hooks, Patrols, Merge Queue

Part II showed you a town that mostly didn't work this session — a schema defect chased across four labs, a Deacon that wouldn't come back, a Refinery that never got the chance to run. This section is the machinery underneath all of it: not just what these pieces are for, but specifically why each one produced the exact behavior — good and bad — that you already watched happen.

Beads on Dolt

Dolt is the sole storage backend: one Dolt SQL server per town (MySQL protocol, port 3307, no password), data under ~/gt/.dolt-data/ with one subdirectory-database per scope. "There is no embedded mode and no SQLite. JSONL is used only for disaster-recovery backups." The daemon auto-starts the server, health-checks it every 30s, and restarts it on crash with exponential backoff. [dolt-storage.md]

Two-level architecture: town-level ~/gt/.beads/ (hq-*: Mayor mail, convoy coordination, town agent beads) vs. rig-level <rig>/mayor/rig/.beads/ (project issues, MRs, rig agent beads); routes.jsonl maps prefixes to the canonical clone, and worktrees (polecats, refinery, crew) carry only a .beads/redirect file so every agent in a rig shares one database. [architecture.md]

Schema version 6: everything is a row in issues — tasks, messages, agents, gates — with agent-specific columns (hook_bead, role_bead, agent_state), molecule columns (mol_type, wisp_type), a dependencies table (types: blocks, parent-child, thread), labels, comments, and an events table serving as the audit trail. Mail is just issue_type='message' — no separate mail table. [dolt-storage.md]

The versioned-audit payoff — the thing plain git+JSON never gave Beads — is real SQL history: dolt_history_* tables, AS OF time-travel queries, dolt_diff(), and DOLT_MERGE/dolt_conflicts for programmatic conflict resolution. "Dolt is git under the hood. The commit graph IS the storage cost, not the rows" — hence a six-stage data lifecycle (CREATE → LIVE → CLOSE → DECAY → COMPACT → FLATTEN) that Reaper and Compactor run daily, and wisps are dolt_ignored so patrol exhaust doesn't generate commits at all. [dolt-storage.md]

One more confirmation this session did surface cleanly: Lab 3's (§5) bd list --include-infra --all returned "dozens of hq-wisp-* patrol/dog molecule beads" alongside agent beads like hq-mayor — real, listable rows proving "agent" and "wisp/molecule" are as genuine a bead kind as "task," exactly as this schema describes. [ground truth: local gt v0.12.0-197-gf28273a1]

GUPP

The Gastown/Gas Town Universal Propulsion Principle, stated plainly on its own concepts page: "If you find something on your hook, YOU RUN IT" — with the steam-engine metaphor: "Gas Town is a steam engine. Agents are pistons… Steam engines don't run on politeness — they run on pistons firing. You are the piston." No supervisor polls "did you start yet?"; the hook is the assignment. [propulsion-principle.md]

The handoff contract: a spawned agent with hooked work must (1) find it on its hook, (2) understand it (bd show / gt hook), (3) BEGIN IMMEDIATELY. The failure mode GUPP exists to prevent: a polecat restarts with hooked work → announces itself → waits for confirmation → the Witness assumes progress → "Nothing happens → Gas Town stops." "Hooked" (triggers autonomous mode) is explicitly distinguished from "pinned" (a permanent reference bead). [propulsion-principle.md]

Enforcement is mechanical, not aspirational: the daemon's safety-net threshold for a GUPP violation is 30 minutes with hook_bead set but no progress, after which it mails GUPP_VIOLATION: <name> to the Witness — deliberately generous, because "distinguishing 'thinking deeply' from 'hung' requires intelligence." GUPP is one leg of a completion guarantee alongside a persistent sandbox and a Witness that respawns sessions; the glossary frames it as one of three Core Principles (with MEOW and NDI) — "the heartbeat of autonomous operation." [polecat-lifecycle-patrol.md · glossary.md]

Coverage note, for completeness: across every repo docs page fetched for Parts II–III, the acronym "GUPP" itself appears only in glossary.md, README.md, polecat-lifecycle-patrol.md, and polecat-self-managed-completion.md — the dedicated propulsion-principle.md and overview.md pages state the principle without ever using the acronym. [propulsion-principle.md · overview.md]

MEOW

One observation, offered as analysis rather than a tiebreaker: the deeper internals docs consistently express the glossary's "molecular" reading — decomposition machinery (formulas, molecules, wisps, epics) is everywhere in the design docs, while the README's "Mayor-Enhanced" expansion appears nowhere outside the README section that defines it. That is a pattern in where the term shows up, not a resolution of what it stands for. [glossary.md · molecules.md]

The molecule machinery the glossary's reading names: Formula (source TOML, "Ice-9") → bd cook → Protomolecule (frozen template) → either bd mol pour → Molecule (persistent, "Liquid") or bd mol wisp --root-only → Root Wisp (ephemeral, "Vapor"). Root-only wisps are the default — formula steps are read inline at gt prime time rather than materialized as rows, cutting wisp accumulation from ~6,000+ rows/day to ~400/day. [molecules.md]

That "Vapor" — Root Wisp — reading is exactly what Lab 3 (§5) saw firsthand, without either of us needing to pick a side in the acronym dispute: bd list --include-infra --all's "dozens of hq-wisp-* patrol/dog molecule beads" are the molecular decomposition machinery made concrete in real listed data, whichever expansion of MEOW you take to be describing it. [ground truth: local gt v0.12.0-197-gf28273a1]

Hooks

Terminology hazard: Gas Town has two unrelated "hooks." (1) The agent hook — glossary: "A special pinned Bead for each agent. The Hook is an agent's primary work queue — when work appears on your Hook, GUPP dictates you must run it"; at schema level, it is the hook_bead column discussed above. (2) Claude Code lifecycle hooks — the gt hooks subsystem managing settings.json files. [glossary.md · dolt-storage.md · HOOKS.md]

On sense (1): the durable bead pointer (hook_bead) survives session cycles while the worktree holds the work product — "No explicit 'handoff payload' is needed. The beads state IS the handoff." This is precisely the field gt status -v printed as empty (hook: (none)) in Lab 5 and Lab 6 (§7/§9) — the durable pointer this whole GUPP mechanism depends on. [polecat-lifecycle-patrol.md]

On sense (2): single source of truth in ~/.gt/hooks-base.json + ~/.gt/hooks-overrides/*.json, merge chain base → role → rig+role (most specific wins), generating per-role settings.json targets passed to Claude Code via --settings so customer repos stay clean. The default base config wires GUPP straight into the session lifecycle: SessionStart → gt prime --hook, PreCompact → gt prime --hook, UserPromptSubmit → gt mail check --inject, Stop → gt costs record — the propulsion check fires mechanically at every session boundary, not just at agent startup. [HOOKS.md]

This is the exact mechanism Stage 1 (§4) already named without unpacking it: "on every gt rig add, Claude settings hooks are auto-synced for all of the new rig's targets — crew, witness, refinery, polecats." The hook registry backing it (~/gt/hooks/registry.toml) catalogs 7 hooks, 5 enabled by default (pr-workflow-guard, session-prime, pre-compact-prime, mail-check, costs-record); gt doctor --fix — the same command that killed three tmux sessions as a side effect in Lab 2/Lab 6 — is also the command that repairs out-of-sync hook files. [HOOKS.md]

Patrol loops

Patrol: "Ephemeral loop maintaining system heartbeat." Four patrol agents run at distinct scopes: Daemon (town-wide, 3-minute heartbeat), Boot/Deacon (town-wide, per daemon tick), Witness (per-rig, continuous), Refinery (per-rig, on demand). Mechanically, every patrol role cycles gt patrol new (root-only patrol wisp) → gt prime (inline checklist) → work steps → gt patrol report --summary "...", which atomically closes the cycle and starts the next; patrol wisps are ephemeral, Dolt-ignored, and reaped by the data-lifecycle Dogs. [glossary.md · polecat-lifecycle-patrol.md]

The daemon's own tick order is fixed: ensureBootRunning() → checkDeaconHeartbeat() (belt-and-suspenders) → ensureWitnessesRunning() → ensureRefineriesRunning() → processLifecycleRequests() — agent running/stopped state is derived from tmux directly every tick, not read back out of beads. [dog-infrastructure.md]

Patrol overlap is intentional redundancy, not sloppy duplication: "The daemon detects dead sessions. The deacon detects dead witnesses. The witness detects dead polecats" — every layer converges on the same observables (beads, git, tmux liveness) with no private state, the "discover, don't track" principle. Safety-net thresholds are deliberately generous: GUPP violation 30 min hooked-no-progress, hung session 30 min no tmux output, stuck-in-done 60 seconds. [polecat-lifecycle-patrol.md]

Merge queue / refinery

The core design is batch-then-bisect, "Bors-style": batch pending MRs by rebasing them as a stack on main, run tests once on the tip — all green fast-forwards the whole stack; red triggers a binary bisect to isolate the offender. But architecture.md's own phase table lists Phase 1 (parallel gates) "In progress" and Phase 2 (batch-then-bisect) "Blocked by Phase 1" — while the README narrates batching+bisect as already-shipped, present-tense behavior. [architecture.md]

The shipped baseline, per the patrol design doc, is simpler and serialized: claim MR → acquire a merge slot (serialized push lock) → run gates → squash-merge to main → close the MR bead and source issue → send MERGED. MR discovery is poll-based, not push-based — the Refinery queries beads each patrol cycle for issues labeled gt:merge-request; MERGE_READY nudges only cut latency, so a missed nudge costs at most one patrol cycle. [polecat-lifecycle-patrol.md · polecat-self-managed-completion.md]

Integration branches extend the queue for epics: gt mq integration create <epic-id> creates an integration/<title> branch that the whole pipeline auto-targets; polecats spawn worktrees from it, and once all children close it lands as a single --no-ff merge. Landing guardrails are three-layered — soft formula instructions, a pre-push git hook blocking any push that makes an origin/integration/* tip reachable from the default branch, and only gt mq integration land itself setting the env var that clears that block: "a policy-based trust boundary, not a capability-based security mechanism." [integration-branches.md]

And this whole section is the mechanics behind the box Stage 4's own delegation diagram (§7) drew as "Refinery: merge queue, Bors-style" — a step this guide's own session never reached at all, because no bead was ever created for a polecat to work, so no MR bead ever existed for a Refinery to discover, batch, or bisect. [ground truth: local gt v0.12.0-197-gf28273a1]

Sources: dolt-storage.md · architecture.md · propulsion-principle.md · polecat-lifecycle-patrol.md · glossary.md · README · molecules.md · HOOKS.md · dog-infrastructure.md · polecat-self-managed-completion.md · integration-branches.md · overview.md · ground truth (local gt v0.12.0-197-gf28273a1)

13 · Gas Town ↔ Gas City

Gas City is Gas Town's successor SDK — gastownhall.ai frames it as recasting the town as “a composable SDK for building observable, multi-agent dark factories.” Every row below starts Gas-Town-first: the term you already learned somewhere in Parts I–III on the left, what actually happens to it on the Gas City side on the right — including, explicitly, the concepts that don't survive the move at all. [gastownhall.ai]

A 2026-07-11 re-check of gastownhall.ai found no renames or changelog since the original mapping was drawn: same lineage claim, same v1.0.0 version numbers for both projects (Gas Town released 2026-04-03; Gas City announced 2026-04-27), and no command or role names on the landing page at all — it's marketing copy, not documentation, so the mapping below still rests on each project's own docs, not on gastownhall.ai's phrasing. [gastownhall.ai]

The shift underneath every row: Gas Town ships as one opinionated application with seven fixed worker roles, hardcoded path-derived identity (~/gt/mayor/), and a purpose-built merge queue, escalation ladder, and federation layer baked into the gt binary itself. Gas City strips that down to nine composable primitives (City/Agent/Bead/Formula/Molecule/Rig/ Pack/Convoy/Order/Event) and reintroduces Gas Town's own roles as one importable “Gastown pack” rather than platform code — “the same SDK can express Gas Town, Ralph, or any other pack.” Its own docs are blunt about the porting trap: “Do not port code or prompts that assume directory path implies who the agent is” — identity moves from folder location to declared config. [coming-from-gastown]

Roles & primitives

Concepts with no direct primitive — kept explicit, not glossed over

When should a Gas Town user actually care about Gas City?

If you're running one opinionated town with the stock seven roles and don't need multiple concurrently-configured “packs,” Gas Town's out-of-the-box roles, merge queue, and escalation ladder still do more for you with less config than Gas City would — Gas City makes you author back several behaviors Gas Town ships free. If you need more than one flavor of orchestration on shared infrastructure, or a Kubernetes/ACP/herdr session backend instead of tmux-only, Gas City's pack/import/override model and pluggable runtime providers are the actual reason to migrate. If your install depends on Wasteland federation, mail groups/queues/channels, gt escalate, gt seance, or the Bors-style merge queue, treat those as blocking gaps, not renames, until a pack reimplementing them turns up. And if you're porting prompts or scripts written against ~/gt/<role>/ path assumptions, budget time to rewrite them against explicit agent.toml/dir config — Gas City's own docs call this out as the single most common porting mistake. [coming-from-gastown · escalation.md · WASTELAND.md]

Sources: gastownhall.ai · README · glossary.md · overview.md · architecture.md · dolt-storage.md · dog-infrastructure.md · escalation.md · mail-protocol.md · WASTELAND.md · scheduler.md · HOOKS.md · model-aware-molecules.md · convoy.md · coming-from-gastown · gastown-command-map

14 · Quiz, Glossary & Sources

Twenty questions, every answer traceable to a specific section above — including the honest, partial, and blocked outcomes this guide's own labs actually produced. Reveal each answer only after you've committed to one; the point is finding out what you don't know yet, not the count.

Quiz

Glossary

Every Gas Town term used in this guide, in one line each, with its closest Gas City equivalent (“—” where this guide's own migration research (§13) found none).

Sources

Primary: steveyegge/gastown README · reference.md · glossary.md · overview.md · HOOKS.md · convoy.md · propulsion-principle.md · heartbeats.md · mail-protocol.md · escalation.md · model-aware-molecules.md · local-rig-bootstrap.md · WASTELAND.md · internal/shell/integration.go · architecture.md · dolt-storage.md · dog-infrastructure.md · dog-execution-model.md · polecat-lifecycle.md · polecat-lifecycle-patrol.md · persistent-polecat-pool.md · polecat-self-managed-completion.md · identity.md · molecules.md · integration-branches.md · scheduler.md · gastownhall.ai · docs.gastownhall.ai · Gas City: coming-from-gastown · Gas City: gastown-command-map

Lineage: “Welcome to Gas Town” (Steve Yegge).

Community: “A Day in Gas Town” (DoltHub) · “Gas Town, Decoded” (Andrew Lilley Brinker) · Better Stack: “Building with Gas Town” · Shinzo: “How to use Gas Town” (direct fetch returned an empty JS shell; only search-snippet fragments used, low confidence, flagged inline where cited).

Local: gt v0.12.0-197-gf28273a1 ground truth, 2026-07-11.

All sources fetched 2026-07-11.