How to use Gas Town: install gt, run the Mayor and track agent work

What Gas Town is and who it is for

Gas Town coordinates multiple AI coding agents working on different tasks. Instead of losing context when an agent restarts, it persists work state in git-backed hooks, which the project describes as enabling reliable multi-agent workflows.

It fits developers who already use Claude Code or similar agents on several tasks at once, and teams who want agent work tracked as git-backed issues. If you only use one agent occasionally, the coordination layer adds setup overhead you may not need.

Check the prerequisites before installing

Native installs need several host tools. The README lists Git 2.20+, Go 1.26.2+ for Linux, Windows and macOS source builds, Beads (bd) 0.57.0+ for native installs, and tmux 3.0+ for gt up. Dolt is required on Linux and Windows.

Docker is an alternative path: the README says Docker installs only need Docker Compose on the host, because the image supplies Go, Dolt, bd, tmux and CLI utilities.

• Git 2.20+ (worktree support)
• Go 1.26.2+ for Linux, Windows and macOS source builds (not needed for brew install gastown)
• Beads (bd) 0.57.0+ for native installs
• tmux 3.0+ for gt up
• Dolt, required on Linux and Windows
• Claude Code CLI is the default runtime; alternatives include Codex, Copilot, Gemini and Cursor

Install gt on macOS

On macOS, Homebrew installs gt, bd and dolt together. The README advises against go install on macOS because the unsigned binary it produces gets killed by Gatekeeper.

Install gt on Linux or Windows

On Linux, install Dolt first using the Dolt installation guide, then install gt and bd with go install. On Windows, install Dolt first too, since go install does not install it. Both binaries land in %USERPROFILE%\go\bin\ on Windows, so put that directory ahead of older installs on PATH and open a new shell.

On Linux, if your Go binary directory is not on PATH, the README suggests prepending it so fresh binaries take precedence. Use ~/.zshrc instead if you use zsh.

Learn the core concepts: Town, Rigs and the Mayor

A Town is your workspace directory, for example ~/gt/, containing projects, agents and configuration. Each Rig wraps a git repository and manages its agents. The Mayor is your primary AI coordinator and the README says to start there: just tell the Mayor what you want to accomplish.

Crew Members are your personal workspace within a rig for hands-on work. Polecats are worker agents with persistent identity but ephemeral sessions, spawned for tasks.

• Town: workspace directory (e.g. ~/gt/)
• Rig: project container around a git repository
• Mayor: AI coordinator with context about your workspace
• Crew Member: your hands-on workspace inside a rig
• Polecat: worker agent spawned for a task

Understand how work is tracked

Work state lives in Beads, a git-backed issue tracker. Bead IDs use a prefix plus a 5-character alphanumeric format, such as gt-abc12. Commands like gt sling and gt convoy accept these IDs. Convoys bundle multiple beads for agents to work on.

Hooks are git worktree-based persistent storage that survives crashes and restarts. The watchdog layer is made of the Witness (per-rig lifecycle), the Deacon (background patrol) and Dogs (maintenance workers).

Ask about past agent sessions with seance

Seance discovers previous agent sessions through .events.jsonl logs, so an agent can query its predecessors for context and decisions from earlier work. The README gives these two example commands.