为Claude Code、GitHub Copilot及其他AI代理设计的多代理编排系统，具备持久化工作追踪

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

它解决了什么问题？

挑战	Gas Town 解决方案
代理重启后丢失上下文	工作持久化在git支持的hooks中
手动协调代理	内置邮箱、身份与交接机制
4-10个代理变得混乱	可轻松扩展至20-30个代理
工作状态仅存于代理内存	工作状态存储于Beads账本

mermaid graph TB Mayor[市长\nAI协调器] Town[镇工作区\n~/gt/]

Town --> Mayor
Town --> Rig1[钻井平台: 项目 A]
Town --> Rig2[钻井平台: 项目 B]

Rig1 --> Crew1[成员\n你的工作区]
Rig1 --> Hooks1[Hooks\n持久化存储]
Rig1 --> Polecats1[北极猫\n工作代理]

Rig2 --> Crew2[成员]
Rig2 --> Hooks2[Hooks]
Rig2 --> Polecats2[北极猫]

Hooks1 -.git worktree.-> GitRepo1[Git仓库]
Hooks2 -.git worktree.-> GitRepo2[Git仓库]

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

加载中

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

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

项目容器。每个钻井平台包装一个git仓库，并管理其关联的代理。

你在钻井平台内的个人工作区。进行手动工作的地方。

具有持久身份但会话临时的工人代理。为任务生成，会话在完成后结束，但身份和工作历史持久保留。

基于Git worktree的代理工作持久化存储。能够从崩溃和重启中幸存。

工作追踪单元。将多个珠子打包，分配给代理。标记为 mountain 的车队具有自主停滞检测和智能跳过逻辑，可执行规模级史诗任务。

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

珠子ID（也称作问题ID）使用前缀+5位字母数字格式（如 gt-abc12、hq-x7k2m）。前缀表示物品的来源或平台。命令如 gt sling 和 gt convoy 接受这些ID以引用具体工作项。“珠子”和“问题”这两个术语可以互换——珠子是底层数据格式，问题是存储为珠子的工作项。

协调多步工作的工作流模板。公式（TOML定义）被实例化为具有追踪步骤的分子。两种模式：仅根结点的微灵（步骤在运行时物化，轻量）和倒出的微灵（步骤物化为子微灵，具有检查点恢复）。参见 Molecules。

监控：见证者、执事、狗 🐕

三层看门狗系统保持代理健康：

• 见证者 - 每个钻井平台的生命周期管理器。监控北极猫，发现卡住的代理，触发恢复，管理会话清理。
• 执事 - 后台主管，在所有平台上运行连续巡逻周期。
• 狗 - 由执事分派的基础设施工作犬，执行维护任务（例如启动用于分诊）。

每个钻井平台的合并队列处理器。当北极猫通过 gt done 完成工作时，精炼厂批量合并请求，运行验证门，并使用Bors风格的对分队列合并到主线。失败的MR被隔离，或被就地修复，或重新分派。

按严重性路由的问题升级。遇到阻碍的代理通过 gt escalate 升级，这创建追踪珠子，经由执事、市长以及（必要时）监督者路由。严重级别：CRITICAL (P0)、HIGH (P1)、MEDIUM (P2)。参见 升级。

配置驱动的容量调节器，用于北极猫分派。通过在可配置的并发限制下批量分派，防止API速率限制耗尽。默认是直接分派；设置 scheduler.max_polecats 以启用守护进程的延迟分派。参见 调度器。

会话发现与延续。通过 .events.jsonl 日志发现先前的代理会话，使代理能够查询其前辈，获取早期工作的上下文和决策。

gt seance # 列出可发现的前任会话 gt seance --talk -p "你找到了什么？" # 一次性提问

通过DoltHub连接各个城镇的联邦工作协调网络。钻井平台发布所需项，从其他城镇认领工作，提交完成证据，并通过多维度印章获得可移植的声誉。参见 Wasteland。

新来Gas Town？ 完整术语和概念指南请见 词汇表。

设置（下方有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 并克隆/构建：

$ 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

创建你的成员工作区

gt crew add yourname --rig myproject cd myproject/crew/yourname

启动市长会话（主接口）

gt mayor attach

Docker-Compose

export GIT_USER="<你的名字>" export GIT_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

然后告诉市长你想构建什么！

---

mermaid sequenceDiagram participant 你 participant 市长 participant 车队 participant 代理 participant Hook

