[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-4898":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},4898,"gastown","gastownhall\u002Fgastown","gastownhall","Gas Town - multi-agent workspace manager","",null,"Go",15863,1478,96,175,0,17,132,766,109,119.51,"MIT License",false,"main",[],"2026-06-12 04:00:23","# Gas Town\n\n**Multi-agent orchestration system for Claude Code, GitHub Copilot, and other AI agents with persistent work tracking**\n\n## Overview\n\nGas 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.\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\u002F>AI Coordinator]\n    Town[Town Workspace\u003Cbr\u002F>~\u002Fgt\u002F]\n\n    Town --> Mayor\n    Town --> Rig1[Rig: Project A]\n    Town --> Rig2[Rig: Project B]\n\n    Rig1 --> Crew1[Crew Member\u003Cbr\u002F>Your workspace]\n    Rig1 --> Hooks1[Hooks\u003Cbr\u002F>Persistent storage]\n    Rig1 --> Polecats1[Polecats\u003Cbr\u002F>Worker agents]\n\n    Rig2 --> Crew2[Crew Member]\n    Rig2 --> Hooks2[Hooks]\n    Rig2 --> Polecats2[Polecats]\n\n    Hooks1 -.git worktree.-> GitRepo1[Git Repository]\n    Hooks2 -.git worktree.-> 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., `~\u002Fgt\u002F`). 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. Convoys labeled `mountain` get autonomous stall detection and smart skip logic for epic-scale execution.\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### Molecules 🧬\n\nWorkflow templates that coordinate multi-step work. Formulas (TOML definitions) are instantiated as molecules with tracked steps. Two modes: root-only wisps (steps materialized at runtime, lightweight) and poured wisps (steps materialized as sub-wisps with checkpoint recovery). See [Molecules](docs\u002Fconcepts\u002Fmolecules.md).\n\n### Monitoring: Witness, Deacon, Dogs 🐕\n\nA three-tier watchdog system keeps agents healthy:\n\n- **Witness** - Per-rig lifecycle manager. Monitors polecats, detects stuck agents, triggers recovery, manages session cleanup.\n- **Deacon** - Background supervisor running continuous patrol cycles across all rigs.\n- **Dogs** - Infrastructure workers dispatched by the Deacon for maintenance tasks (e.g., Boot for triage).\n\n### Refinery 🏭\n\nPer-rig merge queue processor. When polecats complete work via `gt done`, the Refinery batches merge requests, runs verification gates, and merges to main using a Bors-style bisecting queue. Failed MRs are isolated and either fixed inline or re-dispatched.\n\n### Escalation 🚨\n\nSeverity-routed issue escalation. Agents that hit blockers escalate via `gt escalate`, which creates tracked beads routed through the Deacon, Mayor, and (if needed) Overseer. Severity levels: CRITICAL (P0), HIGH (P1), MEDIUM (P2). See [Escalation](docs\u002Fdesign\u002Fescalation.md).\n\n### Scheduler ⏱️\n\nConfig-driven capacity governor for polecat dispatch. Prevents API rate limit exhaustion by batching dispatch under configurable concurrency limits. Default is direct dispatch; set `scheduler.max_polecats` to enable deferred dispatch with the daemon. See [Scheduler](docs\u002Fdesign\u002Fscheduler.md).\n\n### Seance 👻\n\nSession discovery and continuation. Discovers previous agent sessions via `.events.jsonl` logs, enabling agents to query their predecessors for context and decisions from earlier work.\n\n```bash\ngt seance                       # List discoverable predecessor sessions\ngt seance --talk \u003Cid> -p \"What did you find?\"  # One-shot question\n```\n\n### Wasteland 🏜️\n\nFederated work coordination network linking Gas Towns through DoltHub. Rigs post wanted items, claim work from other towns, submit completion evidence, and earn portable reputation via multi-dimensional stamps. See [Wasteland](docs\u002FWASTELAND.md).\n\n> **New to Gas Town?** See the [Glossary](docs\u002Fglossary.md) for a complete guide to terminology and concepts.\n\n## Installation\n\n### Prerequisites\n\n- **Go 1.25+** - [go.dev\u002Fdl](https:\u002F\u002Fgo.dev\u002Fdl\u002F)\n- **Git 2.25+** - for worktree support\n- **Dolt 1.82.4+** - `brew install dolt` on macOS, or see [github.com\u002Fdolthub\u002Fdolt](https:\u002F\u002Fgithub.com\u002Fdolthub\u002Fdolt)\n- **beads (bd) 0.55.4+** - installed by `brew install gastown`, or see [github.com\u002Fsteveyegge\u002Fbeads](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads)\n- **sqlite3** - for convoy database queries (usually pre-installed on macOS\u002FLinux)\n- **tmux 3.0+** - recommended for full experience\n- **Claude Code CLI** (default runtime) - [claude.ai\u002Fcode](https:\u002F\u002Fclaude.ai\u002Fcode)\n- **Codex CLI** (optional runtime) - [developers.openai.com\u002Fcodex\u002Fcli](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fcli)\n- **GitHub Copilot CLI** (optional runtime) - [cli.github.com](https:\u002F\u002Fcli.github.com) (requires Copilot seat)\n\n### Setup (Docker-Compose below)\n\n```bash\n# Install Gas Town\n$ brew install gastown                                    # Homebrew (recommended)\n$ npm install -g @gastown\u002Fgt                              # npm\n$ go install github.com\u002Fsteveyegge\u002Fgastown\u002Fcmd\u002Fgt@latest  # From source (Linux only)\n\n# macOS: go install produces unsigned binaries that macOS will SIGKILL.\n# Use brew install (above) or install Dolt and clone\u002Fbuild with make:\n$ brew install dolt\n$ git clone https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fgastown.git && cd gastown\n$ make build && mv gt $HOME\u002Fgo\u002Fbin\u002F\n\n# Windows (or if go install fails): clone and build manually\n$ git clone https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fgastown.git && cd gastown\n$ go build -o gt.exe .\u002Fcmd\u002Fgt\n$ mv gt.exe $HOME\u002Fgo\u002Fbin\u002F  # or add gastown to PATH\n\n# If using go install, add Go binaries to PATH (add to ~\u002F.zshrc or ~\u002F.bashrc)\nexport PATH=\"$PATH:$HOME\u002Fgo\u002Fbin\"\n\n# Create workspace with git initialization\ngt install ~\u002Fgt --git\ncd ~\u002Fgt\n\n# Add your first project\ngt rig add myproject https:\u002F\u002Fgithub.com\u002Fyou\u002Frepo.git\n\n# Create your crew workspace\ngt crew add yourname --rig myproject\ncd myproject\u002Fcrew\u002Fyourname\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>\"\nexport GIT_EMAIL=\"\u003Cyour email>\"\nexport FOLDER=\"\u002FUsers\u002Fyou\u002Fcode\"\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 ~\u002Fgt --git &&\ncd ~\u002Fgt &&\ngt config agent list &&\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->>Mayor: Tell Mayor what to build\n    Mayor->>Convoy: Create convoy with beads\n    Mayor->>Agent: Sling bead to agent\n    Agent->>Hook: Store work state\n    Agent->>Agent: Complete work\n    Agent->>Convoy: Report completion\n    Mayor->>You: 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]) --> Tell[Tell Mayor\u003Cbr\u002F>what to build]\n    Tell --> Creates[Mayor creates\u003Cbr\u002F>convoy + agents]\n    Creates --> Monitor[Monitor progress\u003Cbr\u002F>via convoy list]\n    Monitor --> Done{All done?}\n    Done -->|No| Monitor\n    Done -->|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\u002Fformula\u002Fformulas\u002F`).\n\n**Example Formula** (`internal\u002Fformula\u002Fformulas\u002Frelease.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 .\u002Fscripts\u002Fbump-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 .\u002Fscripts\u002Fpublish.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\u002Fmy-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\u002Fconfig.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\u002Fsettings.json` (managed via `--settings` flag) for mail injection and startup.\n- For Codex, set `project_doc_fallback_filenames = [\"CLAUDE.md\"]` in\n  `~\u002F.codex\u002Fconfig.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- **GitHub Copilot** (`copilot`) is a built-in preset using `--yolo` for autonomous\n  mode. It uses executable lifecycle hooks in `.github\u002Fhooks\u002Fgastown.json` (same events\n  as Claude: `sessionStart`, `userPromptSubmitted`, `preToolUse`, `sessionEnd`). Uses a\n  5-second ready delay instead of prompt detection. Requires a Copilot seat and org-level\n  CLI policy. See [docs\u002FINSTALLING.md](docs\u002FINSTALLING.md).\n\n## Key Commands\n\n### Workspace Management\n\n```bash\ngt install \u003Cpath>           # Initialize workspace\ngt rig add \u003Cname> \u003Crepo>    # Add project\ngt rig list                 # List projects\ngt crew add \u003Cname> --rig \u003Crig>  # Create crew workspace\n```\n\n### Agent Operations\n\n```bash\ngt agents                   # List active agents\ngt sling \u003Cbead-id> \u003Crig>    # Assign work to agent\ngt sling \u003Cbead-id> \u003Crig> --agent cursor   # Override runtime for this sling\u002Fspawn\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> [issues...]   # Create convoy with issues\ngt convoy list              # List all convoys\ngt convoy show [id]         # Show convoy details\ngt convoy add \u003Cconvoy-id> \u003Cissue-id...>  # 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\n### Monitoring & Health\n\n```bash\ngt escalate -s HIGH \"description\"  # Escalate a blocker\ngt escalate list               # List open escalations\ngt scheduler status            # Show scheduler state\ngt seance                      # Discover previous sessions\ngt seance --talk \u003Cid>          # Query a predecessor session\n```\n\n### Beads Integration\n\n```bash\nbd formula list             # List formulas\nbd cook \u003Cformula>           # Execute formula\nbd mol pour \u003Cformula>       # Create trackable instance\nbd mol list                 # List active instances\n```\n\n### Wasteland Federation\n\n```bash\ngt wl join \u003Cremote>            # Join a wasteland\ngt wl browse                   # View wanted board\ngt wl claim \u003Cid>               # Claim work\ngt wl done \u003Cid> --evidence \u003Curl>  # Submit completion\n```\n\n## Cooking Formulas\n\nGas Town includes built-in formulas for common workflows. See `internal\u002Fformula\u002Fformulas\u002F` 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`\u002F`k` to scroll, `Tab` to switch panels, `1`\u002F`2`\u002F`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## Monitoring & Health\n\nGas Town uses a three-tier watchdog chain to keep agents healthy at scale:\n\n```\nDaemon (Go process) ← heartbeat every 3 min\n    └── Boot (AI agent) ← intelligent triage\n        └── Deacon (AI agent) ← continuous patrol\n            └── Witnesses & Refineries ← per-rig agents\n```\n\n### Witness (Per-Rig)\n\nEach rig has a Witness that monitors its polecats. The Witness detects stuck agents, triggers recovery (nudge or handoff), manages session cleanup, and tracks completion. Witnesses delegate work rather than implementing it directly.\n\n### Deacon (Cross-Rig)\n\nThe Deacon runs continuous patrol cycles across all rigs, checking agent health, dispatching Dogs for maintenance tasks, and escalating issues that individual Witnesses can't resolve.\n\n### Escalation\n\nWhen agents hit blockers, they escalate rather than waiting:\n\n```bash\ngt escalate -s HIGH \"Description of blocker\"\ngt escalate list                    # List open escalations\ngt escalate ack \u003Cbead-id>           # Acknowledge an escalation\n```\n\nEscalations route through Deacon -> Mayor -> Overseer based on severity. See [Escalation design](docs\u002Fdesign\u002Fescalation.md).\n\n## Merge Queue (Refinery)\n\nThe Refinery processes completed polecat work through a bisecting merge queue:\n\n1. Polecat runs `gt done` -> branch pushed, MR bead created\n2. Refinery batches pending MRs\n3. Runs verification gates on the merged stack\n4. If green: all MRs in batch merge to main\n5. If red: bisects to isolate the failing MR, merges the good ones\n\nThis is a Bors-style merge queue — polecats never push directly to main.\n\n## Scheduler\n\nThe scheduler controls polecat dispatch capacity to prevent API rate limit exhaustion:\n\n```bash\ngt config set scheduler.max_polecats 5   # Enable deferred dispatch (max 5 concurrent)\ngt scheduler status                      # Show scheduler state\ngt scheduler pause                       # Pause dispatch\ngt scheduler resume                      # Resume dispatch\n```\n\nDefault mode (`max_polecats = -1`) dispatches immediately via `gt sling`. When a limit is set, the daemon dispatches incrementally, respecting capacity. See [Scheduler design](docs\u002Fdesign\u002Fscheduler.md).\n\n## Seance\n\nDiscover and query previous agent sessions:\n\n```bash\ngt seance                              # List discoverable predecessor sessions\ngt seance --talk \u003Cid>                  # Full context conversation with predecessor\ngt seance --talk \u003Cid> -p \"Question?\"   # One-shot question to predecessor\n```\n\nSeance discovers sessions via `.events.jsonl` logs, enabling agents to recover context and decisions from earlier work without re-reading entire codebases.\n\n## Wasteland Federation\n\nThe Wasteland is a federated work coordination network linking multiple Gas Towns through DoltHub:\n\n```bash\ngt wl join hop\u002Fwl-commons              # Join a wasteland\ngt wl browse                           # View wanted board\ngt wl claim \u003Cid>                       # Claim a wanted item\ngt wl done \u003Cid> --evidence \u003Curl>       # Submit completion with evidence\ngt wl post --title \"Need X\"            # Post new wanted item\n```\n\nCompletions earn portable reputation via multi-dimensional stamps (quality, speed, complexity). See [Wasteland guide](docs\u002FWASTELAND.md).\n\n## Telemetry (OpenTelemetry)\n\nGas Town emits all agent operations as structured logs and metrics to any OTLP-compatible backend (VictoriaMetrics\u002FVictoriaLogs by default):\n\n```bash\n# Configure OTLP endpoints\nexport GT_OTEL_LOGS_URL=\"http:\u002F\u002Flocalhost:9428\u002Finsert\u002Fjsonline\"\nexport GT_OTEL_METRICS_URL=\"http:\u002F\u002Flocalhost:8428\u002Fapi\u002Fv1\u002Fwrite\"\n```\n\n**Events emitted:** session lifecycle, agent state changes, bd calls with duration, mail operations, sling\u002Fnudge\u002Fdone workflows, polecat spawn\u002Fremove, formula instantiation, convoy creation, daemon restarts, and more.\n\n**Metrics include:** `gastown.session.starts.total`, `gastown.bd.calls.total`, `gastown.polecat.spawns.total`, `gastown.done.total`, `gastown.convoy.creates.total`, and others.\n\nSee [OTEL data model](docs\u002Fotel-data-model.md) and [OTEL architecture](docs\u002Fdesign\u002Fotel\u002F) for the complete event schema.\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    [*] --> Created: Agent spawned\n    Created --> Active: Work assigned\n    Active --> Suspended: Agent paused\n    Suspended --> Active: Agent resumed\n    Active --> Completed: Work done\n    Completed --> Archived: Hook archived\n    Archived --> [*]\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 > \u002Fetc\u002Fbash_completion.d\u002Fgt\n\n# Zsh\ngt completion zsh > \"${fpath[1]}\u002F_gt\"\n\n# Fish\ngt completion fish > ~\u002F.config\u002Ffish\u002Fcompletions\u002Fgt.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| **Witness**     | Per-rig agent health monitor         | Automatic patrol     |\n| **Deacon**      | Cross-rig supervisor daemon          | `gt patrol`          |\n| **Refinery**    | Merge queue processor                | Automatic            |\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## Design Documentation\n\nFor deeper technical details, see the design docs in `docs\u002F`:\n\n| Topic | Document |\n|-------|----------|\n| Architecture | [docs\u002Fdesign\u002Farchitecture.md](docs\u002Fdesign\u002Farchitecture.md) |\n| Glossary | [docs\u002Fglossary.md](docs\u002Fglossary.md) |\n| Molecules | [docs\u002Fconcepts\u002Fmolecules.md](docs\u002Fconcepts\u002Fmolecules.md) |\n| Escalation | [docs\u002Fdesign\u002Fescalation.md](docs\u002Fdesign\u002Fescalation.md) |\n| Scheduler | [docs\u002Fdesign\u002Fscheduler.md](docs\u002Fdesign\u002Fscheduler.md) |\n| Wasteland | [docs\u002FWASTELAND.md](docs\u002FWASTELAND.md) |\n| OTEL data model | [docs\u002Fotel-data-model.md](docs\u002Fotel-data-model.md) |\n| Witness design | [docs\u002Fdesign\u002Fwitness-at-team-lead.md](docs\u002Fdesign\u002Fwitness-at-team-lead.md) |\n| Convoy lifecycle | [docs\u002Fdesign\u002Fconvoy\u002F](docs\u002Fdesign\u002Fconvoy\u002F) |\n| Polecat lifecycle | [docs\u002Fdesign\u002Fpolecat-lifecycle-patrol.md](docs\u002Fdesign\u002Fpolecat-lifecycle-patrol.md) |\n| Plugin system | [docs\u002Fdesign\u002Fplugin-system.md](docs\u002Fdesign\u002Fplugin-system.md) |\n| Agent providers | [docs\u002Fagent-provider-integration.md](docs\u002Fagent-provider-integration.md) |\n| Hooks | [docs\u002FHOOKS.md](docs\u002FHOOKS.md) |\n| Installation guide | [docs\u002FINSTALLING.md](docs\u002FINSTALLING.md) |\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>\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","Gas Town 是一个多代理工作空间管理器，旨在协调多个AI编码代理（如Claude Code、GitHub Copilot等）协同工作。其核心功能包括通过git支持的钩子持久化保存工作状态，内置邮箱、身份和交接机制，以及能够舒适地扩展到20-30个代理而不混乱。该项目采用Go语言开发，并利用Beads账本存储工作状态，确保即使代理重启也能保持上下文连贯。Gas Town适用于需要多AI代理协作完成复杂软件开发任务的场景，特别是当团队希望在不同项目间无缝切换并保持高效沟通时。",2,"2026-06-11 03:01:22","top_language"]