gastown

多智能体协调工作空间管理器，专为管理 Claude Code、GitHub Copilot 等多个 AI 编码代理设计。通过 git worktree 持久化代理工作状态，解决重启后上下文丢失的痛点，支持 20-30 个代理规模。内置 Mayor 协调器、convoy 工作跟踪、refinery 合并队列等机制，类似一个轻量级的 agent 编排系统。亮点在于利用 git 存储实现持久化和版本控制，并支持多运行时（Claude、Codex、Copilot 等）。适合需要大规模并行使用 AI 编码助手的团队。

README

Gas Town

用于 Claude Code、GitHub Copilot 和其他 AI agents 的多 agent 编排系统，具有持久化工作跟踪

概述

Gas Town 是一个工作区管理器，让你可以协调多个 AI 编码 agents（Claude Code、GitHub Copilot、Codex、Gemini 等）处理不同任务。不再因 agents 重启而丢失上下文，Gas Town 将工作状态持久化在 git 托管的 hooks 中，实现可靠的多 agent 工作流。

它解决了什么问题？

挑战	Gas Town 解决方案
Agents 重启后丢失上下文	工作在 git 托管的 hooks 中持久化
手动协调 agents	内置 mailboxes、identities 和 handoffs
4-10 个 agents 变得混乱	轻松扩展到 20-30 个 agents
工作状态丢失在 agent memory 中	工作状态存储在 Beads 账本中

架构

