Gas Town: Multi-Agent Orchestration with Persistent Work Tracking

Gas Town: A Detailed Guide to Multi-Agent Orchestration and Persistent Work Tracking

Introduction Gas Town is a radical workspace manager designed to orchestrate multiple AI coding agents—Claude Code, GitHub Copilot, Codex, Gemini, and others—without losing context as agents restart or sessions end. At its core, Gas Town persists work state in git-backed hooks, transforming chaos into coherent, auditable multi-agent workflows. This blog post walks through what Gas Town is, how it’s built, and how you can use it to coordinate a growing cadre of AI workers—from a handful of agents to a bustling fleet of 20–30.

What Problem Does This Solve? Gas Town is built to address the key pain points of multi-agent coding environments. Rather than relying on fragile in-memory state or ad-hoc handoffs, Gas Town provides durable, auditable persistence and structured coordination.

• Agent context is lost on restart
• Gas Town relies on git-backed hooks to persist work state. This means that even after crashes, restarts, or redeployments, the current progress and decisions survive.
• Manual agent coordination is error-prone
• Built-in mailboxes, identities, and handoffs automate communications and transitions between agents, reducing human-in-the-loop friction.
• When 4–10 agents become chaotic, growth breaks your flow
• Gas Town scales to 20–30 agents gracefully through robust routing, state tracking, and batched work management.
• Work state is buried in memory
• All work state is stored in the Beads ledger within git-backed hooks, making history-accurate audits and rollbacks straightforward.

Architecture at a Glance Below is the architectural picture of Gas Town, presented as a diagram to illustrate how the components fit together and interact.

Mermaid Diagram: 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]

In short: The Mayor coordinates, the Town houses your workspace, Rigs enclose project containers, Crew Members are your hands-on workspace, Polecats are persistent identities for worker agents, and Hooks/Beads provide durable, billable state.

Core Concepts Gas Town is built from a collection of interlocking concepts that give you scalable, persistent, multi-agent workflows.

• The Mayor (🎩)
• Your primary AI coordinator. A Claude Code instance with full context about your workspace, projects, and agents. Start here—tell the Mayor what you want to accomplish, and it will orchestrate the rest.
• Town (🏘️)
• Your workspace directory (for example, ~/gt/). It contains all projects, agents, and configuration.
• Rigs (🏗️)
• Project containers. Each rig wraps a git repository and manages its associated agents. Rigs isolate work by project or domain while keeping a unified control surface.
• Crew Members (👤)
• Your personal workspace within a rig. Where you do hands-on work. They represent individual crew members or sub-teams within a rig.
• Polecats (🦨)
• Worker agents with persistent identity but ephemeral sessions. They’re spawned for tasks, sessions end on completion, but identity and work history persist, enabling continuity across runs.
• Hooks (🪝)
• Git worktree-based persistent storage for agent work. Hooks survive crashes and restarts by keeping state in the VCS layer.
• Convoys (🚚)
• Work-tracking units. Convoys bundle multiple beads (work items) that get assigned to agents. Convoys labeled mountain have 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 follow a prefix + 5-character alphanumeric format (e.g., gt-abc12, hq-x7k2m). The prefix signals origin or rig. Commands like gt sling and gt convoy reference these IDs. Beads and issues are two terms for the same underlying data—beads are the 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. Modes include root-only wisps (runtime materialization) and poured wisps (checkpointed sub-wisps with recovery).
• Monitoring: Witness, Deacon, Dogs (🐕)
• A three-tier watchdog system for health and resilience:
  • Witness: Per-rig lifecycle manager monitoring polecats, detecting stuck agents, triggering recovery, and handling session cleanup.
  • Deacon: Cross-rig supervisor running continuous patrol cycles and orchestrating maintenance tasks via Dogs.
  • 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. Failures are isolated and fixed or re-dispatched.
• Escalation (🚨)
• Severity-based issue escalation. Blocked agents escalate via gt escalate, which routes through Deacon, Mayor, and Overseer as needed. Severity levels: CRITICAL (P0), HIGH (P1), MEDIUM (P2).
• Scheduler (⏱️)
• Config-driven capacity governor for polecat dispatch. Prevents API rate limit exhaustion by batching dispatch under configurable concurrency. Default is direct dispatch; set scheduler.max_polecats to enable deferred dispatch with the daemon.
• Seance (👻)
• Session discovery and continuation. Discovers previous agent sessions via .events.jsonl logs, enabling agents to query predecessors for context and decisions from earlier work.
• 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 with multi-dimensional stamps.

New to Gas Town? See the Glossary If you’re new, Gas Town provides a comprehensive glossary of terms to guide you through its terminology and concepts. The glossary is a helpful reference as you navigate between beads, convoys, and molecules.

