Snowflake-Labs/gastown

Snowflake-Labs/gastown

Description: Gas Town - multi-agent workspace manager

Language: Go

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-04-15T08:58:27Z

Pushed: 2026-04-16T16:01:02Z

Default branch: main

Fork: yes

Parent repository: gastownhall/gastown

Archived: no

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

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

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

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

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

Molecules 🧬

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](docs/concepts/molecules.md).

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

Refinery 🏭

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.

Escalation 🚨

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](docs/design/escalation.md).

Scheduler ⏱️

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](docs/design/scheduler.md).

Seance 👻

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 -p "What did you find?" # One-shot question

Wasteland 🏜️

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](docs/WASTELAND.md).

> New to Gas Town? See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.

Installation

Prerequisites

• Go 1.25+ - go.dev/dl
• Git 2.25+ - for worktree support
• Dolt 1.82.4+ - github.com/dolthub/dolt
• beads (bd) 0.55.4+ - github.com/steveyegge/beads
• sqlite3 - for convoy database queries (usually pre-installed on macOS/Linux)
• tmux 3.0+ - recommended for full experience
• Claude Code CLI (default runtime) - claude.ai/code
• Codex CLI (optional runtime) - developers.openai.com/codex/cli
• GitHub Copilot CLI (optional runtime) - cli.github.com (requires Copilot seat)

Setup (Docker-Compose below)

# Install Gas Town
$ brew install gastown…