johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 (README.md): rewrite documentation with comprehensive guides, archi… (#226)

Browse Source 
* 📝 (README.md): rewrite documentation with comprehensive guides, architecture diagrams, and detailed workflows
The README has been completely overhauled to provide a more structured and detailed explanation of the Gas Town system. It now includes architecture diagrams, in-depth descriptions of core concepts, step-by-step installation and usage guides, and troubleshooting tips to improve the developer onboarding experience.

* 📝 (README.md): improve formatting, alignment, and spacing

The tables are realigned to improve readability in the raw view, and missing newlines are added before code blocks and after section headers to ensure proper rendering and visual separation.
This commit is contained in:
Dave Williams
2026-01-06 20:59:44 +00:00
committed by GitHub
parent 7fe505d673
commit 83c47df980
1 changed files with 302 additions and 276 deletions
Download Patch File Download Diff File Expand all files Collapse all files

578
README.md
View File

@@ -1,388 +1,414 @@
# Gas Town # Gas Town
Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agents. **Multi-agent orchestration system for Claude Code with persistent work tracking**
## Why Gas Town? ## Overview
| Without | With Gas Town | Gas Town is a workspace manager that lets you coordinate multiple Claude Code agents working on different tasks. Instead of losing context when agents restart, Gas Town persists work state in git-backed hooks, enabling reliable multi-agent workflows.
|---------|---------------|
| Agents forget work after restart | Work persists on hooks - survives crashes, compaction, restarts |
| Manual coordination | Agents have mailboxes, identities, and structured handoffs |
| 4-10 agents is chaotic | Comfortably scale to 20-30 agents |
| Work state in agent memory | Work state in Beads (git-backed ledger) |
## Prerequisites ### What Problem Does This Solve?
- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/) | Challenge | Gas Town Solution |
- **Git 2.25+** - for worktree support | ------------------------------- | -------------------------------------------- |
- **beads (bd)** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - required for issue tracking | Agents lose context on restart | Work persists in git-backed hooks |
- **tmux 3.0+** - recommended for the full experience (the Mayor session is the primary interface) | Manual agent coordination | Built-in mailboxes, identities, and handoffs |
- **Claude Code CLI** - [claude.ai/code](https://claude.ai/code) | 4-10 agents become chaotic | Scale comfortably to 20-30 agents |
| Work state lost in agent memory | Work state stored in Beads ledger |
## Quick Start ### Architecture
```bash ```mermaid
# Install graph TB
go install github.com/steveyegge/gastown/cmd/gt@latest Mayor[The Mayor<br/>AI Coordinator]
Town[Town Workspace<br/>~/gt/]
# Ensure Go binaries are in your PATH (add to ~/.zshrc or ~/.bashrc) Town --> Mayor
export PATH="$PATH:$HOME/go/bin" Town --> Rig1[Rig: Project A]
Town --> Rig2[Rig: Project B]
# Create workspace (--git auto-initializes git repository) Rig1 --> Crew1[Crew Member<br/>Your workspace]
gt install ~/gt --git Rig1 --> Hooks1[Hooks<br/>Persistent storage]
cd ~/gt Rig1 --> Polecats1[Polecats<br/>Worker agents]
# Add a project Rig2 --> Crew2[Crew Member]
gt rig add myproject https://github.com/you/repo.git Rig2 --> Hooks2[Hooks]
Rig2 --> Polecats2[Polecats]
# Create your personal workspace Hooks1 -.git worktree.-> GitRepo1[Git Repository]
gt crew add <yourname> --rig myproject Hooks2 -.git worktree.-> GitRepo2[Git Repository]
# Start working style Mayor fill:#e1f5ff
cd myproject/crew/<yourname> style Town fill:#f0f0f0
``` style Rig1 fill:#fff4e1
style Rig2 fill:#fff4e1
For advanced multi-agent coordination, use the Mayor session:
```bash
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:
```bash
# 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 ## 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. ### The Mayor 🎩
``` Your primary AI coordinator. The Mayor is a Claude Code instance with full context about your workspace, projects, and agents. **Start here** - just tell the Mayor 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. ### Town 🏘️
**Beads**: Git-backed issue tracker. All work state lives here. [github.com/steveyegge/beads](https://github.com/steveyegge/beads) Your workspace directory (e.g., `~/gt/`). Contains all projects, agents, and configuration.
## Workflows ### Rigs 🏗️
### Full Stack (Recommended) Project containers. Each rig wraps a git repository and manages its associated agents.
The primary Gas Town experience. Agents run in tmux sessions with the Mayor as your interface. ### Crew Members 👤
Your personal workspace within a rig. Where you do hands-on work.
### Polecats 🦨
Ephemeral worker agents that spawn, complete a task, and disappear.
### Hooks 🪝
Git worktree-based persistent storage for agent work. Survives crashes and restarts.
### Convoys 🚚
Work tracking units. Bundle multiple issues/tasks that get assigned to agents.
### Beads Integration 📿
Git-backed issue tracking system that stores work state as structured data.
## Installation
### Prerequisites
- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
- **Git 2.25+** - for worktree support
- **beads (bd)** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
- **tmux 3.0+** - recommended for full experience
- **Claude Code CLI** - [claude.ai/code](https://claude.ai/code)
### Setup
```bash ```bash
gt start # Start Gas Town (daemon + Mayor session) # Install Gas Town
gt mayor attach # Enter Mayor session go install github.com/steveyegge/gastown/cmd/gt@latest
# Inside Mayor session, just ask: # Add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
# "Create a convoy for issues 123 and 456 in myproject" export PATH="$PATH:$HOME/go/bin"
# "What's the status of my work?"
# "Show me what the witness is doing"
# Or use CLI commands: # Create workspace with git initialization
gt convoy create "Feature X" issue-123 issue-456 gt install ~/gt --git
gt sling issue-123 myproject # Spawns polecat automatically cd ~/gt
gt convoy list # Dashboard view
gt agents # Navigate between sessions # Add your first project
gt rig add myproject https://github.com/you/repo.git
# Create your crew workspace
gt crew add yourname --rig myproject
cd myproject/crew/yourname
# Start the Mayor session (your main interface)
gt mayor attach
``` ```
### Minimal (No Tmux) ## Quick Start Guide
Run individual Claude Code instances manually. Gas Town just tracks state. ### Basic Workflow
```mermaid
sequenceDiagram
participant You
participant Mayor
participant Convoy
participant Agent
participant Hook
You->>Mayor: Tell Mayor what to build
Mayor->>Convoy: Create convoy with issues
Mayor->>Agent: Sling issue to agent
Agent->>Hook: Store work state
Agent->>Agent: Complete work
Agent->>Convoy: Report completion
Mayor->>You: Summary of progress
```
### Example: Feature Development
```bash ```bash
gt convoy create "Fix bugs" issue-123 # Create convoy (sling auto-creates if skipped) # 1. Start the Mayor
gt sling issue-123 myproject # Assign to worker gt mayor attach
claude --resume # Agent reads mail, runs work
gt convoy list # Check progress # 2. In Mayor session, create a convoy
gt convoy create "Feature X" issue-123 issue-456 --notify --human
# 3. Assign work to an agent
gt sling issue-123 myproject
# 4. Track progress
gt convoy list
# 5. Monitor agents
gt agents
``` ```
### Pick Your Roles ## Common Workflows
Gas Town is modular. Run what you need: ### Mayor Workflow (Recommended)
- **Polecats only**: Manual spawning, no monitoring **Best for:** Coordinating complex, multi-issue work
- **+ Witness**: Automatic worker lifecycle, stuck detection
- **+ Refinery**: Merge queue, code review
- **+ Mayor**: Cross-project coordination
## Cooking Formulas ```mermaid
flowchart LR
Formulas define structured workflows. Cook them, sling them to agents. Start([Start Mayor]) --> Tell[Tell Mayor<br/>what to build]
Tell --> Creates[Mayor creates<br/>convoy + agents]
### Basic Example Creates --> Monitor[Monitor progress<br/>via convoy list]
Monitor --> Done{All done?}
```toml Done -->|No| Monitor
# .beads/formulas/shiny.formula.toml Done -->|Yes| Review[Review work]
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 **Commands:**
```bash ```bash
bd formula list # See available formulas # Attach to Mayor
bd cook shiny # Cook into a protomolecule gt mayor attach
bd mol pour shiny --var feature=auth # Create runnable molecule
gt convoy create "Auth feature" gt-xyz # Track with convoy # In Mayor, create convoy and let it orchestrate
gt sling gt-xyz myproject # Assign to worker gt convoy create "Auth System" issue-101 issue-102 --notify
gt convoy list # Monitor progress
# Track progress
gt convoy list
``` ```
### What Happens ### Beads Formula Workflow
1. **Cook** expands the formula into a protomolecule (frozen template) **Best for:** Predefined, repeatable processes
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 Formulas are YAML-defined workflows stored in `.beads/formulas/`.
A real workflow for releasing a new beads version: **Example Formula** (`.beads/formulas/release.yaml`):
```toml ```yaml
formula = "beads-release" formula: release
description = "Version bump and release workflow" description: Standard release process
steps:
- name: bump-version
command: ./scripts/bump-version.sh {{version}}
[[steps]] - name: run-tests
id = "bump-version" command: make test
description = "Update version in version.go and CHANGELOG"
[[steps]] - name: build
id = "update-deps" command: make build
needs = ["bump-version"]
description = "Run go mod tidy, update go.sum"
[[steps]] - name: create-tag
id = "run-tests" command: git tag -a v{{version}} -m "Release v{{version}}"
needs = ["update-deps"]
description = "Full test suite, check for regressions"
[[steps]] - name: publish
id = "build-binaries" command: ./scripts/publish.sh
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 **Execute:**
after `run-tests`, a new polecat picks up at `build-binaries`.
### Formula Composition ```bash
# List available formulas
bd formula list
```toml # Run a formula with variables
# Extend an existing formula bd cook release --var version=1.2.0
formula = "shiny-enterprise"
extends = ["shiny"]
[compose] # Create formula instance for tracking
aspects = ["security-audit"] # Add cross-cutting concerns bd mol pour release --var version=1.2.0
```
### Manual Convoy Workflow
**Best for:** Direct control over work distribution
```bash
# Create convoy manually
gt convoy create "Bug Fixes" --human
# Add issues
gt convoy add-issue bug-101 bug-102
# Assign to specific agents
gt sling bug-101 myproject/my-agent
# Check status
gt convoy show
``` ```
## Key Commands ## Key Commands
### For Humans (Overseer) ### Workspace Management
```bash ```bash
gt start # Start Gas Town (daemon + agents) gt install <path> # Initialize workspace
gt shutdown # Graceful shutdown gt rig add <name> <repo> # Add project
gt status # Town overview gt rig list # List projects
gt <role> attach # Jump into any agent session gt crew add <name> --rig <rig> # Create crew workspace
# e.g., gt mayor attach, gt witness attach ```
### Agent Operations
```bash
gt agents # List active agents
gt sling <issue> <rig> # Assign work to agent
gt mayor attach # Start Mayor session
gt prime # Alternative to mayor attach
```
### Convoy (Work Tracking)
```bash
gt convoy create <name> [issues...] # Create convoy
gt convoy list # List all convoys
gt convoy show [id] # Show convoy details
gt convoy add-issue <issue> # Add issue to convoy
``` ```
### Configuration ### Configuration
```bash ```bash
gt config agent list [--json] # List all agents (built-in + custom) # Set custom agent command
gt config agent get <name> # Show agent configuration
gt config agent set <name> <cmd> # Create or update custom agent
gt config agent remove <name> # Remove custom agent (built-ins protected)
gt config default-agent [name] # Get or set town default agent
```
**Example**: Use a cheaper model for most work:
```bash
gt config agent set claude-glm "claude-glm --model glm-4" gt config agent set claude-glm "claude-glm --model glm-4"
# Set default agent
gt config default-agent claude-glm gt config default-agent claude-glm
# View config
gt config show
``` ```
Most other work happens through agents - just ask them. ### Beads Integration
### For Agents
```bash ```bash
# Convoy (primary dashboard) bd formula list # List formulas
gt convoy list # Active work across all rigs bd cook <formula> # Execute formula
gt convoy status <id> # Detailed convoy progress bd mol pour <formula> # Create trackable instance
gt convoy create "name" <issues> # Create new convoy bd mol list # List active instances
# 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 ## Dashboard
Web-based dashboard for monitoring Gas Town activity. Gas Town includes a web dashboard for monitoring:
```bash ```bash
# Start the dashboard # Start dashboard
gt dashboard --port 8080 gt dashboard --port 8080
# Open in browser # Open in browser
open http://localhost:8080 open http://localhost:8080
``` ```
**Features:** 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: - Real-time agent status
| Status | Color | Meaning | - Convoy progress tracking
|--------|-------|---------| - Hook state visualization
| `complete` | Green | All tracked items done | - Configuration management
| `active` | Green | Recent activity (< 1 min) |
| `stale` | Yellow | Activity 1-5 min ago | ## Advanced Concepts
| `stuck` | Red | Activity > 5 min ago |
| `waiting` | Gray | No assignee/activity | ### The Propulsion Principle
Gas Town uses git hooks as a propulsion mechanism. Each hook is a git worktree with:
1. **Persistent state** - Work survives agent restarts
2. **Version control** - All changes tracked in git
3. **Rollback capability** - Revert to any previous state
4. **Multi-agent coordination** - Shared through git
### Hook Lifecycle
```mermaid
stateDiagram-v2
[*] --> Created: Agent spawned
Created --> Active: Work assigned
Active --> Suspended: Agent paused
Suspended --> Active: Agent resumed
Active --> Completed: Work done
Completed --> Archived: Hook archived
Archived --> [*]
```
### MEOW (Mayor-Enhanced Orchestration Workflow)
MEOW is the recommended pattern:
1. **Tell the Mayor** - Describe what you want
2. **Mayor analyzes** - Breaks down into tasks
3. **Convoy creation** - Mayor creates convoy with issues
4. **Agent spawning** - Mayor spawns appropriate agents
5. **Work distribution** - Issues slung to agents via hooks
6. **Progress monitoring** - Track through convoy status
7. **Completion** - Mayor summarizes results
## Shell Completions ## Shell Completions
Enable tab completion for `gt` commands:
### Bash
```bash ```bash
# Add to ~/.bashrc # Bash
source <(gt completion bash) gt completion bash > /etc/bash_completion.d/gt
# Or install permanently # Zsh
gt completion bash > /usr/local/etc/bash_completion.d/gt
```
### Zsh
```bash
# Add to ~/.zshrc (before compinit)
source <(gt completion zsh)
# Or install to fpath
gt completion zsh > "${fpath[1]}/_gt" gt completion zsh > "${fpath[1]}/_gt"
```
### Fish # Fish
```bash
gt completion fish > ~/.config/fish/completions/gt.fish gt completion fish > ~/.config/fish/completions/gt.fish
``` ```
## Roles ## Project Roles
| Role | Scope | Job | | Role | Description | Primary Interface |
|------|-------|-----| | --------------- | ------------------ | -------------------- |
| **Overseer** | Human | Sets strategy, reviews output, handles escalations | | **Mayor** | AI coordinator | `gt mayor attach` |
| **Mayor** | Town-wide | Cross-rig coordination, work dispatch | | **Human (You)** | Crew member | Your crew directory |
| **Deacon** | Town-wide | Daemon process, agent lifecycle, plugin execution | | **Polecat** | Worker agent | Spawned by Mayor |
| **Witness** | Per-rig | Monitor polecats, nudge stuck workers | | **Hook** | Persistent storage | Git worktree |
| **Refinery** | Per-rig | Merge queue, PR review, integration | | **Convoy** | Work tracker | `gt convoy` commands |
| **Polecat** | Per-task | Execute work, file discovered issues, request shutdown |
## The Propulsion Principle ## Tips
> If your hook has work, RUN IT. - **Always start with the Mayor** - It's designed to be your primary interface
- **Use convoys for coordination** - They provide visibility across agents
- **Leverage hooks for persistence** - Your work won't disappear
- **Create formulas for repeated tasks** - Save time with Beads recipes
- **Monitor the dashboard** - Get real-time visibility
- **Let the Mayor orchestrate** - It knows how to manage agents
Agents wake up, check their hook, execute the molecule. No waiting for commands. ## Troubleshooting
Molecules survive crashes - any agent can continue where another left off.
--- ### Agents lose connection
## Optional: MEOW Deep Dive Check hooks are properly initialized:
**M**olecular **E**xpression **O**f **W**ork - the full algebra. ```bash
gt hooks list
gt hooks repair
```
### States of Matter ### Convoy stuck
| Phase | Name | Storage | Behavior | Force refresh:
|-------|------|---------|----------|
| Ice-9 | Formula | `.beads/formulas/` | Source template, composable |
| Solid | Protomolecule | `.beads/` | Frozen template, reusable |
| Liquid | Mol | `.beads/` | Flowing work, persistent |
| Vapor | Wisp | `.beads/` (ephemeral flag) | Transient, for patrols |
*(Protomolecules are an homage to The Expanse. Ice-9 is a nod to Vonnegut.)* ```bash
gt convoy refresh <convoy-id>
```
### Operators ### Mayor not responding
| Operator | From → To | Effect | Restart Mayor session:
|----------|-----------|--------|
| `cook` | Formula → Protomolecule | Expand macros, flatten |
| `pour` | Proto → Mol | Instantiate as persistent |
| `wisp` | Proto → Wisp | Instantiate as ephemeral |
| `squash` | Mol/Wisp → Digest | Condense to permanent record |
| `burn` | Wisp → ∅ | Discard without record |
--- ```bash
gt mayor detach
gt mayor attach
```
## License ## License
MIT MIT License - see LICENSE file for details
---
**Getting Started:** Run `gt install ~/gt --git && cd ~/gt && gt mayor attach` and tell the Mayor what you want to build!