Skip to main content
A single coding agent is remarkable on its own — but it works alone. One session, one train of thought, and when it crashes, you have to recover the context. Real engineering work is bigger than that: it spans many steps, runs longer than any one session, and shouldn’t need you hovering over it. There are two ways to put coding agents to work. The first is the interactive session — you sit with one agent and steer it, watching every move. The second is to automate the work itself: turn a fleet of agents into a software factory that runs without you in the loop. An interactive session gives you a faster pair of hands; a software factory is what gets you production quality at machine speed. Gas City is that software factory. You write down how a job gets done once — a formula — and an orchestrator runs it across a fleet of agents, outside your session. It breaks the job into tracked units of work, runs the independent pieces in parallel, holds the rest until their dependencies finish, and retries what fails until the whole thing is done. In practice: you describe a feature once and come back to a finished branch. The factory decomposes the work, implements the pieces in parallel across agents, reviews the result, gap-checks it against the plan, and fills what’s missing. The review and gap-check are how you get production quality; the parallel fan-out is the machine speed. The work is durable, so a crash never loses progress. And because no role is hardwired into the binary, the same engine runs your local configuration, the one you share with your team, or the ones shared by the community. That orchestration is built from six primitives: The six primitives and how they relate: Packs declare agents, formulas, and orders; a Formula operates over a convoy of Beads, fanning work out to Agents that execute in a Rig; Events are fired as it happens so humans and agents can observe.
  • Agent — who does the work
  • Bead — what the work is: the tracked unit that survives a crash
  • Formula — how a job gets done: the method the orchestrator runs across many agents
  • Rig — where it happens: a project registered with the city
  • Pack — what configures the system; the City is your local pack, and it imports shared ones
  • Event — fired as things happen, so you and other agents can observe the fleet
How Gas City Works walks through all six and how they fit together.

​
Get started

  • Installation — the local toolchain and the shortest path to a working gc binary.
  • Upgrading an Existing City — back up a city, upgrade gc and bd, and run the one-time Beads schema migration.
  • Quickstart — boot the smallest city you can run locally.
  • How Gas City Works — the mental model: the six primitives and how work flows through them.
  • Coming from Gas Town — map Gas Town’s roles, commands, plugins, and habits onto Gas City’s primitives.
  • FAQ — quick answers to what Gas City adds over a single coding agent, what it runs on, and how it compares.
  • Troubleshooting setup — fixes for the snags you hit getting a city running.

​
Find your way around

  • Tutorials — the guided, end-to-end path that builds one city up, command by command.
  • Guides — go deeper on a subsystem or accomplish a specific workflow.
  • Troubleshooting — diagnosis walkthroughs and operational runbooks for a running city.
  • Reference — exact commands, config fields, formula contracts, and provider details.
Contributor-facing material — architecture, design notes, and the archive — lives in the engdocs/ directory in the repository.
Last modified on October 6, 2026