gastownhall /gastown

Gas Town - multi-agent workspace manager

★ 18,805⑂ 1,701👁 105⑃ 3,536● 1,276▤ 14
GoMITCreated 2025-12-16
下载:v1.2.1v1.2.1 ↓1.2.12026-06-06
+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

Discussions

Latest release

v1.2.1 v1.2.1 2026-06-06
Gas 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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON