Gas City: A Go SDK for Declarative Multi-Agent Orchestration

What Gas City Actually Solves

Gas City targets the messy middle of multi-agent coding: not the agents themselves, but the plumbing that keeps them alive and coordinated. The README positions it as an orchestration-builder SDK that extracts reusable infrastructure from Gas Town into a configurable toolkit. That means you get runtime providers, work routing, formulas, orders, health patrol, and a declarative city configuration. The intended user is an engineer who already runs several agents, possibly Claude, Codex, or Gemini, and needs a way to start sessions, route work, and reconcile what should be running with what actually is. It is not a framework that writes code for you. It is a control plane for agents that do. The distinction matters: if you are looking for a single-agent assistant, this is overkill. If you have a fleet of agents and no way to supervise them, Gas City gives you a structured model.

The Architecture: City, Rigs, and the Convergence Loop

The core mental model is a city, defined in city.toml, which holds the desired state of your multi-agent setup. You have rigs, which scope orchestration to specific projects, and packs and overrides that compose configuration across multiple rigs. The runtime layer is an abstraction over several providers: tmux, subprocess, exec, ACP, Kubernetes, and herdr. The controller runs a supervisor loop that reconciles desired state to running state, and the convergence package implements bounded iterative refinement loops with gate handling. That is the heart of the system: it does not just launch agents once, it continuously checks whether the running state matches the declared config and attempts to converge. The bounded part is important, because an unbounded loop could spin forever if an agent keeps failing. Orders handle periodic dispatch, so you can schedule work to be scanned and sent to agents on a timer. This is not a static config loader; it is a live system that keeps pushing toward the declared end state.

Getting It Running: Commands, Dependencies, and the ICU Hurdle

Installation is straightforward if you use Homebrew: `brew install gascity`, then `gc version`. For source builds, you need Go 1.26.4+, make, and ICU because of a transitive Dolt CGO dependency. The README spells out the exact flags for NixOS and Flox machines, where ICU headers are not on the default CGO path. That is a real friction point. On a standard Linux box you run `apt install libicu-dev`, but on Nix you have to set CGO_CPPFLAGS and CGO_LDFLAGS to point at the Nix store, and disable the Makefile's /usr/lib fallback with SYS_USR_CGO_FALLBACK=0. The quickstart flow is: `gc init ~/bright-lights`, `cd` into it, `gc start`, then create a rig with `gc rig add .` after a git init. Work is submitted via `bd create` and you attach to a session with `gc session attach mayor`. The CLI checks for tmux, git, jq, pgrep, and lsof automatically, and reports missing ones. tmux is required even if you use another backend, because it is the fallback. That is a design choice that keeps the system dependable but adds a hard dependency.

The Beads Store: Dolt by Default, File as an Escape Hatch

Work tracking and mail go through a store abstraction called beads. The default provider is `bd`, which requires dolt (2.1.0+), the bd CLI (1.0.0), and flock. That is three extra tools just for the store. The README warns about a compatibility floor: Dolt versions before 2.1.0 and releases before 1.86.2 can miss an upstream deadlock fix in dolthub/dolt commit ccf7bde206, which can hang `dolt_backup sync` under heavy write load. That is a specific, documented failure mode. If you do not want the database overhead, you can set `GC_BEADS=file` or add `[beads] provider = "file"` to city.toml, which drops the need for dolt, bd, and flock. The file provider is a lighter path, but you lose whatever semantics the Dolt-backed store gives you, likely versioning or concurrency. The trade-off is explicit in the docs, but the default leans on a database you may not need.

Runtime Providers: Choice Comes with Caveats

Gas City offers six runtime providers: tmux, subprocess, exec, ACP, Kubernetes, and herdr. tmux is the default and the fallback, so even if you run agents in Kubernetes, you still need tmux installed. That is a surprising constraint for a cloud-native setup. herdr is optional and can be enabled per-agent, per-rig, or city-wide, but the README does not explain what herdr gives you beyond being an alternative backend. The subprocess and exec providers likely run agents as child processes, which is simpler but less isolated than tmux sessions. ACP probably refers to the Agent Client Protocol, which would let you connect to agents that speak that protocol. Kubernetes is for scaling across pods. The variety is a strength, but it also means you need to read the provider-specific docs to know which one matches your environment. There is no single universal backend, and the fallback to tmux suggests the authors optimized for local development over production clusters.

A Real Limitation: The Build and Runtime Dependency Stack

The most concrete limitation is the dependency chain. You need Go, make, ICU, tmux, git, jq, pgrep, lsof, and either dolt/bd/flock or the file provider. For the default setup, that is eight external tools before you even start an agent. The ICU requirement is a build-time blocker on Nix systems, and the README goes to great lengths to explain the workaround, which is a sign that it is a common failure. The Dolt deadlock issue is another operational risk: if you use the default beads provider and hit heavy write load, a backup sync can hang. That is not a hypothetical; it is tied to a specific commit. If you are on an older Dolt, you will hit it. The bounded convergence loop is a safeguard against infinite reconciliation, but it also means that if the loop hits its bound without converging, you get a partial state and no clear path forward. The README does not say what happens when the bound is reached, so you have to test that yourself.

Alternatives: Gas Town and the DIY Route

The most direct alternative is Gas Town, the project Gas City was extracted from. The README includes a migration guide for Gas Town users, mapping Town roles, commands, plugins, convoys, and directory habits onto Gas City's primitive-first model. Gas Town is presumably a full application with its own opinionated structure, while Gas City is a lower-level SDK that lets you assemble your own orchestration. If you already use Gas Town, you would migrate to get more control, but you lose the ready-made conventions. Another alternative is to build your own orchestration with a process supervisor like systemd or a task runner, but that does not give you the agent-aware features like orders, waits, and the convergence loop. A third option is to use a generic workflow engine like Temporal, but that requires writing more glue code to manage agent sessions. Gas City's advantage is that it is purpose-built for coding agents, with concepts like rigs and formulas that map to how developers actually organize projects. The disadvantage is that you are tied to its model, and if your workflow does not fit, you will fight the abstraction.

Maintenance and License: What You Are Signing Up For

The project is MIT-licensed, which is permissive and low-friction for commercial use. The repository is active, with a v1.4.1 release in August 2026 and a rolling edge release on main. That suggests ongoing development, but it also means you should track the release notes for breaking changes, especially in the config schema and provider interfaces. The docs are Mintlify-based and live in the repo, so you can preview them locally with `make docs-dev`. The maintenance cost is not trivial: you need to keep Dolt updated to avoid the deadlock issue, and you need to monitor the compatibility floor for bd and Dolt as they evolve. The CGO dependency on ICU means that any upgrade to your Go toolchain or system ICU could break the build, so you need a reproducible build environment. The README does not promise stability guarantees, so pin your versions and test upgrades in a staging rig. The edge release is rolling main, so if you want stability, stick to tagged releases.

Editorial conclusion

Adopt Gas City if you manage multiple coding agents and want a config-driven orchestrator with pluggable runtimes, and you are comfortable with Go, tmux, and the Dolt-backed beads store. Skip it if you need a lightweight, single-agent tool or cannot meet the ICU and CGO build requirements. Before adopting, verify that your target runtime provider (tmux, subprocess, exec, ACP, Kubernetes, herdr) is supported for your use case, check the Dolt version compatibility floor (2.1.0+), and read the migration guide if you come from Gas Town. Also test the convergence loop with your own gate conditions, because the bounded iterative refinement may not fit every workflow.

Official sources

1. Official README
2. Project repository
3. Release notes