graph TB
    Mayor[The Mayor<br/>AI Coordinator]
    Town[Town Workspace<br/>~/gt/]

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

    Rig1 --> Crew1[Crew Member<br/>Your workspace]
    Rig1 --> Hooks1[Hooks<br/>Persistent storage]
    Rig1 --> Polecats1[Polecats<br/>Worker 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

核心概念

The Mayor 🎩

你的主要 AI 协调器。Mayor 是一个 Claude Code 实例，拥有关于你的工作区、项目和 agents 的完整上下文。从这里开始——只需告诉 Mayor 你想完成什么。

Town 🏘️

你的工作区目录（例如 ~/gt/）。包含所有项目、agents 和配置。

Rigs 🏗️

项目容器。每个 rig 包裹一个 git 仓库并管理其关联的 agents。

Crew Members 👤

你在 rig 内的个人工作区。在这里进行实操工作。

Polecats 🦨

具有持久化身份但会话短暂的 worker agents。为任务而生成，完成后会话结束，但身份和工作历史持久存在。

Hooks 🪝

基于 git worktree 的持久化存储，用于 agent 工作。能存活于崩溃和重启。

Convoys 🚚

工作跟踪单元。将多个 beads 打包并分配给 agents。标记为 mountain 的 Convoys 会获得自主停滞检测和智能跳过逻辑，用于史诗级执行。

Beads Integration 📿

基于 git 的问题跟踪系统，将工作状态存储为结构化数据。

Bead IDs（也称为 issue IDs）使用前缀 + 5 字符字母数字格式（例如 gt-abc12，hq-x7k2m）。前缀表示条目的来源或 rig。像 gt sling 和 gt convoy 这样的命令接受这些 ID 来引用特定工作项。术语 "bead" 和 "issue" 可互换使用——beads 是底层数据格式，issues 是存储为 beads 的工作项。

Molecules 🧬

协调多步骤工作的工作流模板。公式（TOML 定义）被实例化为带有跟踪步骤的 molecules。两种模式：仅根节点的 wisps（步骤在运行时物化，轻量）和倾倒的 wisps（步骤物化为子 wisps，支持检查点恢复）。详见 Molecules。

监控：Witness, Deacon, Dogs 🐕

三级看门狗系统保持 agents 健康：

Witness - 每个 rig 的生命周期管理器。监控 polecats，检测卡住的 agents，触发恢复，管理会话清理。
Deacon - 后台主管，在所有 rig 上运行持续巡逻周期。
Dogs - 由 Deacon 分发用于维护任务的基础设施 worker（例如用于分诊的 Boot）。

Refinery 🏭

每个 rig 的合并队列处理器。当 polecats 通过 gt done 完成工作时，Refinery 批量组织合并请求，运行验证门，并使用 Bors 风格的对分队列合并到 main。失败的 MR 被隔离，要么内联修复，要么重新分发。

升级 🚨

按严重程度路由的问题升级。遇到障碍的 agents 通过 gt escalate 升级，创建跟踪 beads，通过 Deacon、Mayor 以及（如果需要）Overseer 路由。严重性级别：CRITICAL (P0)、HIGH (P1)、MEDIUM (P2)。详见 Escalation。

Scheduler ⏱️

基于配置的容量管理，用于 polecat 分发。通过将分发批处理在可配置的并发限制下，防止 API 速率限制耗尽。默认为直接分发；设置 scheduler.max_polecats 可启用带守护进程的延迟分发。详见 Scheduler。

Seance 👻

会话发现和延续。通过 .events.jsonl 日志发现之前的 agent 会话，使 agents 能够查询前驱的上下文和决策。

gt seance                       # 列出可发现的前驱会话
gt seance --talk <id> -p "What did you find?"  # 一次性提问

Wasteland 🏜️

通过 DoltHub 连接多个 Gas Town 的联邦工作协调网络。Rigs 发布 wanted 项，从其他 town 认领工作，提交完成证据，并通过多维印章获得可移植声誉。详见 Wasteland。

Gas Town 新手？ 请参阅 Glossary 了解完整的术语和概念指南。

安装

前提条件

Go 1.25+ - go.dev/dl
Git 2.25+ - 用于 worktree 支持
Dolt 2.0.7+ - macOS 上使用 brew install dolt，或见 github.com/dolthub/dolt
beads (bd) 0.55.4+ - 由 brew install gastown 安装，或见 github.com/steveyegge/beads
sqlite3 - 用于 convoy 数据库查询（通常 macOS/Linux 已预装）
tmux 3.0+ - 推荐用于完整体验
Claude Code CLI（默认运行时） - claude.ai/code
Codex CLI（可选运行时） - developers.openai.com/codex/cli
GitHub Copilot CLI（可选运行时） - cli.github.com（需要 Copilot 席位）

设置（下方 Docker Compose）

# 安装 Gas Town
$ brew install gastown                                    # Homebrew（推荐）
$ npm install -g @gastown/gt                              # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest  # 从源码安装（仅 Linux）

# macOS：go install 会产生未签名的二进制文件，macOS 会 SIGKILL。
# 使用上方的 brew install，或安装 Dolt 并用 make 克隆和构建：
$ brew install dolt
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ make build && mv gt $HOME/go/bin/

# Windows（或 go install 失败时）：手动克隆和构建
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ go build -o gt.exe ./cmd/gt
$ mv gt.exe $HOME/go/bin/  # 或将 gastown 添加到 PATH

# 如果使用 go install，将 Go 二进制目录添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$PATH:$HOME/go/bin"

# 创建工作区并初始化 git
gt install ~/gt --git
cd ~/gt

# 添加你的第一个项目
gt rig add myproject https://github.com/you/repo.git

# 创建你的 crew 工作区
gt crew add yourname --rig myproject
cd myproject/crew/yourname

# 启动 Mayor 会话（你的主要界面）
gt mayor attach

Docker Compose

export GIT_USER="<your name>"
export GIT_EMAIL="<your email>"
export FOLDER="/Users/you/code"
export DASHBOARD_PORT=8080  # 可选，web 仪表板的主机端口

docker compose build              # 仅在首次运行或代码更改后需要
docker compose up -d

docker compose exec gastown zsh   # 或 bash

gt up

gh auth login                     # 如果你希望 gh 工作

gt mayor attach

快速入门指南

开始入门

运行

gt install ~/gt --git &&
cd ~/gt &&
gt config agent list &&
gt mayor attach

并告诉 Mayor 你想构建什么！

基本工作流

sequenceDiagram
    participant You
    participant Mayor
    participant Convoy
    participant Agent
    participant Hook

    You->>Mayor: 告诉 Mayor 要构建什么
    Mayor->>Convoy: 创建包含 beads 的 convoy
    Mayor->>Agent: 将 bead sling 给 agent
    Agent->>Hook: 存储工作状态
    Agent->>Agent: 完成工作
    Agent->>Convoy: 报告完成
    Mayor->>You: 进度摘要

示例：功能开发

# 1. 启动 Mayor
gt mayor attach

# 2. 在 Mayor 会话中，创建带有 bead ID 的 convoy
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

# 3. 将工作分配给 agent
gt sling gt-abc12 myproject

# 4. 跟踪进度
gt convoy list

# 5. 监控 agents
gt agents

常见工作流

Mayor 工作流（推荐）

最佳用于： 协调复杂的多问题工作

flowchart LR
    Start([启动 Mayor]) --> Tell[告诉 Mayor<br/>要构建什么]
    Tell --> Creates[Mayor 创建<br/>convoy + agents]
    Creates --> Monitor[监控进度<br/>通过 convoy list]
    Monitor --> Done{全部完成？}
    Done -->|否| Monitor
    Done -->|是| Review[审查工作]

命令：

# 附加到 Mayor
gt mayor attach

# 在 Mayor 中，创建 convoy 并让它编排
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify

# 跟踪进度
gt convoy list

最小模式（无 Tmux）

手动运行各个运行时实例。Gas Town 只跟踪状态。

gt convoy create "Fix bugs" gt-abc12   # 创建 convoy（如果跳过，sling 会自动创建）
gt sling gt-abc12 myproject            # 分配给 worker
claude --resume                        # Agent 读取邮件，运行工作（Claude）
# 或：codex                            # 在工作区中启动 Codex
gt convoy list                         # 检查进度

Beads Formula 工作流

最佳用于： 预定义、可重复的过程

Formulas 是嵌入在 gt 二进制中的 TOML 定义的工作流（源码在 internal/formula/formulas/）。

示例 Formula (internal/formula/formulas/release.formula.toml)：

description = "Standard release process"
formula = "release"
version = 1

[vars.version]
description = "The semantic version to release (e.g., 1.2.0)"
required = true

[[steps]]
id = "bump-version"
title = "Bump version"
description = "Run ./scripts/bump-version.sh {{version}}"

[[steps]]
id = "run-tests"
title = "Run tests"
description = "Run make test"
needs = ["bump-version"]

[[steps]]
id = "build"
title = "Build"
description = "Run make build"
needs = ["run-tests"]

[[steps]]
id = "create-tag"
title = "Create release tag"
description = "Run git tag -a v{{version}} -m 'Release v{{version}}'"
needs = ["build"]

[[steps]]
id = "publish"
title = "Publish"
description = "Run ./scripts/publish.sh"
needs = ["create-tag"]

执行：

# 列出可用 formulas
bd formula list

# 使用变量运行 formula
bd cook release --var version=1.2.0

# 创建用于跟踪的 formula 实例
bd mol pour release --var version=1.2.0

手动 Convoy 工作流

最佳用于： 直接控制工作分配

# 手动创建 convoy
gt convoy create "Bug Fixes" --human

# 将 issue 添加到现有 convoy
gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x

# 分配给特定 agents
gt sling gt-m3k9p myproject/my-agent

# 检查状态
gt convoy show

运行时配置

Gas Town 支持多个 AI 编码运行时。每个 rig 的运行时设置位于 settings/config.json。

{
  "runtime": {
    "provider": "codex",
    "command": "codex",
    "args": [],
    "prompt_mode": "none"
  }
}

备注：

Claude 使用 .claude/settings.json 中的 hooks（通过 --settings 标志管理）进行邮件注入和启动。
对于 Codex，在 ~/.codex/config.toml 中设置 project_doc_fallback_filenames = ["CLAUDE.md"]，以便拾取角色指令。
对于没有 hooks 的运行时（例如 Codex），Gas Town 会在会话准备就绪后发送启动回退：gt prime，可选 gt mail check --inject（用于自主角色），以及 gt nudge deacon session-started。
GitHub Copilot (copilot) 是内置预设，使用 --yolo 实现自主模式。它使用 .github/hooks/gastown.json 中的可执行生命周期 hooks（与 Claude 相同的事件：sessionStart、userPromptSubmitted、preToolUse、sessionEnd）。使用 5 秒就绪延迟代替提示检测。需要 Copilot 席位和组织级 CLI 策略。参见 docs/INSTALLING.md。

关键命令

工作区管理

gt install <path>           # 初始化工作区
gt rig add <name> <repo>    # 添加项目
gt rig list                 # 列出项目
gt crew add <name> --rig <rig>  # 创建 crew 工作区

Agent 操作

gt agents                   # 列出活动 agents
gt sling <bead-id> <rig>    # 将工作分配给 agent
gt sling <bead-id> <rig> --agent cursor   # 为此 sling/spawn 覆盖运行时
gt mayor attach             # 启动 Mayor 会话
gt mayor start --agent auggie           # 使用特定 agent 别名运行 Mayor
gt prime                    # 上下文恢复（在现有会话内运行）
gt feed                     # 实时活动流（TUI）
gt feed --problems          # 以问题视图启动（卡住 agent 检测）

内置 agent 预设：claude、gemini、codex、cursor、auggie、amp、opencode、copilot、pi、omp

Convoy（工作跟踪）

gt convoy create <name> [issues...]   # 使用 issues 创建 convoy
gt convoy list              # 列出所有 convoys
gt convoy show [id]         # 显示 convoy 详情
gt convoy add <convoy-id> <issue-id...>  # 向 convoy 添加 issues

配置

# 设置自定义 agent 命令
gt config agent set claude-glm "claude-glm --model glm-4"
gt config agent set codex-low "codex --thinking low"

# 设置默认 agent
gt config default-agent claude-glm

监控与健康

gt escalate -s HIGH "description"  # 升级一个阻塞项
gt escalate list               # 列出开放的升级
gt scheduler status            # 显示调度器状态
gt seance                      # 发现之前的会话
gt seance --talk <id>          # 查询前驱会话

Beads 集成

bd formula list             # 列出 formulas
bd cook <formula>           # 执行 formula
bd mol pour <formula>       # 创建可跟踪实例
bd mol list                 # 列出活动实例

Wasteland 联邦

gt wl join <remote>            # 加入一个 wasteland
gt wl browse                   # 查看需求板
gt wl claim <id>               # 认领工作
gt wl done <id> --evidence <url>  # 提交完成

烹饪 Formulas

Gas Town 包含常见工作流的内置 formulas。参见 internal/formula/formulas/ 获取可用配方。

活动流

gt feed 启动一个交互式终端仪表板，实时监控所有 agent 活动。它将 beads 活动、agent 事件和合并队列更新组合成三面板 TUI：

Agent Tree - 按 rig 和角色分组的所有 agents 的层次视图
Convoy Panel - 进行中及最近完成的 convoys
Event Stream - 创建、完成、sling、nudge 等事件的时间顺序流

gt feed                      # 启动 TUI 仪表板
gt feed --problems           # 以问题视图启动
gt feed --plain              # 纯文本输出（无 TUI）
gt feed --window             # 在专用 tmux 窗口中打开
gt feed --since 1h           # 过去一小时的事件

导航： j/k 滚动，Tab 切换面板，1/2/3 跳转到面板，? 帮助，q 退出。

问题视图

在规模较大时（20-50+ agents），在活动流中定位卡住的 agents 变得困难。问题视图通过分析结构化 beads 数据，显示需要人工干预的 agents。

在 gt feed 中按 p（或使用 gt feed --problems 启动）切换问题视图，按健康状态分组 agents：

状态	条件
GUPP 违规	长时间无进展的 hooked 工作
停滞	进展缓慢的 hooked 工作
僵尸	死亡的 tmux 会话
工作中	活动，正常进展
空闲	无 hooked 工作

干预键（在问题视图中）：n 轻推选中 agent，h 移交（刷新上下文）。

仪表板

Gas Town 包含一个 Web 仪表板，用于监控你的工作区。仪表板必须从 Gas Town 工作区（HQ）目录内运行。

# 启动仪表板（默认端口 8080）
gt dashboard

# 在自定义端口上启动
gt dashboard --port 3000

# 启动并自动在浏览器中打开
gt dashboard --open

仪表板提供单个页面概览，显示工作区中所有内容：agents、convoys、hooks、队列、issues 和升级。它通过 htmx 自动刷新，并包含命令面板，可直接从浏览器运行 gt 命令。

监控与健康

Gas Town 使用三级看门狗链在规模下保持 agents 健康：

Daemon (Go 进程) ← 每 3 分钟心跳
    └── Boot (AI agent) ← 智能分诊
        └── Deacon (AI agent) ← 持续巡逻
            └── Witnesses & Refineries ← 每个 rig 的 agents

Witness（每个 Rig）

每个 rig 都有一个 Witness 监控其 polecats。Witness 检测卡住的 agents，触发恢复（nudge 或 handoff），管理会话清理，并跟踪完成。Witnesses 委派工作而不是直接实现。

Deacon（跨 Rig）

Deacon 在所有 rig 上运行持续巡逻周期，检查 agent 健康，为维护任务分派 Dogs，并升级单个 Witnesses 无法解决的问题。

升级

当 agents 遇到阻塞时，它们升级而不是等待：

gt escalate -s HIGH "Description of blocker"
gt escalate list                    # 列出开放的升级
gt escalate ack <bead-id>           # 确认一个升级

升级根据严重性从 Deacon -> Mayor -> Overseer 路由。参见 Escalation design。

合并队列（Refinery）

Refinery 通过对分合并队列处理已完成的 polecat 工作：

Polecat 运行 gt done -> 分支推送，创建 MR bead
Refinery 批量处理待处理的 MRs
对合并后的堆栈运行验证门
如果通过：批次中的所有 MRs 合并到 main
如果失败：二分查找找出失败的 MR，合并正确的 MRs

这是 Bors 风格的合并队列——polecats 永远不会直接推送到 main。

Scheduler

Scheduler 控制 polecat 分发容量以防止 API 速率限制耗尽：

gt config set scheduler.max_polecats 5   # 启用延迟分发（最多 5 个并发）
gt scheduler status                      # 显示调度器状态
gt scheduler pause                       # 暂停分发
gt scheduler resume                      # 恢复分发

默认模式（max_polecats = -1）通过 gt sling 立即分发。设置限制后，守护进程逐步分发，尊重容量。参见 Scheduler design。

Seance

发现并查询之前的 agent 会话：

gt seance                              # 列出可发现的前驱会话
gt seance --talk <id>                  # 与前驱进行全上下文对话
gt seance --talk <id> -p "Question?"   # 向前驱一次性提问

Seance 通过 .events.jsonl 日志发现会话，使 agents 无需重新阅读整个代码库即可恢复上下文和决策。

Wasteland 联邦

Wasteland 是一个联邦工作协调网络，通过 DoltHub 连接多个 Gas Town：

gt wl join hop/wl-commons              # 加入一个 wasteland
gt wl browse                           # 查看需求板
gt wl claim <id>                       # 认领一个 wanted 项
gt wl done <id> --evidence <url>       # 提交完成并附上证据
gt wl post --title "Need X"            # 发布新的 wanted 项

完成通过多维印章（质量、速度、复杂性）获得可移植声誉。参见 Wasteland guide。

遥测（OpenTelemetry）

Gas Town 将所有 agent 操作作为结构化日志和指标发送到任何兼容 OTLP 的后端（默认 VictoriaMetrics/VictoriaLogs）：

# 配置 OTLP 端点
export GT_OTEL_LOGS_URL="http://localhost:9428/insert/jsonline"
export GT_OTEL_METRICS_URL="http://localhost:8428/api/v1/write"

发出的事件： 会话生命周期、agent 状态变化、带持续时间的 bd 调用、邮件操作、sling/nudge/done 工作流、polecat 生成/移除、formula 实例化、convoy 创建、守护进程重启等。

指标包括： gastown.session.starts.total、gastown.bd.calls.total、`gastown

开源项目gastownhall2026-07-05原文

打开互动版

gastown

README

Gas Town

概述

它解决了什么问题？

架构

核心概念

The Mayor 🎩

Town 🏘️

Rigs 🏗️

Crew Members 👤

Polecats 🦨

Hooks 🪝

Convoys 🚚

Beads Integration 📿

Molecules 🧬

监控：Witness, Deacon, Dogs 🐕

Refinery 🏭

升级 🚨

Scheduler ⏱️

Seance 👻

Wasteland 🏜️

安装

前提条件

设置（下方 Docker Compose）

Docker Compose

快速入门指南

开始入门

基本工作流

示例：功能开发

常见工作流

Mayor 工作流（推荐）

最小模式（无 Tmux）

Beads Formula 工作流

手动 Convoy 工作流

运行时配置

关键命令

工作区管理

Agent 操作

Convoy（工作跟踪）

配置

监控与健康

Beads 集成

Wasteland 联邦

烹饪 Formulas

活动流

问题视图

仪表板

监控与健康

Witness（每个 Rig）

Deacon（跨 Rig）

升级

合并队列（Refinery）

Scheduler

Seance

Wasteland 联邦

遥测（OpenTelemetry）

相关内容

warp

sim

superpowers

skills

skills