Installation Essentials Gas Town sets up a full multi-agent environment and requires a suite of tools. Here’s a concise setup outline.

Prerequisites

• Go 1.25+ (go.dev/dl)
• Git 2.25+ (for git worktree support)
• Dolt 1.82.4+ (brew install dolt for macOS, or see the DoltHub project)
• beads (bd) 0.55.4+ (installed via brew install gastown or from beads repo)
• sqlite3 (for convoy database queries; usually pre-installed)
• tmux 3.0+ (recommended for the full experience)
• Runtime clients:
• Claude Code CLI (default runtime) — claude.ai/code
• Codex CLI — developers.openai.com/codex/cli
• GitHub Copilot CLI — cli.github.com (requires Copilot seat)

Setup (Docker-Compose below)

• Install Gas Town with your package manager or go tooling
• Create a workspace and initialize git
• Add your projects and crews
• Start the Mayor session and attach to the workspace
• Optional: start the dashboard and enable gh auth if you want GitHub integration

Basic quick-start commands (summarized)

• Install and initialize: gt install ~/gt --git
• Create and attach to Mayor: gt mayor attach
• Create convoys and start the orchestration: gt convoy create "Feature X" gt-abc12
• Sling work to agents: gt sling gt-abc12 myproject
• Check progress: gt convoy list
• Start dashboard: gt dashboard

Quick Start Guide: How to Begin

• Step 1: Install and initialize Gas Town in your workspace.
• Step 2: Create your first rig (project) and crew, then attach to the Mayor.
• Step 3: Define a convoy with beads (work items) and sling them to available agents.
• Step 4: Monitor progress via the convoy list, agents view, and the activity feed.
• Step 5: If blockers appear, escalate or hand off context to maintain momentum.

Common Workflows Gas Town supports several robust workflows, each designed for different scales and preferences. Below are three representative patterns.

Mayor Workflow (Recommended)

• Start the Mayor to coordinate complex, multi-issue work.
• Create a convoy with beads (e.g., “Auth System” with bead IDs gt-x7k2m and gt-p9n4q).
• The Mayor distributes beads across agents, tracks progress through the convoy, and consolidates results when ready.

Minimal Mode (No Tmux)

• Create convoys and assign work directly to workers without multi-session coordination.
• Agents read mail, perform work, and report via the convoy.
• Useful for small teams or quick experiments where a full orchestration surface isn’t needed.

Beads Formula Workflow

• Define reusable formulas (TOML) embedded in the Gas Town binary. A release workflow example shows steps for bumping versions, running tests, building, tagging, and publishing.
• Execute formulas with variables, pour instances for tracking, and reuse them for repeatable tasks.

Manual Convoy Workflow

• Create convoys manually and add issues to maintain precise, direct control over task distribution.
• Assign tasks to specific agents or crews, and monitor from the convoy’s details.

Runtime Configuration Gas Town supports multiple runtimes per rig, with per-rig runtime settings in settings/config.json. A typical configuration looks like:

• Provider: codex
• Command: codex
• Args: []
• Prompt mode: none

Notes on hooks and runtime-specific behavior

• Claude uses hooks in .claude/settings.json for mail injection and startup.
• Codex requires a role-picking fallback: projectdocfallback_filenames = ["CLAUDE.md"] in ~/.codex/config.toml.
• For runtimes without hooks, Gas Town can perform startup fallbacks after the session is ready (gt prime, gt mail check --inject, gt nudge deacon session-started).
• GitHub Copilot is a built-in preset using --yolo for autonomous mode and uses lifecycle hooks under .github/hooks/gastown.json. Copilot requires an org-level policy and a Copilot seat.

Key Commands: Practical Hands-On Workspace Management

• gt install: Initialize workspace
• gt rig add: Add a project
• gt rig list: List projects
• gt crew add: Create a crew workspace

Agent Operations

• gt agents: List active agents
• gt sling: Assign work to an agent
• gt sling --agent cursor: Override runtime for this sling
• gt mayor attach: Start Mayor session
• gt mayor start --agent : Run Mayor with a specific agent
• gt prime: Run context recovery
• gt feed: Real-time activity feed

Convoy (Work Tracking)

• gt convoy create [issues…]: Create convoy with issues
• gt convoy list: List convoys
• gt convoy show [id]: Show convoy details
• gt convoy add: Add issues to convoy

Configuration

• gt config agent set "": Set a custom agent command
• gt config default-agent : Set default agent

Monitoring & Health

• gt escalate -s "": Escalate a blocker
• gt escalate list: List open escalations
• gt scheduler status: Show scheduler state
• gt seance: Discover previous sessions

