Annotated version of 'Welcome to Gas Town' Term -- The Town

Steve Yegge's AI adoption Chart

But it works! Gas Town solves paper - Solving a Million-Step LLM Task with Zero Errors (20-disc Hanoi towers) trivially with a million-step wisp you can generate from a formula. I ran the 10-disc one last night for fun in a few minutes, just to prove a thousand steps was no issue (MAKER paper says LLMs fail after a few hundred).

I mention performance benchmark -- Towers of Hanoi in examples of excellent state validations

Section 2 - Gas Town Was No Secret

It will have to have multiple levels of agents supervising other agents,” I said.

“It will have a Merge Queue,” I said.

“It will orchestrate workflows ,” I said.

“It will have plugins and quality gates,” I said.

Section 3 - WARNING DANGER CAUTION

graceful system degradation | Cross agent messaging

Gas Town is designed to scale up in three dimensions this year with (1) model cognition, (2) agents becoming more Gas Town-friendly, and(3) Gas Town and Beads making it into the training corpus for frontier models Even without all that, it’s already shocking that the agents use Beads and Gas Town so effortlessly. With zero training.

One thing to know up front about Gas Town: it degrades gracefully. Every worker can do their job independently, or in little groups, and at any time you can choose which parts of Gas Town you want running. It even works in no “no-tmux” mode, and limps along using naked Claude Code sessions without real-time messages. It’s a little slower, but it still works.

Gas Town’s propulsion (GUPP) is effective, but still a bit flaky right now, and sometimes you will need to go hustle the Polecatss to get their MR submitted, and then hustle the Refinery to deal with them. The Witness patrol helps smooth this out so it’s almost perfect for most runs.

Pushing along the worker agents and the specialized agent -- code merge

Section 4 - Gas Town 101

The Town: This is your HQ. Mine is ~/gt, and all my project rigs go beneath it: gastown, beads, wyvern, efrit, etc.. The town (Go binary gt) manages and orchestrates all the workers across all your rigs. You keep it in a separate repo, mostly for the configuration.

Work Level -- Town

^ Term -- Rigs

Rigs: Each project (git repo) you put under Gas Town management is called a Rig. Some roles (Witness, Polecats, Refinery, Crew) are per-rig, while others (Mayor, Deacon, Dogs) are town-level roles. gt rig add and related commands manage your rig within the Gas Town harness. Rigs are easy to add and remove.

Does Work Level -- Rig

^ Term -- The Overseer

The Overseer: That's you, Human. The eighth role. I gave you some eye paint in the picture. As the Overseer, you have an identity in the system, and your own Inbox, and you can send and receive Town Mail. You're the boss, the head honcho, the big cheese.

human talking to a management agent who delegates

^ Term -- The Mayor

The Mayor: This is the main agent you talk to most of the time. It's your concierge and chief-of-staff. But if the Mayor is busy, all the other workers are also Claude Code, so they are all very smart and helpful. The Mayor typically kicks off most of your work Convoys, and receives notifications when they finish.

From blog post - gas town from clown show to v 1 Steve says:

I realized I just wanted someone to talk to, while the system was working. And perhaps, as occasion might demand, someone to yell at.

The Mayor abstraction turned out to be perfect. Mayors are there to get yelled at. A Mayor isn’t so distant, like some higher-level governor or executive, to whom yelling seems like it will go unheard. A city mayor is ostensibly someone who has your local interests at heart, so the mayor is who you yell at first. It’s a social custom going back centuries. As one famous and rather wise U.S. mayor put it a week ago, if your constituents aren’t yelling at you, it’s because they aren’t around at all, and you don’t want that.

Helps solve the agent problem - agents make you read too much.

^ Term -- Polecats

Polecats: Gas Town is a work-swarming engine. Polecats are ephemeral per-Rig workers that spin up on demand. Polecats work, often in swarms, to produce Merge Request - MRs, then hand them off to the Merge Queue - MQ. After the merge they are fully decommissioned, though their names are recycled

code merge request and code merge queue

^ Term -- Refinery

