{"id":36974670,"url":"https://github.com/steveyegge/gastown","last_synced_at":"2026-03-12T05:12:47.047Z","repository":{"id":332016037,"uuid":"1117184424","full_name":"steveyegge/gastown","owner":"steveyegge","description":"Gas Town - multi-agent workspace manager","archived":false,"fork":false,"pushed_at":"2026-01-12T06:56:03.000Z","size":46512,"stargazers_count":3200,"open_issues_count":77,"forks_count":260,"subscribers_count":35,"default_branch":"main","last_synced_at":"2026-01-12T06:57:40.660Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steveyegge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-16T00:33:33.000Z","updated_at":"2026-01-12T06:56:06.000Z","dependencies_parsed_at":"2026-01-12T07:05:31.679Z","dependency_job_id":null,"html_url":"https://github.com/steveyegge/gastown","commit_stats":null,"previous_names":["steveyegge/gastown"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/steveyegge/gastown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveyegge%2Fgastown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveyegge%2Fgastown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveyegge%2Fgastown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveyegge%2Fgastown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steveyegge","download_url":"https://codeload.github.com/steveyegge/gastown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveyegge%2Fgastown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-13T22:01:07.836Z","updated_at":"2026-03-12T05:12:47.040Z","avatar_url":"https://github.com/steveyegge.png","language":"Go","funding_links":[],"categories":["Multi-Agent Swarms","Go","Multi-Agent Systems","\u003ca name=\"Go\"\u003e\u003c/a\u003eGo","🗂️ Task, Memory \u0026 Workspace Management","Harnesses \u0026 orchestration"],"sub_categories":["Orchestration Platforms","Orchestrators \u0026 autonomous loops"],"readme":"# Gas Town\n\n**Multi-agent orchestration system for Claude Code with persistent work tracking**\n\n## Overview\n\nGas 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.\n\n### What Problem Does This Solve?\n\n| Challenge                       | Gas Town Solution                            |\n| ------------------------------- | -------------------------------------------- |\n| Agents lose context on restart  | Work persists in git-backed hooks            |\n| Manual agent coordination       | Built-in mailboxes, identities, and handoffs |\n| 4-10 agents become chaotic      | Scale comfortably to 20-30 agents            |\n| Work state lost in agent memory | Work state stored in Beads ledger            |\n\n### Architecture\n\n```mermaid\ngraph TB\n    Mayor[The Mayor\u003cbr/\u003eAI Coordinator]\n    Town[Town Workspace\u003cbr/\u003e~/gt/]\n\n    Town --\u003e Mayor\n    Town --\u003e Rig1[Rig: Project A]\n    Town --\u003e Rig2[Rig: Project B]\n\n    Rig1 --\u003e Crew1[Crew Member\u003cbr/\u003eYour workspace]\n    Rig1 --\u003e Hooks1[Hooks\u003cbr/\u003ePersistent storage]\n    Rig1 --\u003e Polecats1[Polecats\u003cbr/\u003eWorker agents]\n\n    Rig2 --\u003e Crew2[Crew Member]\n    Rig2 --\u003e Hooks2[Hooks]\n    Rig2 --\u003e Polecats2[Polecats]\n\n    Hooks1 -.git worktree.-\u003e GitRepo1[Git Repository]\n    Hooks2 -.git worktree.-\u003e GitRepo2[Git Repository]\n\n    style Mayor fill:#e1f5ff,color:#000000\n    style Town fill:#f0f0f0,color:#000000\n    style Rig1 fill:#fff4e1,color:#000000\n    style Rig2 fill:#fff4e1,color:#000000\n```\n\n## Core Concepts\n\n### The Mayor 🎩\n\nYour 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.\n\n### Town 🏘️\n\nYour workspace directory (e.g., `~/gt/`). Contains all projects, agents, and configuration.\n\n### Rigs 🏗️\n\nProject containers. Each rig wraps a git repository and manages its associated agents.\n\n### Crew Members 👤\n\nYour personal workspace within a rig. Where you do hands-on work.\n\n### Polecats 🦨\n\nWorker agents with persistent identity but ephemeral sessions. Spawned for tasks, sessions end on completion, but identity and work history persist.\n\n### Hooks 🪝\n\nGit worktree-based persistent storage for agent work. Survives crashes and restarts.\n\n### Convoys 🚚\n\nWork tracking units. Bundle multiple beads that get assigned to agents.\n\n### Beads Integration 📿\n\nGit-backed issue tracking system that stores work state as structured data.\n\n**Bead IDs** (also called **issue IDs**) use a prefix + 5-character alphanumeric format (e.g., `gt-abc12`, `hq-x7k2m`). The prefix indicates the item's origin or rig. Commands like `gt sling` and `gt convoy` accept these IDs to reference specific work items. The terms \"bead\" and \"issue\" are used interchangeably—beads are the underlying data format, while issues are the work items stored as beads.\n\n\u003e **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.\n\n## Installation\n\n### Prerequisites\n\n- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)\n- **Git 2.25+** - for worktree support\n- **Dolt 1.82.4+** - [github.com/dolthub/dolt](https://github.com/dolthub/dolt)\n- **beads (bd) 0.55.4+** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads)\n- **sqlite3** - for convoy database queries (usually pre-installed on macOS/Linux)\n- **tmux 3.0+** - recommended for full experience\n- **Claude Code CLI** (default runtime) - [claude.ai/code](https://claude.ai/code)\n- **Codex CLI** (optional runtime) - [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)\n\n### Setup (Docker-Compose below)\n\n```bash\n# Install Gas Town\n$ brew install gastown                                    # Homebrew (recommended)\n$ npm install -g @gastown/gt                              # npm\n$ go install github.com/steveyegge/gastown/cmd/gt@latest  # From source (macOS/Linux)\n\n# Windows (or if go install fails): clone and build manually\n$ git clone https://github.com/steveyegge/gastown.git \u0026\u0026 cd gastown\n$ go build -o gt.exe ./cmd/gt\n$ mv gt.exe $HOME/go/bin/  # or add gastown to PATH\n\n# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)\nexport PATH=\"$PATH:$HOME/go/bin\"\n\n# Create workspace with git initialization\ngt install ~/gt --git\ncd ~/gt\n\n# Add your first project\ngt rig add myproject https://github.com/you/repo.git\n\n# Create your crew workspace\ngt crew add yourname --rig myproject\ncd myproject/crew/yourname\n\n# Start the Mayor session (your main interface)\ngt mayor attach\n```\n\n### Docker Compose\n\n```bash\nexport GIT_USER=\"\u003cyour name\u003e\"\nexport GIT_EMAIL=\"\u003cyour email\u003e\"\nexport FOLDER=\"/Users/you/code\"\nexport DASHBOARD_PORT=8080  # optional, host port for the web dashboard\n\ndocker compose build              # only needed on first run or after code changes\ndocker compose up -d\n\ndocker compose exec gastown zsh   # or bash\n\ngt up\n\ngh auth login                     # if you want gh to work\n\ngt mayor attach\n```\n\n## Quick Start Guide\n\n### Getting Started\nRun\n```shell\ngt install ~/gt --git \u0026\u0026\ncd ~/gt \u0026\u0026\ngt config agent list \u0026\u0026\ngt mayor attach\n```\nand tell the Mayor what you want to build!\n\n---\n\n### Basic Workflow\n\n```mermaid\nsequenceDiagram\n    participant You\n    participant Mayor\n    participant Convoy\n    participant Agent\n    participant Hook\n\n    You-\u003e\u003eMayor: Tell Mayor what to build\n    Mayor-\u003e\u003eConvoy: Create convoy with beads\n    Mayor-\u003e\u003eAgent: Sling bead to agent\n    Agent-\u003e\u003eHook: Store work state\n    Agent-\u003e\u003eAgent: Complete work\n    Agent-\u003e\u003eConvoy: Report completion\n    Mayor-\u003e\u003eYou: Summary of progress\n```\n\n### Example: Feature Development\n\n```bash\n# 1. Start the Mayor\ngt mayor attach\n\n# 2. In Mayor session, create a convoy with bead IDs\ngt convoy create \"Feature X\" gt-abc12 gt-def34 --notify --human\n\n# 3. Assign work to an agent\ngt sling gt-abc12 myproject\n\n# 4. Track progress\ngt convoy list\n\n# 5. Monitor agents\ngt agents\n```\n\n## Common Workflows\n\n### Mayor Workflow (Recommended)\n\n**Best for:** Coordinating complex, multi-issue work\n\n```mermaid\nflowchart LR\n    Start([Start Mayor]) --\u003e Tell[Tell Mayor\u003cbr/\u003ewhat to build]\n    Tell --\u003e Creates[Mayor creates\u003cbr/\u003econvoy + agents]\n    Creates --\u003e Monitor[Monitor progress\u003cbr/\u003evia convoy list]\n    Monitor --\u003e Done{All done?}\n    Done --\u003e|No| Monitor\n    Done --\u003e|Yes| Review[Review work]\n```\n\n**Commands:**\n\n```bash\n# Attach to Mayor\ngt mayor attach\n\n# In Mayor, create convoy and let it orchestrate\ngt convoy create \"Auth System\" gt-x7k2m gt-p9n4q --notify\n\n# Track progress\ngt convoy list\n```\n\n### Minimal Mode (No Tmux)\n\nRun individual runtime instances manually. Gas Town just tracks state.\n\n```bash\ngt convoy create \"Fix bugs\" gt-abc12   # Create convoy (sling auto-creates if skipped)\ngt sling gt-abc12 myproject            # Assign to worker\nclaude --resume                        # Agent reads mail, runs work (Claude)\n# or: codex                            # Start Codex in the workspace\ngt convoy list                         # Check progress\n```\n\n### Beads Formula Workflow\n\n**Best for:** Predefined, repeatable processes\n\nFormulas are TOML-defined workflows embedded in the `gt` binary (source in `internal/formula/formulas/`).\n\n**Example Formula** (`internal/formula/formulas/release.formula.toml`):\n\n```toml\ndescription = \"Standard release process\"\nformula = \"release\"\nversion = 1\n\n[vars.version]\ndescription = \"The semantic version to release (e.g., 1.2.0)\"\nrequired = true\n\n[[steps]]\nid = \"bump-version\"\ntitle = \"Bump version\"\ndescription = \"Run ./scripts/bump-version.sh {{version}}\"\n\n[[steps]]\nid = \"run-tests\"\ntitle = \"Run tests\"\ndescription = \"Run make test\"\nneeds = [\"bump-version\"]\n\n[[steps]]\nid = \"build\"\ntitle = \"Build\"\ndescription = \"Run make build\"\nneeds = [\"run-tests\"]\n\n[[steps]]\nid = \"create-tag\"\ntitle = \"Create release tag\"\ndescription = \"Run git tag -a v{{version}} -m 'Release v{{version}}'\"\nneeds = [\"build\"]\n\n[[steps]]\nid = \"publish\"\ntitle = \"Publish\"\ndescription = \"Run ./scripts/publish.sh\"\nneeds = [\"create-tag\"]\n```\n\n**Execute:**\n\n```bash\n# List available formulas\nbd formula list\n\n# Run a formula with variables\nbd cook release --var version=1.2.0\n\n# Create formula instance for tracking\nbd mol pour release --var version=1.2.0\n```\n\n### Manual Convoy Workflow\n\n**Best for:** Direct control over work distribution\n\n```bash\n# Create convoy manually\ngt convoy create \"Bug Fixes\" --human\n\n# Add issues to existing convoy\ngt convoy add hq-cv-abc gt-m3k9p gt-w5t2x\n\n# Assign to specific agents\ngt sling gt-m3k9p myproject/my-agent\n\n# Check status\ngt convoy show\n```\n\n## Runtime Configuration\n\nGas Town supports multiple AI coding runtimes. Per-rig runtime settings are in `settings/config.json`.\n\n```json\n{\n  \"runtime\": {\n    \"provider\": \"codex\",\n    \"command\": \"codex\",\n    \"args\": [],\n    \"prompt_mode\": \"none\"\n  }\n}\n```\n\n**Notes:**\n\n- Claude uses hooks in `.claude/settings.json` (managed via `--settings` flag) for mail injection and startup.\n- For Codex, set `project_doc_fallback_filenames = [\"CLAUDE.md\"]` in\n  `~/.codex/config.toml` so role instructions are picked up.\n- For runtimes without hooks (e.g., Codex), Gas Town sends a startup fallback\n  after the session is ready: `gt prime`, optional `gt mail check --inject`\n  for autonomous roles, and `gt nudge deacon session-started`.\n\n## Key Commands\n\n### Workspace Management\n\n```bash\ngt install \u003cpath\u003e           # Initialize workspace\ngt rig add \u003cname\u003e \u003crepo\u003e    # Add project\ngt rig list                 # List projects\ngt crew add \u003cname\u003e --rig \u003crig\u003e  # Create crew workspace\n```\n\n### Agent Operations\n\n```bash\ngt agents                   # List active agents\ngt sling \u003cbead-id\u003e \u003crig\u003e    # Assign work to agent\ngt sling \u003cbead-id\u003e \u003crig\u003e --agent cursor   # Override runtime for this sling/spawn\ngt mayor attach             # Start Mayor session\ngt mayor start --agent auggie           # Run Mayor with a specific agent alias\ngt prime                    # Context recovery (run inside existing session)\ngt feed                     # Real-time activity feed (TUI)\ngt feed --problems          # Start in problems view (stuck agent detection)\n```\n\n**Built-in agent presets**: `claude`, `gemini`, `codex`, `cursor`, `auggie`, `amp`, `opencode`, `copilot`, `pi`, `omp`\n\n### Convoy (Work Tracking)\n\n```bash\ngt convoy create \u003cname\u003e [issues...]   # Create convoy with issues\ngt convoy list              # List all convoys\ngt convoy show [id]         # Show convoy details\ngt convoy add \u003cconvoy-id\u003e \u003cissue-id...\u003e  # Add issues to convoy\n```\n\n### Configuration\n\n```bash\n# Set custom agent command\ngt config agent set claude-glm \"claude-glm --model glm-4\"\ngt config agent set codex-low \"codex --thinking low\"\n\n# Set default agent\ngt config default-agent claude-glm\n\n# View config\ngt config show\n```\n\n### Beads Integration\n\n```bash\nbd formula list             # List formulas\nbd cook \u003cformula\u003e           # Execute formula\nbd mol pour \u003cformula\u003e       # Create trackable instance\nbd mol list                 # List active instances\n```\n\n## Cooking Formulas\n\nGas Town includes built-in formulas for common workflows. See `internal/formula/formulas/` for available recipes.\n\n## Activity Feed\n\n`gt feed` launches an interactive terminal dashboard for monitoring all agent activity in real-time. It combines beads activity, agent events, and merge queue updates into a three-panel TUI:\n\n- **Agent Tree** - Hierarchical view of all agents grouped by rig and role\n- **Convoy Panel** - In-progress and recently-landed convoys\n- **Event Stream** - Chronological feed of creates, completions, slings, nudges, and more\n\n```bash\ngt feed                      # Launch TUI dashboard\ngt feed --problems           # Start in problems view\ngt feed --plain              # Plain text output (no TUI)\ngt feed --window             # Open in dedicated tmux window\ngt feed --since 1h           # Events from last hour\n```\n\n**Navigation:** `j`/`k` to scroll, `Tab` to switch panels, `1`/`2`/`3` to jump to a panel, `?` for help, `q` to quit.\n\n### Problems View\n\nAt scale (20-50+ agents), spotting stuck agents in the activity stream becomes difficult. The problems view surfaces agents needing human intervention by analyzing structured beads data.\n\nPress `p` in `gt feed` (or start with `gt feed --problems`) to toggle the problems view, which groups agents by health state:\n\n| State | Condition |\n|-------|-----------|\n| **GUPP Violation** | Hooked work with no progress for an extended period |\n| **Stalled** | Hooked work with reduced progress |\n| **Zombie** | Dead tmux session |\n| **Working** | Active, progressing normally |\n| **Idle** | No hooked work |\n\n**Intervention keys** (in problems view): `n` to nudge the selected agent, `h` to handoff (refresh context).\n\n## Dashboard\n\nGas Town includes a web dashboard for monitoring your workspace. The dashboard\nmust be run from inside a Gas Town workspace (HQ) directory.\n\n```bash\n# Start dashboard (default port 8080)\ngt dashboard\n\n# Start on a custom port\ngt dashboard --port 3000\n\n# Start and automatically open in browser\ngt dashboard --open\n```\n\nThe dashboard gives you a single-page overview of everything happening in your\nworkspace: agents, convoys, hooks, queues, issues, and escalations. It\nauto-refreshes via htmx and includes a command palette for running gt commands\ndirectly from the browser.\n\n## Advanced Concepts\n\n### The Propulsion Principle\n\nGas Town uses git hooks as a propulsion mechanism. Each hook is a git worktree with:\n\n1. **Persistent state** - Work survives agent restarts\n2. **Version control** - All changes tracked in git\n3. **Rollback capability** - Revert to any previous state\n4. **Multi-agent coordination** - Shared through git\n\n### Hook Lifecycle\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e Created: Agent spawned\n    Created --\u003e Active: Work assigned\n    Active --\u003e Suspended: Agent paused\n    Suspended --\u003e Active: Agent resumed\n    Active --\u003e Completed: Work done\n    Completed --\u003e Archived: Hook archived\n    Archived --\u003e [*]\n```\n\n### MEOW (Mayor-Enhanced Orchestration Workflow)\n\nMEOW is the recommended pattern:\n\n1. **Tell the Mayor** - Describe what you want\n2. **Mayor analyzes** - Breaks down into tasks\n3. **Convoy creation** - Mayor creates convoy with beads\n4. **Agent spawning** - Mayor spawns appropriate agents\n5. **Work distribution** - Beads slung to agents via hooks\n6. **Progress monitoring** - Track through convoy status\n7. **Completion** - Mayor summarizes results\n\n## Shell Completions\n\n```bash\n# Bash\ngt completion bash \u003e /etc/bash_completion.d/gt\n\n# Zsh\ngt completion zsh \u003e \"${fpath[1]}/_gt\"\n\n# Fish\ngt completion fish \u003e ~/.config/fish/completions/gt.fish\n```\n\n## Project Roles\n\n| Role            | Description        | Primary Interface    |\n| --------------- | ------------------ | -------------------- |\n| **Mayor**       | AI coordinator     | `gt mayor attach`    |\n| **Human (You)** | Crew member        | Your crew directory  |\n| **Polecat**     | Worker agent       | Spawned by Mayor     |\n| **Hook**        | Persistent storage | Git worktree         |\n| **Convoy**      | Work tracker       | `gt convoy` commands |\n\n## Tips\n\n- **Always start with the Mayor** - It's designed to be your primary interface\n- **Use convoys for coordination** - They provide visibility across agents\n- **Leverage hooks for persistence** - Your work won't disappear\n- **Create formulas for repeated tasks** - Save time with Beads recipes\n- **Use `gt feed` for live monitoring** - Watch agent activity and catch stuck agents early\n- **Monitor the dashboard** - Get real-time visibility in the browser\n- **Let the Mayor orchestrate** - It knows how to manage agents\n\n## Troubleshooting\n\n### Agents lose connection\n\nCheck hooks are properly initialized:\n\n```bash\ngt hooks list\ngt hooks repair\n```\n\n### Convoy stuck\n\nForce refresh:\n\n```bash\ngt convoy refresh \u003cconvoy-id\u003e\n```\n\n### Mayor not responding\n\nRestart Mayor session:\n\n```bash\ngt mayor detach\ngt mayor attach\n```\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveyegge%2Fgastown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteveyegge%2Fgastown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveyegge%2Fgastown/lists"}