你->>市长: 告诉市长要构建什么
市长->>车队: 创建带珠子的车队
市长->>代理: 把珠子分派给代理
代理->>Hook: 存储工作状态
代理->>代理: 完成工作
代理->>车队: 报告完成
市长->>你: 进度摘要

加载中

示例：功能开发

1. 启动市长

gt mayor attach

2. 在市长会话中，创建带珠子ID的车队

gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

3. 分配工作给代理

gt sling gt-abc12 myproject

4. 追踪进度

gt convoy list

5. 监控代理

gt agents

市长工作流（推荐）

最适合： 协调复杂、多问题的工作

mermaid flowchart LR Start([启动市长]) --> Tell[告诉市长\n要构建什么] Tell --> Creates[市长创建\n车队 + 代理] Creates --> Monitor[通过 convoy list 监控进度] Monitor --> Done{全部完成？} Done -->|否| Monitor Done -->|是| Review[审查工作]

加载中

命令：

接入市长

gt mayor attach

在市长中，创建车队并让其编排

gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify

追踪进度

gt convoy list

手动工作流

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

gt convoy create "Fix bugs" gt-abc12 # 创建车队（若跳过则自动创建） gt sling gt-abc12 myproject # 分派给工作者 claude --resume # 代理读取邮件，运行工作（Claude）

或：codex # 在工作区启动Codex

gt convoy list # 检查进度

配方工作流

最适合： 预定义、可重复的流程

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

配方示例（internal/formula/formulas/release.formula.toml）：

toml description = "标准发布流程" formula = "release" version = 1

[vars.version] description = "要发布的语义版本（例如 1.2.0）" required = true

[[steps]] id = "bump-version" title = "提升版本" description = "运行 ./scripts/bump-version.sh {{version}}"

[[steps]] id = "run-tests" title = "运行测试" description = "运行 make test" needs = ["bump-version"]

[[steps]] id = "build" title = "构建" description = "运行 make build" needs = ["run-tests"]

[[steps]] id = "create-tag" title = "创建发布标签" description = "运行 git tag -a v{{version}} -m 'Release v{{version}}'" needs = ["build"]

[[steps]] id = "publish" title = "发布" description = "运行 ./scripts/publish.sh" needs = ["create-tag"]

执行：

列出可用配方

bd formula list

使用变量运行配方

bd cook release --var version=1.2.0

创建追踪用的配方实例

bd mol pour release --var version=1.2.0

熟练用户工作流

最适合： 直接控制工作分配

手动创建车队

gt convoy create "Bug Fixes" --human

向现有车队添加问题

gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x

分配给特定代理

gt sling gt-m3k9p myproject/my-agent

检查状态

gt convoy show

代理运行时（Claude、Codex、Copilot等）

Gas Town支持多个AI编码运行时。每个钻井平台的运行时设置在 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 # 初始化工作区 gt rig add # 添加项目 gt rig list # 列出项目 gt crew add --rig # 创建船员工作区

代理 & 车队

gt agents # 列出活跃代理 gt sling # 向代理分配工作 gt sling --agent cursor # 覆盖本次分配的运行时 gt mayor attach # 启动市长会话 gt mayor start --agent auggie # 使用特定代理别名运行市长 gt prime # 上下文恢复（在现有会话内运行） gt feed # 实时活动源（TUI） gt feed --problems # 以问题视图启动（卡住代理检测）

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

gt convoy create [issues...] # 创建带问题的车队 gt convoy list # 列出所有车队 gt convoy show [id] # 显示车队详情 gt convoy add <issue-id...> # 向车队添加问题

配置

设置自定义代理命令

gt config agent set claude-glm "claude-glm --model glm-4" gt config agent set codex-low "codex --thinking low"

设置默认代理

gt config default-agent claude-glm

高级命令

gt escalate -s HIGH "description" # 升级一个阻碍 gt escalate list # 列出开放升级 gt scheduler status # 显示调度器状态 gt seance # 发现先前会话 gt seance --talk # 询问前任会话

配方

bd formula list # 列出配方 bd cook # 执行配方 bd mol pour # 倒出配方分子

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

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

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

Loading

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.

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

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

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

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

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

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.

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—beads are the underlying data format, while issues are the work items stored as beads.

Workflow 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.

Monitoring: Witness, Deacon, Dogs 🐕

A three-tier watchdog system keeps agents healthy:

• Witness - Per-rig lifecycle manager. Monitors polecats, detects stuck agents, triggers recovery, manages session cleanup.
• Deacon - Background supervisor running continuous patrol cycles across all rigs.
• Dogs - Infrastructure workers dispatched by the Deacon for maintenance tasks (e.g., Boot for triage).