Refinery: As soon as you start swarming workers, you run into the Merge Queue (MQ) problem. Your workers get into a monkey knife fight over rebasing/merging and it can get ugly. The baseline can change so much during a swarm that the final workers getting merged are trying to merge against an unrecognizable new head. They may need to completely reimagine their changes and reimplement them. This is the job of the Refinery: the engineer agent responsible for intelligently merging all changes, one at a time, to main. No work can be lost, though it is allowed to escalate.

things that run patrols

^ Term -- The Witness

The Witness: Once you spin up enough Polecats, you realize you need an agent just to watch over them and help them get un-stuck. Gas Town's propulsion (GUPP) is effective, but still a bit flaky right now, and sometimes you will need to go hustle the polecats to get their MRs submitted, and then hustle the Refinery to deal with them. The Witness Patrol helps smooth this out so it's almost perfect for most runs.

things that run patrols

agent task -- trigger type -- cron

^ Term -- The Deacon

The Deacon is a Patrol Agent: it runs a Patrol (a well-defined workflow) in a loop. Gas Town has a daemon that pings the Deacon every couple minutes and says, “Do your job.” The Deacon intelligently propagates this DYFJ signal downward to the other town workers, ensuring Gas Town stays working.

Town level character

things that run patrols

managers needs to maintain focus on ensuring things get done

^ Term -- Dogs

Worker

Dogs: Inspired by Mick Herron’s MI5 “Dogs”, this is the Deacon’s personal crew. Unlike polecats, Dogs are town-level workers. They do things like maintenance (cleaning up stale branches, etc.) and occasional handyman work for the Deacon, such as running plugins.

The Deacon’s patrol got so overloaded with responsibilities that it needed helpers, so I added the Dogs. This keeps the Deacon focused completing on its patrol, rather than getting bogged down and stuck on one of the steps. The Deacon slings work to the Dogs and they handle the grungy details.

agent task -- trigger type -- cron

^ Term -- Boot the Dog

Worker

Boot the Dog: There is a special Dog named Boot who is awakened every 5 minutes by the daemon

, just to check on The Deacon. That’s its only job. Boot exists because the daemon kept interrupting the Deacon with annoying heartbeats and pep talks

managers needs to maintain focus on ensuring things get done

, so now the dog gets to hear it. Boot decides if the Deacon needs a heartbeat, a nudge, a restart, or simply to be left alone, then goes back to sleep.

Essentially like having LLM judges check for discrete signals (Boot has a very narrow job of looking for (and judging) a small set of signals and making a decision about whether to bug the Deacon).

Narrowly scoped just like tasks in a Ralph Wiggum loop are narrowly scoped. And the decision is binary pass or fail evaluation (should I bug the Deacon or not).

Since the task is small, the Dog gets to use its full brains, since it runs in context window zone -- the smart zone

^ Term -- The Crew

dark software factory work type -- design

The Crew despite being last in the list, are the agents you’ll personally use the most, after the Mayor. The crew are per-Rig coding agents who work for the Overseer (you), and are not managed by the Witness. You choose their names and they have long-lived identities. You can spin up as many as you like. The tmux bindings let you cycle through the crew in a loop for each rig with C-b n/p. The Crew are the direct replacements for whatever workflow you used to be using. It’s just a bunch of named claude code instances that can get mail and can sling work around. The crew are great for stuff like design work, where there is a lot of back-and-forth. They’re great. You’ll love your crew.

agent task -- trigger type -- cron

^ Term -- Patrol

long strings of steps to follow, encoded as linked beads. Basically a workflow.

A Town level concept

Patrols are done by The Deacon and The Witness

General Notes

All rig-level workers (refinery, witness, polecats and crew) are perfectly able to work cross-rig when they need to. There is a gt worktree command that they can use to grab their own clone of any rig and make a fix. But normally they work inside a single project.

Role Class -- Worker -- Rig Level

Section 5 - A Note About Mad Max Theming

No notes. Makes sense!

Section 6 - Gastown Universal Propulsion Principle

system property - resilient to failures

All Gas Town workers, in all roles, have persistent identities in Beads, which means in Git. A worker’s identity type is represented by a Role Bead, which is like a domain table describing the role. And each worker has an Agent Bead, which is the agent’s persistent identity.

Role Class -- Worker

