Gas Town is a terminal-first orchestrator for running lots of coding-agent sessions in parallel (e.g., Claude Code and similar tools) without losing track of who is doing what. It does this by treating all work and agent state as entries in a Git-backed issue system called Beads, then assigning those work-items to persistent “agent identities” that can be resumed across many short-lived CLI sessions. A small set of supervisory agents continuously patrol, nudge, and merge work so that swarms of ephemeral workers can generate changes (merge requests) while a dedicated merge agent serializes integration into main. The user (human) acts like a product manager: create/route work, watch dashboards, and occasionally intervene when agents get stuck.
- Beads → A lightweight, Git-versioned issue tracker / state store (issues stored as JSON lines committed to Git).
- Town → The orchestrator “control plane” (global config + processes managing all projects).
- Rig → A managed project/repo (“workspace” / execution target).
- Agent → A persistent identity stored in Beads (not a single chat/session).
- Session → An ephemeral CLI instance of a coding agent (cattle, not pets).
- Hook → A per-agent persistent “work queue pointer” (a Bead) saying what workflow the agent must run next.
- Molecule → A workflow: a graph/chain of Beads representing ordered steps with acceptance criteria.
- Protomolecule / Formula → Workflow templates / workflow source code used to generate molecules.
- Wisp → Ephemeral orchestration work-items (not persisted to Git) used for high-churn internal patrol runs.
- Convoy → A tracked delivery unit / work order that groups related work so humans can follow progress.
- GUPP (“If there’s work on your hook, you must run it”) → The “always continue work when assigned” execution rule.
- Nudge → A pragmatic “kick” to make a CLI agent start processing its hook (since some wait for user input).
Gas Town’s central idea is: don’t store orchestration state in RAM, a database, or a proprietary server—store it in Git via Beads. Beads aren’t just “tickets”; they also represent:
- work items (bugs/features/tasks),
- agent identities (who/what an agent is),
- mail/messages between agents,
- workflow steps (molecules),
- and control artifacts like hooks and role definitions.
This means the system can survive crashes and context resets because the “truth” is in versioned state.
Gas Town draws a hard line:
- Agent identity = durable (stored as Beads, has inbox/hook/history)
- Agent session = disposable (a particular Claude Code run)
So a “Mayor” can die and be restarted, and the Mayor agent identity continues with its hook/workflow. This is how Gas Town scales to many parallel agents without relying on one uninterrupted chat context.
- Rig-level (project): features/bugs/changes inside a specific repo (Rigs).
- Town-level (orchestration): patrol loops, releases, dashboards, plugins, and cross-project coordination.
Both are represented in Beads, but separated conceptually so you can see “real work” vs “system work”.
Gas Town defines a small, opinionated set of roles. In conventional terms it looks like:
- Mayor: primary “manager agent” you talk to. Routes work, kicks off swarms, receives completion notifications.
- Deacon: daemon-style supervisor that runs on a timer and ensures the whole system keeps moving (propagates “do your job” signals).
- Dogs (+ Boot the Dog): helper agents for the Deacon to offload maintenance and long-running chores; Boot monitors the Deacon itself.
- Polecats: ephemeral worker agents spawned on demand (often in swarms). Their main output is merge requests.
- Witness: monitor / shepherd agent that checks polecats and the merge process, helps unstick things.
- Refinery: merge-queue agent. Serializes integration to
mainand resolves conflicts/rebases, escalating if needed. - Crew: long-lived, named per-project agents the human uses directly for interactive work (design/back-and-forth). Not “swarm cattle”; more like your standing team.
- Overseer: you. You create/shape work, monitor progress, and occasionally do “hands-on-the-wheel” operations.
Gas Town doesn’t just create tickets; it tries to turn knowledge work into explicit step-by-step workflows so an agent can reliably grind through it.
- Beads: atomic tasks/issues.
- Epics: hierarchical grouping of tasks (trees + optional dependencies).
- Molecules: explicit workflows (graphs/chains of Beads), meant to be executed step-by-step.
- Protomolecules: workflow templates made of pre-authored Beads.
- Formulas (TOML): higher-level DSL/source format that “compiles” into protomolecules/molecules (supports composition like loops/gates).
- Wisps: non-persisted, ephemeral workflow runs used internally so the Git history doesn’t fill with orchestration noise.
If you ignore the vocabulary: it’s basically “workflow definitions + workflow instances,” with durable checkpoints at each step.
Every agent has a hook (persistent pointer to the next workflow/molecule). The policy is:
If there is work on your hook, you must run it.
So instead of relying on an agent remembering what to do inside a chat context, the agent repeatedly:
- checks its hook,
- finds the current workflow step,
- executes it,
- marks it done in Beads,
- advances to the next step.
Because CLI agents sometimes idle waiting for user input, Gas Town uses a nudge mechanism (tmux-based messaging) to kick them into reading their hook/inbox and continuing automatically.
Gas Town’s durability claim (as described in the post) is:
- the path can be nondeterministic (agents may take different routes, crash, restart),
- but the workflow is durable (steps are recorded and can be resumed),
- and completion is “eventual” as long as you keep running sessions.
This is basically: checkpointed workflows + retries across restarts, powered by Git-backed state rather than Temporal-style deterministic replay.
A common end-to-end loop looks like this:
-
You tell the Mayor: “Implement feature X” (or fix bug Y).
-
The Mayor files Beads for the work and wraps it in a Convoy (so there’s a human-trackable delivery unit).
-
The Mayor slings work to workers:
- small/interactive → Crew
- parallelizable coding tasks → Polecat swarm
-
Polecats produce merge requests (MRs) and hand them to a merge queue.
-
The Refinery processes the queue one at a time, resolving conflicts and landing changes to
main. -
The Witness patrol watches Polecats + Refinery, nudges stuck tasks, and keeps things moving.
-
The Deacon patrol runs periodically to ensure the whole system keeps running (and delegates chores to Dogs).
-
When the Convoy’s tracked items are done, you get a completion notification and can inspect the activity feed/dashboard.
If you only remember a few differentiators:
- Git as the durable control plane: not just tickets, but agent identities, mail, workflow state, and history.
- Persistent agent identities with disposable sessions: agents can restart endlessly without losing the plan.
- Workflow-as-issues (“molecules”): explicit, stepwise execution rather than “just chat until done.”
- Opinionated multi-agent roles: manager/scheduler (Mayor), patrol daemon (Deacon), monitor (Witness), merge engineer (Refinery), swarm workers (Polecats), plus user-facing Crew.
- Merge queue is first-class: once you swarm, merging becomes the bottleneck; Gas Town elevates that into a dedicated agent role.
- Terminal/tmux-centric operations: designed for managing many concurrent sessions quickly.