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?](docs/getting-started/coming-from-gastown.md).
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](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](https://github.com/dolthub/dolt/releases) |
| bd | Beads provider `bd` | 1.0.0 | [releases](https://github.com/gastownhall/beads/releases) | [releases](https://github.com/gastownhall/beads/releases) |
| flock | Beads provider `bd` | — | `brew install flock` | `apt install util-linux` |
| gh | Optional GitHub gates | — | `brew install gh` | [cli.github.com](https://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](https://herdr.dev) is an
optional alternative backend — see
[herdr Session Provider](docs/reference/herdr-provider.md) 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:
```bash
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):
```bash
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:
```bash
# 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](docs/tutorials/01-cities-and-rigs.md).
## Documentation
📖 **Read the docs online: [docs.gascityhall.com](https://docs.gascityhall.com)**
The docs now use a Mintlify structure rooted in [`docs/`](docs/README.md).
- [Docs Home](docs/index.mdx)
- [Installation](docs/getting-started/installation.md)
- [Quickstart](docs/getting-started/quickstart.md)
- [How Gas City Works](docs/getting-started/how-gas-city-works.md)
- [Contributors](engdocs/contributors/index.md)
- [Reference](docs/reference/index.md)
- [Architecture](engdocs/architecture/index.md)
- [Design Docs](engdocs/design/index.md)
- [Archive](engdocs/archive/index.md)
Preview the docs locally:
```bash
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](docs/getting-started/how-gas-city-works.md). For a deeper
package walkthrough, see
[`engdocs/contributors/codebase-map.md`](engdocs/contributors/codebase-map.md).
## Contributing
Read [CONTRIBUTING.md](CONTRIBUTING.md) and
[engdocs/contributors/index.md](engdocs/contributors/index.md) before opening a
PR.
Useful commands:
- `make setup`
- `make check`
- `make check-docs`
- `make test-integration`
## License
MIT