GitHub - gastownhall/gascity: Orchestration-builder SDK for multi-agent coding workflows · GitHub

Source: original

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

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 gastownhall/gascity/gascity gc version

Or build from source (requires make, Go 1.25+, 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

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