BE AWARE THIS IS BARELY 10% OF THE ABOVE LINK
The seven Gas Town roles all work together to help keep Gas Town running. And it needs your help sometimes, too; Gas Town runs on equal parts guzzoline and elbow grease.
Here are the key players and concepts:
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.
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.
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.
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.
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 Requests (MRs), then hand them off to the Merge Queue (MQ). After the merge they are fully decommissioned, though their names are recycled.
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.
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.
The Deacon: The deacon is the daemon beacon. It’s named for a Dennis Hopper character from Waterworld that was
inspired by the character Lord Humungus in the Mad Max universe, making it a crossover. 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.
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.
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, 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.
The Crew: 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.
Mail and Messaging
Beads are the atomic unit of work in Gas Town. A bead is a special kind of issue-tracker issue, with an ID, description, status, assignee, and so on. Beads are stored in JSON (one issue per line) and tracked in Git along with your project repo. Town mail and messaging (events) use Beads, as do other types of orchestration.
Gas Town has a two-level Beads structure: Rig beads, and Town beads.