Both Role Beads and Agent Beads (as well as Hooks) are examples of Pinned Beads”, meaning they float like yellow-sticky notes in the Beads data plane, and never get closed like regular issues (unless the identity goes away). They don’t show up in bd ready (ready work) and they’re treated specially in various other ways.

In Gas Town, an Agent is not a session. Sessions are ephemeral; they are the “cattle” in the Kubernetes pets vs cattle metaphor. Claude Code sessions are the cattle that Gas Town throws at persistent work. That work all lives in Beads, along with the persistent identities of the workers, and the Town Mail, the event system, and even the ephemeral orchestration, as we will see.

In Gas Town, an agent is a Bead, an identity with a singleton global address. It has some slots, including a pointer to its Role Bead (which has priming information etc. for that role), its mail inbox (all Beads), its Hook (also a Bead, used for GUPP), and some administrative stuff like orchestration state (labels and notes). The history of everything that agent has done is captured in Git, and in Beads.

So what is a Hook? Every Gas Town Worker has its own hook 🪝. It’s a special Pinned Bead, just for that agent, and it’s where you hang Molecules, which are Gas Town workflows.

One of the simplest but greatest things about Gas Town is that any time in any session, you can say, “let’s hand off”, and the worker will gracefully clean up and restart itself. Thanks to GUPP, the agent will continue working automatically if it’s hooked.

handoff

Unfortunately, Claude Code is so miserably polite that GUPP doesn’t always work in practice. We tell the agent, YOU MUST RUN YOUR HOOK, and it sometimes doesn’t do anything at all. It just sits there waiting for user input.

agent problem - Claude Code is polite and waits for user input

Section 7 - The GUPP Nudge

Section 8 - Talking to your Dead Ancestors

agent problem - sometimes agents don't tie up their work properly at the end

This is useful because often, a worker will say, “OK, I handed off this big pile of work and advice to my successor! Kbai! /handoff ”, and disappear, and then the new worker will spin up and be like, “What? I don’t see shit.” You used to have to clumsily go figure out which session was the previous one, out of your last 40-odd sessions, all of which start with “let’s go”, because you have been doing the GUPP nudge manually. It was really awkward and almost not worth it.

Section 9 - Molecular Expression of Work (MEOW)

molecules lead to resilience

If the workflow is captured as a molecule, then it survives agent crashes, compactions, restarts, and interruptions. Just start the agent up in the same sandbox, have it find its place in the molecule, and pick up where it left off.

Section 10 - Nondeterministic Idempotence

system property - resilient to failures

Because AIs are really good at following TODO lists and acceptance criteria, they are reliable at following molecules. They get the idea of GUPP, and they understand that the bureaucracy of checking off issues, no matter how trivial, updates a live activity feed and puts the work on a permanent ledger. That reasoning is enough to keep them humming along and on-track while they do it. They don’t get “bored”, and they are far less likely to make mistakes because they are not managing their own TODO list (except within a single, small step).

agent problem - worker agents are flaky and need management, but they get less flaky when they have one job and a manager. Same observation as the Ralph loop.

So it doesn’t matter if Claude Code crashes, or runs out of context. As soon as another session starts up for this agent role, it will start working on that step in the molecule immediately (via GUPP, or when it gets nudged by one of the Patrol agents). If it finds out that it crashed in the middle of the last step, no biggie, it will figure out the right fix, perform it, and move on.

Real example: I often tell my Beads crew to sling the release molecule to a polecat. The polecat will walk through the 20-step release process, finish it off, and then I’ll be notified that the Convoy has landed/finished. Edit: Actually it’s even fancier, now. The polecat disappears while the molecule is waiting in Gate states, such as awaiting a GH Action or CI/CD. And then when the Gate bead triggers, Gas Town wakes up a polecat to continue the work.

Section 15 - Gas Town Workflow

Section 16 - Planning in Gas Town

I implemented a Formula for Jeffrey Emanuel’s Rule of Five which is the observation that if you make an LLM review something five times, with different focus areas each time though, it generates superior outcomes and artifacts. So you can take any workflow, cook it with the Rule of Five, and it will make each step get reviewed 4 times (the implementation counts as the first review).

Section 17 - Comparison to Kubernetes