Per-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.

Severity-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.

Config-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.

Session discovery and continuation. Discovers previous agent sessions via .events.jsonl logs, enabling agents to query their predecessors for context and decisions from earlier work.

gt seance                       # List discoverable predecessor sessions
gt seance --talk <id> -p "What did you find?"  # One-shot question

Federated 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.

New to Gas Town? See the Glossary for a complete guide to terminology and concepts.

Setup (Docker-Compose below)

# Install Gas Town
$ brew install gastown                                    # Homebrew (recommended)
$ npm install -g @gastown/gt                              # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest  # From source (Linux only)

# macOS: go install produces unsigned binaries that macOS will SIGKILL.
# Use brew install (above) or install Dolt and clone/build with make:
$ brew install dolt
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ make build && mv gt $HOME/go/bin/

# Windows (or if go install fails): clone and build manually
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ go build -o gt.exe ./cmd/gt
$ mv gt.exe $HOME/go/bin/  # or add gastown to PATH

# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$HOME/go/bin"

# Create workspace with git initialization
gt install ~/gt --git
cd ~/gt

# Add your first project
gt rig add myproject https://github.com/you/repo.git

# Create your crew workspace
gt crew add yourname --rig myproject
cd myproject/crew/yourname

# Start the Mayor session (your main interface)
gt mayor attach


export GIT_USER="<your name>"
export GIT_EMAIL="<your email>"
export FOLDER="/Users/you/code"
export DASHBOARD_PORT=8080  # optional, host port for the web dashboard

docker compose build              # only needed on first run or after code changes
docker compose up -d

docker compose exec gastown zsh   # or bash

gt up

gh auth login                     # if you want gh to work

gt mayor attach

Run

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

and tell the Mayor what you want to build!

---

sequenceDiagram
    participant You
    participant Mayor
    participant Convoy
    participant Agent
    participant Hook

    You->>Mayor: Tell Mayor what to build
    Mayor->>Convoy: Create convoy with beads
    Mayor->>Agent: Sling bead to agent
    Agent->>Hook: Store work state
    Agent->>Agent: Complete work
    Agent->>Convoy: Report completion
    Mayor->>You: Summary of progress

Loading

Example: Feature Development

# 1. Start the Mayor
gt mayor attach

# 2. In Mayor session, create a convoy with bead IDs
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

# 3. Assign work to an agent
gt sling gt-abc12 myproject

# 4. Track progress
gt convoy list

# 5. Monitor agents
gt agents

Mayor Workflow (Recommended)

Best for: Coordinating complex, multi-issue work

flowchart LR
    Start([Start Mayor]) --> Tell[Tell Mayor<br/>what to build]
    Tell --> Creates[Mayor creates<br/>convoy + agents]
    Creates --> Monitor[Monitor progress<br/>via convoy list]
    Monitor --> Done{All done?}
    Done -->|No| Monitor
    Done -->|Yes| Review[Review work]

Loading

Commands:

# Attach to Mayor
gt mayor attach

# In Mayor, create convoy and let it orchestrate
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify

# Track progress
gt convoy list

Run individual runtime instances manually. Gas Town just tracks state.

gt convoy create "Fix bugs" gt-abc12   # Create convoy (sling auto-creates if skipped)
gt sling gt-abc12 myproject            # Assign to worker
claude --resume                        # Agent reads mail, runs work (Claude)
# or: codex                            # Start Codex in the workspace
gt convoy list                         # Check progress

Best for: Predefined, repeatable processes

Formulas are TOML-defined workflows embedded in the gt binary (source in internal/formula/formulas/).

Example 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"]

Execute:

# List available formulas
bd formula list

# Run a formula with variables
bd cook release --var version=1.2.0

# Create formula instance for tracking
bd mol pour release --var version=1.2.0

Best for: Direct control over work distribution

# Create convoy manually
gt convoy create "Bug Fixes" --human

# Add issues to existing convoy
gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x

# Assign to specific agents
gt sling gt-m3k9p myproject/my-agent

# Check status
gt convoy show

Gas Town supports multiple AI coding runtimes. Per-rig runtime settings are in settings/config.json.

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

Notes:

• Claude uses hooks in .claude/settings.json (managed via --settings flag) for mail injection and startup.

• For Codex, set project_doc_fallback_filenames = ["CLAUDE.md"] in ~/.codex/config.toml so role instructions are picked up.

• For runtimes without hooks (e.g., Codex), Gas Town sends a startup fallback after the session is ready: gt prime, optional gt mail check --inject for autonomous roles, and gt nudge deacon session-started.

