gastownhall /gastown
Gas Town - multi-agent workspace manager
★ 18,805⑂ 1,701👁 105⑃ 3,536● 1,276▤ 14
+4
日增长
+122
周增长
+462
月增长
18,805
stars
1,701
forks
105
watchers
3,536
prs
1,276
issues
14
releases
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—Top issues
#4958daemon dog-patrol teardown never closes the molecule ROOT wisp: closeWisp omits --force, so bd refuses 'N open child issue(s)' and leaked roots accumulate with no cleanup path18 comments · 2026-11-07#4869gt compact is a no-op across all wisp categories while gt compact report counts tens of thousands as active10 comments · 2026-09-15#4179[Release][Brew] FAILED release of Gastown 1.2.0 and 1.2.1 to brew10 comments · 2026-06-04#2386Deacon patrol can fast-loop fake cycles without executing formula steps7 comments · 2026-03-05#2384gt unsling can leave stale wisps.hook_bead on agent wisps7 comments · 2026-03-05#1066Handle rate limit resets7 comments · 2026-01-29#4540gt agents resolve --role X --rig Y returns a town-issues bead, not rig-local; breaks await-event/await-signal, now confirmed on 6 rigs across 2 sessions6 comments · 2026-07-21#2067Proposal: deacon event-driven wake via emit-event/await-event6 comments · 2026-02-26
Discussions
#4946Gas Town: rejecting the receipt before it reaches the Refinery0 comments · 2026-10-30#4943Support for terminal multiplexers other than tmux (e.g. Herdr)?0 comments · 2026-10-26#4931Gas Town included in AgentManager's tool catalog0 comments · 2026-10-18#4896What happens when one agent breaks the combined application?0 comments · 2026-09-30#4888Mayor want's to fix gastown1 comments · 2026-09-25#4577Making Gastown cheaper (possibly free) and more deterministic via freeride proxy and configurable workflows0 comments · 2026-07-25#4435I really want to use gastown1 comments · 2026-07-08#3513Gas Town Dashboard0 comments · 2026-04-03
Latest release
v1.2.1 v1.2.1 2026-06-06Gas Town v1.2.1 Pre-compiled binaries for Linux, macOS (Intel & Apple Silicon), and Windows. Installation Homebrew (macOS/Linux): bash brew install gastown npm (Node.js): bash npm install -g @gastown/gt Manual Install: Download the appropriate binary for your platform below, extract it, and place it in your PATH. Changelog Features 59edd7151e95edae2598887b22ae0f097ca873b3 feat(daemon): per-bead cargo target clean hook (hq-x0v7v) 5e31df81f66b847774a41a6aef0672720d9a385c feat(witness): detect polecats stuck at startup without heartbeat (gt-uk7) Bug Fixes 64ad5ed95ea071e99a22eaa537