Gas City

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.

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, 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

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	1.86.2 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
claude / codex / gemini	Per provider	—	See provider docs	See provider docs

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 1.86.2 or newer. Earlier and pre-release builds can 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 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.

Documentation

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

Repository Map

• 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

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