Beads Integration

• bd formula list: List formulas
• bd cook : Execute formula
• bd mol pour --var =: Create a tracking instance

Wasteland Federation

• gt wl join: Join a wasteland
• gt wl browse: View wanted board
• gt wl claim: Claim a wanted item
• gt wl done --evidence: Submit completion with evidence

Telemetry and Observability Gas Town emits structured logs and metrics to OTLP-compatible backends. You can configure endpoints like:

• OTLP logs URL: GTOTELLOGS_URL
• OTLP metrics URL: GTOTELMETRICS_URL

Events and Metrics

• Events: session lifecycle, agent state changes, bd calls with duration, mail operations, sling/nudge/done workflows, polecat spawn/remove, and others.
• Metrics: gastown.session.starts.total, gastown.bd.calls.total, gastown.polecat.spawns.total, gastown.done.total, gastown.convoy.creates.total, among others.

Advanced Concepts Propulsion Principle

• Gas Town uses git hooks as a propulsion mechanism. Each hook is a git worktree with persistent state, version control, rollback capability, and multi-agent coordination shared through git.

Hook Lifecycle

• A hook moves through states such as Created, Active, Suspended, Completed, and Archived. This lifecycle models agent spawn, work assignment, pause/resume, completion, and archiving of work states.

MEOW: Mayor-Enhanced Orchestration Workflow

• MEOW outlines a recommended pattern: Tell the Mayor, Mayor analyzes, Convoy creation, Agent spawning, Work distribution, Progress monitoring, Completion summary. It’s a practical recipe for full-stack orchestration.

Shell Completions

• Gas Town offers shell completions for Bash, Zsh, and Fish, easing daily usage and reducing friction for new users.

Project Roles

• Mayor: AI coordinator
• Human (You): Crew member
• Polecat: Worker agent
• Witness: Per-rig health monitor
• Deacon: Cross-rig supervisor
• Refinery: Merge queue processor
• Hook: Persistent storage
• Convoy: Work tracker

Tips for Real-World Use

• Always start with the Mayor: It’s your central control plane.
• Use convoys for cross-agent visibility: They provide coordinated progress.
• Leverage hooks for persistence: Your work won’t disappear between sessions.
• Create formulas for repetitive tasks: Beads recipes speed common pipelines.
• Use gt feed for live monitoring: Real-time visibility helps catch stuck agents early.
• Monitor the dashboard for a browser-based overview: A single pane of glass for agents, convoys, hooks, queues, and escalations.
• Let the Mayor do the orchestrating: It knows how to manage agents, contexts, and handoffs across the entire workspace.

Design Documentation and Reference Gas Town ships with design documentation that covers architecture, glossary, molecules, escalation, scheduler, Wasteland, and OTEL data models. See links under the Design Documentation section in the original docs for deeper technical detail.

Troubleshooting

• Employees lose connection: Check hooks are properly initialized, using commands like gt hooks list and gt hooks repair.
• Convoy stuck: Force a refresh with gt convoy refresh.
• Mayor not responding: Detach and re-attach to the Mayor session with gt mayor detach and gt mayor attach.

Licensing Gas Town is MIT licensed. The license text can be found in the repository’s LICENSE file.

Images and Visual Aids Included

• Architecture Diagram: The mermaid diagram shown above captures the primary relationships in Gas Town: The Mayor coordinating the Town, with Rigs, Crews, Hooks, and Polecats connecting to Git Repositories and Beads.
• Mood and concept icons for core components: Mayor (🎩), Town (🏘️), Rig (🏗️), Crew Members (👤), Polecats (🦨), Hooks (🪝), Convoys (🚚), Beads (📿), Molecules (🧬), and the health monitors (🐕) to provide quick visual anchors in the prose.

Closing Thoughts Gas Town reframes how you coordinate AI-driven development work at scale. By preserving context through git-backed hooks, it eliminates the biggest roadblocks to productive multi-agent collaboration: lost state, miscommunication, and chaotic agent interactions. The Mayor acts as a central, intelligent coordinator while the Beads ledger and Convoys provide durable, auditable progress tracking. The architecture supports growth—from a handful of agents to a large fleet—without sacrificing reliability or clarity.

If you’re considering a multi-agent coding environment, Gas Town offers a cohesive, scalable blueprint: a single source of truth for state, a repeatable workflow for complex tasks, and an infrastructure that stays resilient as your team and toolset expand. Whether you’re a solo practitioner orchestrating Claude Code and Copilot or a team managing dozens of agents across multiple projects, Gas Town gives you the governance, persistence, and visibility you need to build quickly, safely, and at scale.