• GitHub Copilot (copilot) is a built-in preset using --yolo for autonomous mode. It uses executable lifecycle hooks in .github/hooks/gastown.json (same events as Claude: sessionStart, userPromptSubmitted, preToolUse, sessionEnd). Uses a 5-second ready delay instead of prompt detection. Requires a Copilot seat and org-level CLI policy. See docs/INSTALLING.md.

  gt install # Initialize workspace gt rig add # Add project gt rig list # List projects gt crew add --rig # Create crew workspace

  gt agents # List active agents gt sling # Assign work to agent gt sling --agent cursor # Override runtime for this sling/spawn gt mayor attach # Start Mayor session gt mayor start --agent auggie # Run Mayor with a specific agent alias gt prime # Context recovery (run inside existing session) gt feed # Real-time activity feed (TUI) gt feed --problems # Start in problems view (stuck agent detection)

Built-in agent presets : claude, gemini, codex, cursor, auggie, amp, opencode, copilot, pi, omp

gt convoy create <name> [issues...]   # Create convoy with issues
gt convoy list              # List all convoys
gt convoy show [id]         # Show convoy details
gt convoy add <convoy-id> <issue-id...>  # Add issues to convoy


# Set custom agent command
gt config agent set claude-glm "claude-glm --model glm-4"
gt config agent set codex-low "codex --thinking low"

# Set default agent
gt config default-agent claude-glm


gt escalate -s HIGH "description"  # Escalate a blocker
gt escalate list               # List open escalations
gt scheduler status            # Show scheduler state
gt seance                      # Discover previous sessions
gt seance --talk <id>          # Query a predecessor session


bd formula list             # List formulas
bd cook <formula>           # Execute formula
bd mol pour <formula>       # Create trackable instance
bd mol list                 # List active instances


gt wl join <remote>            # Join a wasteland
gt wl browse                   # View wanted board
gt wl claim <id>               # Claim work
gt wl done <id> --evidence <url>  # Submit completion

Gas Town includes built-in formulas for common workflows. See internal/formula/formulas/ for available recipes.

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:

• Agent Tree - Hierarchical view of all agents grouped by rig and role

• Convoy Panel - In-progress and recently-landed convoys

• Event Stream - Chronological feed of creates, completions, slings, nudges, and more

  gt feed # Launch TUI dashboard gt feed --problems # Start in problems view gt feed --plain # Plain text output (no TUI) gt feed --window # Open in dedicated tmux window gt feed --since 1h # Events from last hour

Navigation: j/k to scroll, Tab to switch panels, 1/2/3 to jump to a panel, ? for help, q to quit.

At 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.

Press p in gt feed (or start with gt feed --problems) to toggle the problems view, which groups agents by health state:

State	Condition
GUPP Violation	Hooked work with no progress for an extended period
Stalled	Hooked work with reduced progress
Zombie	Dead tmux session
Working	Active, progressing normally
Idle	No hooked work

Intervention keys (in problems view): n to nudge the selected agent, h to handoff (refresh context).

Gas Town includes a web dashboard for monitoring your workspace. The dashboard must be run from inside a Gas Town workspace (HQ) directory.

# Start dashboard (default port 8080)
gt dashboard

# Start on a custom port
gt dashboard --port 3000

# Start and automatically open in browser
gt dashboard --open

The dashboard gives you a single-page overview of everything happening in your workspace: agents, convoys, hooks, queues, issues, and escalations. It auto-refreshes via htmx and includes a command palette for running gt commands directly from the browser.

Gas Town uses a three-tier watchdog chain to keep agents healthy at scale:

Daemon (Go process) ← heartbeat every 3 min
    └── Boot (AI agent) ← intelligent triage
        └── Deacon (AI agent) ← continuous patrol
            └── Witnesses & Refineries ← per-rig agents

Each 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.

The 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.

When agents hit blockers, they escalate rather than waiting:

gt escalate -s HIGH "Description of blocker"
gt escalate list                    # List open escalations
gt escalate ack <bead-id>           # Acknowledge an escalation

Escalations route through Deacon -> Mayor -> Overseer based on severity. See Escalation design.

The Refinery processes completed polecat work through a bisecting merge queue:

1. Polecat runs gt done -> branch pushed, MR bead created
2. Refinery batches pending MRs
3. Runs verification gates on the merged stack
4. If green: all MRs in batch merge to main
5. If red: bisects to isolate the failing MR, merges the good ones

