README

Gas Town

Multi-agent orchestration system for Claude Code, GitHub Copilot, and other AI agents with persistent work tracking

 Overview

Gas Town is a workspace manager that lets you coordinate multiple AI coding agents (Claude Code, GitHub Copilot, Codex, Gemini, and others) 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.

 What Problem Does This Solve?

| Challenge                       | Gas Town Solution                            |
| ------------------------------- | -------------------------------------------- |
| Agents lose context on restart  | Work persists in git-backed hooks            |
| Manual agent coordination       | Built-in mailboxes, identities, and handoffs |
| 4-10 agents become chaotic      | Scale comfortably to 20-30 agents            |
| Work state lost in agent memory | Work state stored in Beads ledger            |

 Architecture

mermaid
graph TB
    Mayor[The MayorAI Coordinator]
    Town[Town Workspace~/gt/]

    Town -- Mayor
    Town -- Rig1[Rig: Project A]
    Town -- Rig2[Rig: Project B]

    Rig1 -- Crew1[Crew MemberYour workspace]
    Rig1 -- Hooks1[HooksPersistent storage]
    Rig1 -- Polecats1[PolecatsWorker agents]

    Rig2 -- Crew2[Crew Member]
    Rig2 -- Hooks2[Hooks]
    Rig2 -- Polecats2[Polecats]

    Hooks1 -.git worktree.- GitRepo1[Git Repository]
    Hooks2 -.git worktree.- GitRepo2[Git Repository]

    style Mayor fill:e1f5ff,color:000000
    style Town fill:f0f0f0,color:000000
    style Rig1 fill:fff4e1,color:000000
    style Rig2 fill:fff4e1,color:000000


 Core Concepts

 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 🏘️

Your workspace directory (e.g., ~/gt/). Contains all projects, agents, and configuration.

 Rigs 🏗️

Project containers. Each rig wraps a git repository and manages its associated agents.

 Crew Members 👤

Your personal workspace within a rig. Where you do hands-on work.

 Polecats 🦨

Worker agents with persistent identity but ephemeral sessions. Spawned for tasks, sessions end on completion, but identity and work history persist.

 Hooks 🪝

Git worktree-based persistent storage for agent work. Survives crashes and restarts.

 Convoys 🚚

Work tracking units. Bundle multiple beads that get assigned to agents. Convoys labeled mountain get autonomous stall detection and smart skip logic for epic-scale execution.

 Beads Integration 📿

Git-backed issue tracking system that stores work state as structured data.

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—