Gas Town is an agentic development environment, designed to manage dozens of instances of Claude Code working simultaneously, and managed using the gt and bd (Beads) binaries, coordinated with tmux, in directories managed by git.

Though coding work in the Town (your overall work space) and in each Rig (project) relies on the interaction of several types of agents and artifacts, the goal is simple: You provide a high-level description for the work you want done, and the agents of Gas Town collectively execute it.

What makes Gas Town different from other agentic environments is a focus on agent management and orchestration, not just code output. Gas Town agents use Beads to provide persistent state both within an agent lifespan and passed from one agent to another. Gas Town also includes a number of kinds of agents (dogs; polecats) and actions (slinging work to an agent; nudging an agent) that keep agents on task, defending against both context decay and work stoppage.

If you are familiar with Kubernetes’ goal of providing consistent service by provisioning and managing unreliable nodes, you can think of Gas Town as an environment that monitors and supports specific tasks by ensuring that agents are present and working correctly, and nudging or restarting them if they are not.

If you’ve used Claude or other agentic coding interfaces before, you’ll know the primary challenges are: communicating what is to be done, keeping the agent doing it across context compaction or failure, managing multiple agents to do work, and dealing with the resulting flood of merge requests if you overcome the previous challenges. These are all problems that Gas Town sets out to solve.

Conceptually, Gas Town is divided into:

  • Principles
  • Environments
  • Roles
  • Work Units
  • Workflow

Principles

There are three key design principles to Gas Town: MEOW, GUPP, and NDI.

MEOW is the Molecular Expression of Work.

Much of the agent management in Gas Town involves breaking down a large goal into instructions detailed enough for an agent to take them on.

There are several artifacts that support MEOWs, including Beads, Epics (a specialized type of Bead used for organizing an overall goal into sub-tasks), Formulas (the source form for workflows, typically written in TOML format), and Molecules or Mols (a durable workflow composed of Beads chained together, typically derived from a Formula.)

GUPP is the Gastown Universal Propulsion Principle

GUPP involves telling agents: "If there is work on your Hook, YOU MUST RUN IT". GUPP ensures that agents autonomously proceed through tasks without waiting for human input. Several kinds of agents and processes are responsible for GUPP. Unlike MEOW, which requires a high level of human effort, GUPP is a mostly background process, but you should understand it in order to understand how Gas Town is meant to work.

NDI is Nondeterministic Idempotence

This is the overall goal of Gas Town — useful outcomes are guaranteed by the orchestration and oversight of potentially flaky processes. Even if an AI session crashes or takes a nondeterministic path, the persistent nature of Beads and Hooks, and the oversight of agents like the Mayor, Witnesses, and Deacons, ensures the workflow eventually completes.

Environments

  • The Town: The management headquarters and HQ directory (e.g., ~/gas_town). The Town binary (gt) orchestrates all workers across multiple project-specific Rigs.
  • Rig: A specific project or Git repository placed under Gas Town management. Most agent roles, Polecats, Witnesses, Refineries, and Crew, are assigned on a per-rig basis. The town-level (overall workspace) roles are Mayor, Deacon, and Dogs.

Roles

  • Overseer: The human user (you), who manages the Town, and can observe or message many parts of the system. Communication with agents uses tmux. (Development of other UIs is on the TODO list.)

Town-level

  • Mayor: Town-level agent and your chief-of-staff. The Mayor typically initiates Convoys and notifies the human when work is finished.
  • Deacon: Town-level "daemon beacon" that runs a continuous Patrol to ensure all other workers stay active. It propagates heartbeats and runs town-level Plugins.
  • Dogs: Town-level workers that serve as the Deacon's personal crew. They handle maintenance tasks and grungy details so the Deacon can stay focused on its primary Patrol.
  • Boot the Dog: Town-level. A special Dog whose sole job is to check on the Deacon every five minutes and provide a "nudge" if the Deacon becomes stuck or unresponsive.

Rig-level

  • Polecats: Per rig. Ephemeral workers that spin up on demand to perform "swarming" work. They produce Merge Requests (MRs) and are decommissioned after their work is handed to the Merge Queue.
  • Refinery: Per rig. Responsible for the Merge Queue. A Refinery intelligently merges changes from Polecats into the main branch one at a time to prevent "monkey knife fights" over rebasing.
  • Witness: Per rig. A patrol agent that watches over Polecats and Refineries. It ensures workers don't get stuck and helps "hustle" them to submit their work.
  • Crew: Per rig. Long-lived, named agents assigned to a specific Rig. Unlike Polecats, they have persistent identities and are used directly by the Overseer (you) for tasks requiring back-and-forth collaboration, such as design work.

Work Units

  • Beads: The universal, Git-backed data and control plane for everything in Gas Town. A Bead is the atomic unit of work—essentially a lightweight issue-tracker entry stored as JSONL—that tracks status, assignees, and descriptions.
  • Formula: A source form for workflows written in TOML. Formulas are "cooked" into Protomolecules and then instantiated into Wisps or Molecules.
  • Protomolecule: A template or class for a Molecule. It contains instructions and dependencies that are instantiated into a live workflow through variable substitution.
  • Molecule: A durable workflow composed of chained Beads. Molecules can have complex shapes, loops, and gates, allowing agents to execute a sequence of small tasks atomically.
  • Wisp: An ephemeral Bead used for high-velocity orchestration. Unlike standard Beads, Wisps are not persisted to Git; they are "burned" (destroyed) at the end of a run to prevent polluting the repository history.
  • Hook: A special pinned Bead unique to each agent. The sling command adds Molecules (work specified in a bead) to the Hook, which must be executed immediately by the worker, according to the GUPP principle.

Workflow

  • Convoy: The primary work-order or ticketing unit in Gas Town. A Convoy wraps related Beads and Swarms into a single trackable unit for delivery, often displayed in a dashboard for the Overseer.
  • Slinging: The act of assigning work to a specific agent using the gt sling command. This allows the Overseer or the Mayor to delegate tasks to Polecats, Dogs, or the Crew.
  • Nudging: A real-time messaging command (gt nudge) used to kick an agent into checking its Hook and mail. It works around the tendency of Claude Code to wait for user input before acting.
  • Handoff: A command (/handoff or gt handoff) that triggers an agent to clean up its current session and restart. This refresh allows the agent to clear its context window and pick up new instructions from its Hook.
  • Seance: A feature (gt seance) that allows a current agent to communicate with its "dead ancestors" (previous sessions of the same role). It uses the /resume feature to retrieve information or advice left behind by a predecessor.
  • Patrol: An ephemeral workflow in a specific rig, run in a loop by patrol workers like the Deacon, Witnesses, or Refinery. The main function of a patrol is to maintain the system's "heartbeat" and ensure work is completed.