This is a Bors-style merge queue — polecats never push directly to main.

The scheduler controls polecat dispatch capacity to prevent API rate limit exhaustion:

gt config set scheduler.max_polecats 5   # Enable deferred dispatch (max 5 concurrent)
gt scheduler status                      # Show scheduler state
gt scheduler pause                       # Pause dispatch
gt scheduler resume                      # Resume dispatch

Default mode (max_polecats = -1) dispatches immediately via gt sling. When a limit is set, the daemon dispatches incrementally, respecting capacity. See Scheduler design.

Discover and query previous agent sessions:

gt seance                              # List discoverable predecessor sessions
gt seance --talk <id>                  # Full context conversation with predecessor
gt seance --talk <id> -p "Question?"   # One-shot question to predecessor

Seance discovers sessions via .events.jsonl logs, enabling agents to recover context and decisions from earlier work without re-reading entire codebases.

The Wasteland is a federated work coordination network linking multiple Gas Towns through DoltHub:

gt wl join hop/wl-commons              # Join a wasteland
gt wl browse                           # View wanted board
gt wl claim <id>                       # Claim a wanted item
gt wl done <id> --evidence <url>       # Submit completion with evidence
gt wl post --title "Need X"            # Post new wanted item

Completions earn portable reputation via multi-dimensional stamps (quality, speed, complexity). See Wasteland guide.

Telemetry (OpenTelemetry)

Gas Town emits all agent operations as structured logs and metrics to any OTLP-compatible backend (VictoriaMetrics/VictoriaLogs by default):

# Configure OTLP endpoints
export GT_OTEL_LOGS_URL="http://localhost:9428/insert/jsonline"
export GT_OTEL_METRICS_URL="http://localhost:8428/api/v1/write"

Events emitted: session lifecycle, agent state changes, bd calls with duration, mail operations, sling/nudge/done workflows, polecat spawn/remove, formula instantiation, convoy creation, daemon restarts, and more.

Metrics include: gastown.session.starts.total, gastown.bd.calls.total, gastown.polecat.spawns.total, gastown.done.total, gastown.convoy.creates.total, and others.

See OTEL data model and OTEL architecture for the complete event schema.

Gas Town uses git hooks as a propulsion mechanism. Each hook is a git worktree with:

1. Persistent state - Work survives agent restarts
2. Version control - All changes tracked in git
3. Rollback capability - Revert to any previous state
4. Multi-agent coordination - Shared through git

stateDiagram-v2
    [*] --> Created: Agent spawned
    Created --> Active: Work assigned
    Active --> Suspended: Agent paused
    Suspended --> Active: Agent resumed
    Active --> Completed: Work done
    Completed --> Archived: Hook archived
    Archived --> [*]

Loading

MEOW (Mayor-Enhanced Orchestration Workflow)

MEOW is the recommended pattern:

1. Tell the Mayor - Describe what you want
2. Mayor analyzes - Breaks down into tasks
3. Convoy creation - Mayor creates convoy with beads
4. Agent spawning - Mayor spawns appropriate agents
5. Work distribution - Beads slung to agents via hooks
6. Progress monitoring - Track through convoy status
7. Completion - Mayor summarizes results

# Bash
gt completion bash > /etc/bash_completion.d/gt

# Zsh
gt completion zsh > "${fpath[1]}/_gt"

# Fish
gt completion fish > ~/.config/fish/completions/gt.fish

Role	Description	Primary Interface
Mayor	AI coordinator	gt mayor attach
Human (You)	Crew member	Your crew directory
Polecat	Worker agent	Spawned by Mayor
Witness	Per-rig agent health monitor	Automatic patrol
Deacon	Cross-rig supervisor daemon	gt patrol
Refinery	Merge queue processor	Automatic
Hook	Persistent storage	Git worktree
Convoy	Work tracker	gt convoy commands

• Always start with the Mayor - It's designed to be your primary interface
• Use convoys for coordination - They provide visibility across agents
• Leverage hooks for persistence - Your work won't disappear
• Create formulas for repeated tasks - Save time with Beads recipes
• Usegt feed for live monitoring - Watch agent activity and catch stuck agents early
• Monitor the dashboard - Get real-time visibility in the browser
• Let the Mayor orchestrate - It knows how to manage agents

For deeper technical details, see the design docs in docs/:

Check hooks are properly initialized:

gt hooks list
gt hooks repair

Force refresh:

gt convoy refresh <convoy-id>

Restart Mayor session:

gt mayor detach
gt mayor attach

MIT License - see LICENSE file for details