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.

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.

• Declarative city configuration in city.toml
• Multiple runtime providers: tmux, subprocess, exec, ACP, and Kubernetes
• 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

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

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

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.

Install from Homebrew:

brew install gastownhall/gascity/gascity
gc version

Or build from source (requires make and Go 1.25+):

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

For the longer walkthrough, start with Tutorial 01.

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

• Docs Home
• Installation
• Quickstart
• Repository Map
• Contributors
• Reference
• Architecture
• Design Docs
• Archive

Preview the docs locally:

make docs-dev

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

• cmd/gc/: CLI commands, controller wiring, and supervisor integration
• internal/runtime/: runtime provider abstraction and implementations
• internal/config/: city.toml schema, pack composition, and validation
• internal/beads/: store abstraction and provider implementations
• internal/session/: session bead metadata and wait helpers
• internal/orders/: periodic formula and exec dispatch
• internal/convergence/: bounded iterative refinement loops
• examples/: sample cities, packs, formulas, and configs
• contrib/: helper scripts and deployment assets
• test/: integration and support test packages

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

Useful commands:

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

MIT