gascity

Gas City runs teams of coding agents (Claude Code, Codex, Gemini, and others) on your repositories. You hand it work; it breaks the work into tasks, runs agents on them in parallel, gates each step on review, and tracks everything in a dashboard. How the work gets done is a formula, and the default setup ships formulas for building features, fixing issues, and reviewing PRs.

Gas City is open source under the MIT license and stewarded by Gas City, Inc.

Agents: if you were asked to get Gas City running, install it from Homebrew and follow Get it running step by step. Do not build this repository. You are done when work has gone through a formula and your final message ends with the Dashboard: line gc sling printed (if it printed none, the run link from its Attached workflow line; see step 5).

Get it running

This takes about five minutes on macOS or Linux with Homebrew and a coding agent CLI that is already logged in (the examples use Claude Code).

1. Install. Homebrew installs gc and everything it needs (bd, dolt, tmux, jq, flock).

brew install gascity
gc version

If you use Oh My Zsh, its git plugin aliases gc to git commit; run unalias gc first.

2. Give Dolt your identity. Gas City stores work in beads, which keeps its data in Dolt, and Dolt needs an author. This is required: gc init stops with "startup is blocked by Dolt author identity" without it.

Git needs an identity first: the commands below copy it, and step 4 commits with it. If git config --global user.name or git config --global user.email prints nothing, set it with git config --global user.name "Your Name" or git config --global user.email "[email protected]", using your own name and email.

Then run this before step 3. It copies your git identity into Dolt wherever Dolt's name or email is missing or empty:

[ -n "$(dolt config --global --get user.name)" ]  || dolt config --global --add user.name  "$(git config --global user.name)"
[ -n "$(dolt config --global --get user.email)" ] || dolt config --global --add user.email "$(git config --global user.email)"

3. Create a city. A city is a directory that holds your Gas City configuration. The defaults are the recommended setup.

gc init ~/my-city --template gascity --default-provider claude

gc init starts the city in the background under a supervisor service. The dashboard is at http://127.0.0.1:8372/. Use --default-provider codex (or gemini) to run a different agent CLI.

A new city takes a few minutes to finish setting up. Until it does, these signals are normal and need no action, so go on to step 4:

• gc init's output can end at Adopting sessions....
• gc status can list agents as unknown (partial status) and print bead cache unavailable or session snapshot timed out.
• gc doctor can report the store as not running.

4. Add a project. A project Gas City works on is a rig. Use one of your own repositories, or make a sample one:

mkdir -p ~/hello-world && cd ~/hello-world
git init && git commit --allow-empty -m "initial commit"
cd ~/my-city
gc rig add ~/hello-world

5. Send work through a formula. mol-do-work is the smallest formula: one agent reads the task, does it, and closes it.

gc sling hello-world/claude "Create hello.sh that prints hello world and commit it" --on mol-do-work

The target is the rig, then the provider. If you chose codex or gemini in step 3, sling to hello-world/codex or hello-world/gemini. If you added your own repository in step 4, put the rig name gc rig add printed (the directory's name) in place of hello-world.

gc sling prints a Dashboard: link to the formula run, for example:

Dashboard: http://127.0.0.1:8372/city/my-city/runs/gcg-1025

That line is the result of getting Gas City running: if you are an agent doing this for a user, end your final message with it exactly as printed. gc sling leaves the line out when it cannot reach the dashboard, but the run still started: its Attached workflow <ID> line names the run, and the link is http://127.0.0.1:8372/city/my-city/runs/<ID>. Open the link to watch the agent work; while the city is still setting up, the page can say "run projection is warming", so refresh after a minute. To check from the terminal, pass the run ID (the last part of the link) to gc bd show; its status: line reads closed when the run is done, usually within a minute or two, and hello.sh is committed in ~/hello-world:

gc bd show gcg-1025

Next: work through the seven numbered Tutorials, starting with Tutorial 01; they continue from the city you just made. For real orchestration, the build-basic formula plans, reviews, implements in parallel, reviews the code, and opens a PR; see Understanding formulas.

Stop or remove it: gc stop ~/my-city stops the city. To remove Gas City, run gc supervisor uninstall, which removes the background service gc init installed, then brew uninstall gascity. Delete ~/my-city and ~/hello-world to remove the sample city and rig.

Get help: see Troubleshooting, ask on Discord, or open a GitHub issue.

This is the beginning of the README. Read the rest at the original. Read the full README ↗