Gas City

Composable orchestration infrastructure for multi-agent coding workflows.

Gas City is an orchestration-builder SDK for multi-agent systems. It extracts the reusable infrastructure from Gas Town into a configurable toolkit with runtime providers, work routing, formulas, orders, health patrol, and a declarative city configuration.

Sponsors

Coming from Gas Town?

Start with Coming from Gas Town?. It maps Town roles, commands, plugins, convoys, and directory habits onto Gas City's primitive-first model so experienced Gas Town users can ramp without trying to port the entire Town architecture literally.

What You Get

• Declarative city configuration in city.toml
• Multiple runtime providers: tmux, subprocess, exec, ACP, Kubernetes, and herdr
• Beads-backed work tracking, formulas, molecules, waits, and mail
• A controller/supervisor loop that reconciles desired state to running state
• Packs, overrides, and rig-scoped orchestration for multi-project setups

Quickstart

See the full install guide at docs/getting-started/installation.md.

Prerequisites

Gas City requires the following tools on your system. gc init and gc start check for these automatically and report any that are missing.

Dependency	Required	Min Version	Install (macOS)	Install (Linux)
tmux	Always	—	brew install tmux	apt install tmux
git	Always	—	brew install git	apt install git
jq	Always	—	brew install jq	apt install jq
pgrep	Always	—	(included in macOS)	apt install procps
lsof	Always	—	(included in macOS)	apt install lsof
dolt	Beads provider bd	2.1.0 or newer	brew install dolt	releases
bd	Beads provider bd	1.0.0	releases	releases
flock	Beads provider bd	—	brew install flock	apt install util-linux
gh	Optional GitHub gates	—	brew install gh	cli.github.com
claude / codex / gemini	Per provider	—	See provider docs	See provider docs

tmux is the default session backend and the fallback, so it stays required even if you run agents on another backend. herdr is an optional alternative backend — see herdr Session Provider to enable it per-agent, per-rig, or city-wide.

The bd (beads) provider is the default. To use a file-based store instead (no dolt/bd/flock needed), set GC_BEADS=file or add [beads] provider = "file" to your city.toml.

Managed Dolt checks require a final Dolt 2.1.0 or newer. Older and pre-release builds are below Gas City's managed bd/Dolt compatibility floor; releases before 1.86.2 can also miss the upstream GC/writer deadlock fix in dolthub/dolt commit ccf7bde206, which can hang dolt_backup sync under heavy write load.

Install from Homebrew:

brew install gascity
gc version

Or build from source (requires make, Go 1.26.4+, and ICU for a transitive Dolt CGO dependency — brew install icu4c on macOS, apt install libicu-dev on Linux; on macOS the Makefile auto-detects the keg-only icu4c paths):

make install

gc init ~/bright-lights
cd ~/bright-lights
gc start

mkdir hello-world
cd hello-world
git init
gc rig add .

bd create "Create a script that prints hello world"
gc session attach mayor

Nix/Flox machines (ICU not on the default CGO path)

On NixOS / Flox-managed Linux toolchains, system include/lib dirs are not searched, so the build fails with fatal error: unicode/uregex.h: No such file or directory. Point CGO at the Nix-store ICU dev headers + matching runtime lib (pick the dev output whose propagated lib matches your gc/dolt link, to avoid ICU version skew), and disable the Makefile's /usr/lib fallback so the Nix and system toolchains don't get mixed:

# Re-resolve the dev header path if the store path changes:
#   find /nix/store -maxdepth 3 -path '*icu4c*-dev/include/unicode/uregex.h'
# Match the lib to what your installed binary links: ldd $(which gc) | grep icu
ICU_DEV=/nix/store/dvhx24q4icrig4q1v1lp7kzi3izd5jmb-icu4c-76.1-dev
ICU_LIB=/nix/store/i4lj3w4yd9x9jbi7a1xhjqsr7bg8jq7p-icu4c-76.1

CGO_ENABLED=1 \
CGO_CPPFLAGS="-I$ICU_DEV/include" \
CGO_LDFLAGS="-L$ICU_LIB/lib" \
SYS_USR_CGO_FALLBACK=0 \
  make build      # or: go build -o bin/gc ./cmd/gc

CGO-backed tests (e.g. go test ./internal/beads) take the same three CGO_* vars — no CGO_ENABLED=0 workaround needed once ICU is pointed at correctly.

For the longer walkthrough, start with Tutorial 01.

Documentation

📖 Read the docs online: docs.gascityhall.com

The docs now use a Mintlify structure rooted in docs/.

• Docs Home
• Installation
• Quickstart
• How Gas City Works
• Contributors
• Reference
• Architecture
• Design Docs
• Archive

Preview the docs locally:

make docs-dev

# or directly from the repo root
./mint.sh dev

Repository Map

Path	What it contains
cmd/gc/	CLI entrypoints, controller wiring, runtime assembly, and command handlers
internal/runtime/	Runtime provider abstraction plus tmux, subprocess, exec, ACP, K8s, hybrid, and herdr implementations
internal/config/	city.toml schema, validation, composition, packs, patches, and override resolution
internal/beads/	Store abstraction and provider implementations for beads (work, mail, convoys) and waits
internal/session/	Session bead metadata, wait lifecycle helpers, and session identity utilities
internal/orders/	Order parsing and scanning for periodic dispatch
internal/convergence/	Bounded iterative refinement loops and gate handling
internal/api/	HTTP API handlers and resource views
docs/	Mintlify docs site (tutorials, guides, reference)
engdocs/	Contributor-facing architecture, design docs, proposals, and archive
examples/	Example cities, packs, formulas, and reference topologies
contrib/	Helper scripts, Dockerfiles, and integration support assets
test/	Integration and support test packages

Where to start

• CLI behavior — cmd/gc/, then the command-specific helper it calls.
• Runtime/provider work — internal/runtime/runtime.go and the provider package you're changing.
• Config and pack behavior — internal/config/config.go, compose.go, and pack.go.
• Work dispatch (sling) — cmd/gc/cmd_sling.go and internal/beads/.
• Supervisor, sessions, wake/sleep — cmd/gc/, internal/session/, and internal/runtime/.

For the concepts these packages implement, see How Gas City Works. For a deeper package walkthrough, see engdocs/contributors/codebase-map.md.

Contributing

Read CONTRIBUTING.md and engdocs/contributors/index.md before opening a PR.

Useful commands:

• make setup
• make check
• make check-docs
• make test-integration

License

MIT