gastownhall/gascity

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.

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

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.

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

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.

📖 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

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

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

Gas City builds and tests with Bazel; CI gates on bazel test. Useful commands (each runs the matching bazel test tier; see engdocs/bazel-quickstart.md):

• make setup
• make check (bazel test //... plus shell guards)
• make check-docs
• make test-acceptance
• make test-integration

MIT