gastownhall/gascity

Gas City – Orchestration SDK for Multi‑Agent Coding Workflows

What it is

• A Go‑based SDK that lets you declaratively define and run cities – collections of agents (called beads) that perform coding‑related tasks.
• Think of it as a toolbox that extracts the plumbing from the larger Gas Town platform and makes it reusable for any project that needs coordinated AI‑agents, scripts, or subprocesses.

Core concepts

• city.toml – a simple TOML file describing the desired state of your agents, their runtimes, and how work should be routed.
• Runtime providers – plug‑in back‑ends that actually execute the agents. Built‑in options include:
  • tmux (default, runs each agent in its own pane)
  • subprocess / exec
  • ACP (remote execution)
  • Kubernetes
  • herdr (a lightweight session manager)
• Beads – the persistent work‑tracking store. By default it uses the bd (Beads) provider backed by Dolt, but a file‑based store is also supported.
• Supervisor loop – continuously reconciles the desired city state (what you declared) with the actual running state, spawning, stopping, or restarting agents as needed.
• Packs & overrides – modular bundles of configuration that let you compose multi‑project setups without duplication.

Key features

• Declarative configuration (city.toml) for reproducible environments.
• Multiple execution back‑ends, from local tmux sessions to Kubernetes clusters.
• Built‑in work tracking, formulas, and messaging between agents.
• Health‑checking and automatic recovery via the supervisor.
• Extensible “packs” for sharing common patterns across projects.

Typical use‑cases

• Coordinating several LLM‑powered coding assistants that generate, test, and commit code.
• Running a pipeline of AI agents that scrape data, process it, and feed results to downstream models.
• Managing hybrid workloads where some agents run locally (tmux) and others run in the cloud (K8s, ACP).

Getting started

1. Install the CLI (Homebrew or make install).
2. Initialise a city: gc init ~/my‑city && cd ~/my‑city.
3. Add a rig (a project folder) with gc rig add ..
4. Create a bead (a unit of work) – e.g. bd create "Create a script that prints hello world".
5. Attach to the supervising session: gc session attach mayor and watch the agents run.

Architecture at a glance

• cmd/gc/ – entry‑point CLI, parses commands and wires the controller.
• internal/runtime/ – abstraction layer for providers; each provider implements how agents are launched and monitored.
• internal/config/ – parses city.toml, resolves packs/overrides, validates schema.
• internal/beads/ – storage layer for work items, messages, and wait conditions.
• internal/convergence/ – the reconciliation engine that drives the supervisor loop.
• internal/api/ – optional HTTP API for external tooling.

Documentation & community

• Full docs: https://docs.gascityhall.com (Mintlify site).
• Quick‑start tutorials, design docs, and architecture overviews are in the repo under docs/ and engdocs/.
• Join the Discord community for help and announcements.

License

• MIT – free to use, modify, and distribute.

---

Gas City is a real, production‑grade project aimed at developers building sophisticated, multi‑agent AI or automation pipelines. It provides the plumbing needed to define, launch, and keep those agents healthy across a variety of execution environments.