gastown

Gas Town

Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agents.

Why Gas Town?

Prerequisites

• Go 1.23+ - go.dev/dl
• Git 2.25+ - for worktree support
• beads (bd) - github.com/steveyegge/beads - required for issue tracking
• tmux 3.0+ - recommended for the full experience (the Mayor session is the primary interface)
• Claude Code CLI - claude.ai/code

Quick Start

# Install
go install github.com/steveyegge/gastown/cmd/gt@latest

# Ensure Go binaries are in your PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$HOME/go/bin"

# Create workspace (--git auto-initializes git repository)
gt install ~/gt --git
cd ~/gt

# Add a project
gt rig add myproject https://github.com/you/repo.git

# Create your personal workspace
gt crew add <yourname> --rig myproject

# Start working
cd myproject/crew/<yourname>

For advanced multi-agent coordination, use the Mayor session:

gt mayor attach                        # Enter the Mayor's office

Inside the Mayor session, you're talking to Claude with full town context:

"Help me fix the authentication bug in myproject"

The Mayor will create convoys, dispatch workers, and coordinate everything. You can also run CLI commands directly:

# Create a convoy and sling work (CLI workflow)
gt convoy create "Feature X" issue-123 issue-456 --notify --human
gt sling issue-123 myproject

# Track progress
gt convoy list

# Switch between agent sessions
gt agents

Core Concepts

The Mayor is your AI coordinator. It's Claude Code with full context about your workspace, projects, and agents. The Mayor session (gt prime) is the primary way to interact with Gas Town - just tell it what you want to accomplish.

Town (~/gt/)              Your workspace
├── Mayor                 Your AI coordinator (start here)
├── Rig (project)         Container for a git project + its agents
│   ├── Polecats          Workers (ephemeral, spawn → work → disappear)
│   ├── Witness           Monitors workers, handles lifecycle
│   └── Refinery          Merge queue processor

Hook: Each agent has a hook where work hangs. On wake, run what's on your hook.

Beads: Git-backed issue tracker. All work state lives here. github.com/steveyegge/beads

Workflows

Full Stack (Recommended)

The primary Gas Town experience. Agents run in tmux sessions with the Mayor as your interface.

gt start                               # Start Gas Town (daemon + Mayor session)
gt mayor attach                        # Enter Mayor session

# Inside Mayor session, just ask:
# "Create a convoy for issues 123 and 456 in myproject"
# "What's the status of my work?"
# "Show me what the witness is doing"

# Or use CLI commands:
gt convoy create "Feature X" issue-123 issue-456
gt sling issue-123 myproject           # Spawns polecat automatically
gt convoy list                         # Dashboard view
gt agents                              # Navigate between sessions

Minimal (No Tmux)

Run individual Claude Code instances manually. Gas Town just tracks state.

gt convoy create "Fix bugs" issue-123  # Create convoy (sling auto-creates if skipped)
gt sling issue-123 myproject           # Assign to worker
claude --resume                        # Agent reads mail, runs work
gt convoy list                         # Check progress

Pick Your Roles

Gas Town is modular. Run what you need:

• Polecats only: Manual spawning, no monitoring
• + Witness: Automatic worker lifecycle, stuck detection
• + Refinery: Merge queue, code review
• + Mayor: Cross-project coordination

Cooking Formulas

Formulas define structured workflows. Cook them, sling them to agents.

Basic Example

# .beads/formulas/shiny.formula.toml
formula = "shiny"
description = "Design before code, review before ship"

[[steps]]
id = "design"
description = "Think about architecture"

[[steps]]
id = "implement"
needs = ["design"]

[[steps]]
id = "test"
needs = ["implement"]

[[steps]]
id = "submit"
needs = ["test"]

Using Formulas

bd formula list                    # See available formulas
bd cook shiny                      # Cook into a protomolecule
bd mol pour shiny --var feature=auth   # Create runnable molecule
gt convoy create "Auth feature" gt-xyz  # Track with convoy
gt sling gt-xyz myproject          # Assign to worker
gt convoy list                     # Monitor progress

What Happens

1. Cook expands the formula into a protomolecule (frozen template)
2. Pour creates a molecule (live workflow) with steps as beads
3. Worker executes each step, closing beads as it goes
4. Crash recovery: Worker restarts, reads molecule, continues from last step

Example: Beads Release Molecule

A real workflow for releasing a new beads version:

formula = "beads-release"
description = "Version bump and release workflow"

[[steps]]
id = "bump-version"
description = "Update version in version.go and CHANGELOG"

[[steps]]
id = "update-deps"
needs = ["bump-version"]
description = "Run go mod tidy, update go.sum"

[[steps]]
id = "run-tests"
needs = ["update-deps"]
description = "Full test suite, check for regressions"

[[steps]]
id = "build-binaries"
needs = ["run-tests"]
description = "Cross-compile for all platforms"

[[steps]]
id = "create-tag"
needs = ["build-binaries"]
description = "Git tag with version, push to origin"

[[steps]]
id = "publish-release"
needs = ["create-tag"]
description = "Create GitHub release with binaries"

Cook it, pour it, sling it. The polecat runs through each step, and if it crashes after run-tests, a new polecat picks up at build-binaries.

Formula Composition

# Extend an existing formula
formula = "shiny-enterprise"
extends = ["shiny"]

[compose]
aspects = ["security-audit"]  # Add cross-cutting concerns

Key Commands

For Humans (Overseer)

gt start                          # Start Gas Town (daemon + agents)
gt shutdown                       # Graceful shutdown
gt status                         # Town overview
gt <role> attach                  # Jump into any agent session
                                  # e.g., gt mayor attach, gt witness attach

Most other work happens through agents - just ask them.

For Agents

# Convoy (primary dashboard)
gt convoy list                    # Active work across all rigs
gt convoy status <id>             # Detailed convoy progress
gt convoy create "name" <issues>  # Create new convoy

# Work assignment
gt sling <bead> <rig>             # Assign work to polecat
bd ready                          # Show available work
bd list --status=in_progress      # Active work

# Communication
gt mail inbox                     # Check messages
gt mail send <addr> -s "..." -m "..."

# Lifecycle
gt handoff                        # Request session cycle
gt peek <agent>                   # Check agent health

# Diagnostics
gt doctor                         # Health check
gt doctor --fix                   # Auto-repair

Dashboard

Web-based dashboard for monitoring Gas Town activity.

# Start the dashboard
gt dashboard --port 8080

# Open in browser
open http://localhost:8080

Features:

• Convoy tracking - View all active convoys with progress bars and work status
• Polecat workers - See active worker sessions and their activity status
• Refinery status - Monitor merge queue and PR processing
• Auto-refresh - Updates every 10 seconds via htmx

Work status indicators:

Shell Completions

Enable tab completion for gt commands:

Bash

# Add to ~/.bashrc
source <(gt completion bash)

# Or install permanently
gt completion bash > /usr/local/etc/bash_completion.d/gt

Zsh

# Add to ~/.zshrc (before compinit)
source <(gt completion zsh)

# Or install to fpath
gt completion zsh > "${fpath[1]}/_gt"

Fish

gt completion fish > ~/.config/fish/completions/gt.fish

Roles

The Propulsion Principle

If your hook has work, RUN IT.

Agents wake up, check their hook, execute the molecule. No waiting for commands. Molecules survive crashes - any agent can continue where another left off.

Optional: MEOW Deep Dive

Molecular Expression Of Work - the full algebra.

States of Matter

(Protomolecules are an homage to The Expanse. Ice-9 is a nod to Vonnegut.)

Operators

License

MIT