How Gas Town Orchestrates AI Agents Across Repositories

Gas Town coordinates distributed AI agents through a central Mayor that manages Convoys of Beads, dispatching work to Polecats in Git worktrees while Witnesses and Deacons monitor health across all connected repositories.

Gas Town, available at gastownhall/gastown, is an open-source orchestration platform designed to manage AI agents across multiple Git repositories called Rigs. The architecture leverages Git itself as a persistent state layer, ensuring that agent work survives crashes and maintains complete version history.

The Mayor and Convoy Architecture

At the heart of Gas Town's orchestration sits the Mayor, a central coordinator that translates high-level build requests into actionable work units. When you initiate a task, the Mayor creates a Convoy—a collection of Bead IDs representing discrete work items.

The Convoy is recorded in the Beads ledger (bd), which persists in the Git worktree of the HQ repository. According to the README.md, this design ensures that work allocation is durable and versioned from the moment of creation.

Polecat Execution and the Hook System

The Mayor distributes work by slinging individual Beads to Polecats—lightweight agents that execute within specific Rigs. The gt sling command (implemented in internal/cmd/sling.go) spawns a short-lived AI runtime such as Claude Code, Codex, or Gemini inside a tmux pane or headless mode.

Each Polecat receives a Hook, which is a dedicated Git worktree where the agent writes intermediate state. Because the Hook is a standard Git worktree, all changes are automatically versioned, diffable, and recoverable. This propulsion principle transforms Git into a persistent message bus, allowing agents to maintain state across restarts without external databases.

Cross-Rig Coordination via Witness and Deacon

Every Rig runs a Witness agent (internal/witness/handlers.go) that monitors local Polecat activity. The Witness watches Hook directories for stalled processes, detects idle agents, and issues nudges to the Mayor when slots become available or when human intervention is required.

Coordinating across all Rigs, the Deacon (internal/deacon/patrol.go) executes continuous patrol cycles. It aggregates health reports from every Witness, dispatches Dog workers for maintenance tasks like cleaning old sessions, and escalates blockers that individual Witnesses cannot resolve. This layered monitoring ensures that the system remains healthy even when orchestrating dozens of agents across disparate repositories.

Refinery Merge Queue and Workflow Completion

When a Polecat finishes its task and executes gt done, it pushes a feature branch and creates an MR-Bead. The Refinery (internal/daemon/refinery.go) manages these completions through a Bors-style bisecting merge queue.

The Refinery batches MR-Beads from multiple agents, runs automated verification gates, and merges approved changes to the main branch. This queue prevents merge conflicts and maintains repository integrity while allowing parallel agent execution. You can monitor the queue status using gt refinery status to see pending merges and their health checks.

Communication Channels: Nudge and Mail

Gas Town provides two primary communication primitives for asynchronous coordination. The nudge channel (gt nudge) delivers immediate notifications such as "slot open" alerts, implemented in internal/nudge/poller.go to guarantee reliable delivery even when target sessions are detached.

For persistent messaging that survives session shutdowns, the mail system (gt mail) stores messages until the recipient is ready to process them. This is critical for escalations and hand-offs between agents that may not be simultaneously online.

Capacity Control and Scheduling

To prevent API throttling, a config-driven scheduler (internal/scheduler/capacity/dispatch.go) caps concurrent Polecats per Rig. When capacity limits are reached, the daemon queues additional slings and releases them as signaled by the Witness and Deacon monitoring layers. This backpressure mechanism ensures stable operation across cloud-based AI providers with rate limits.

Example Workflow

The following commands demonstrate the complete orchestration flow across multiple repositories:

# Initialize the entire system (Dolt, Daemon, Deacon, Mayor, per-rig agents)

gt up

# Attach to the Mayor and create a convoy of work

gt mayor attach

# Inside the Mayor session:

gt convoy create "Auth System" gt-abc12 gt-def34 --notify

# Sling a bead to a Polecat in a specific rig

gt sling gt-abc12 myproject

# Inspect the Polecat's progress in its Git worktree Hook

cat myproject/hooks/gt-abc12/README.md

# Check for stalled agents and nudges

gt feed --problems

# Complete work and submit to the Refinery merge queue

gt done

# Check merge queue status

gt refinery status

# Send persistent escalation message

gt mail send mayor/ -s "BLOCKER" -m "API rate limit hit"

Key Implementation Files

The orchestration logic spans several critical source files:

• internal/witness/handlers.go – Witness health monitoring and slot-open detection
• internal/deacon/patrol.go – Cross-rig patrol cycles and Dog dispatch
• internal/nudge/poller.go – Reliable nudge delivery implementation
• internal/cmd/sling.go – Polecat creation and runtime attachment
• internal/daemon/refinery.go – Merge-queue orchestration and MR-Bead handling
• internal/scheduler/capacity/dispatch.go – Capacity-governed dispatch logic
• internal/convoy/convoy.go – Convoy and Bead tracking implementation
• internal/web/fetcher.go – Dashboard status fetching for Mayor, Witness, and Refinery

Summary

Gas Town orchestrates AI agents across repositories through a hierarchical coordination system:

• The Mayor converts requests into versioned Convoys and Beads stored in Git
• Polecats execute AI runtimes in isolated Git worktrees called Hooks, ensuring durable state
• Witnesses monitor per-Rig health while the Deacon coordinates cross-Rig operations
• The Refinery manages a merge queue to safely integrate parallel agent outputs
• Nudge and Mail systems provide reliable async communication between components
• A scheduler enforces capacity limits to prevent API throttling

Frequently Asked Questions

How does Gas Town maintain agent state across runtime restarts?

Gas Town persists all agent state to Git worktrees called Hooks. Because the Hook is a standard Git worktree located at myproject/hooks/<bead-id>/, any files written by the Polecat are immediately versioned. If the Claude Code or Codex runtime crashes, the replacement process simply attaches to the same Hook directory and resumes from the last committed state, functioning as a durable message bus without external databases.

What limits the number of concurrent AI agents in a Gas Town deployment?

The scheduler (internal/scheduler/capacity/dispatch.go) enforces per-Rig capacity limits based on configuration settings, typically designed to respect API rate limits from providers like Anthropic or OpenAI. When the limit is reached, additional gt sling commands queue until the Witness detects a slot opening and nudges the Mayor to release the next agent.

How does the Refinery prevent merge conflicts when multiple agents finish simultaneously?

The Refinery implements a Bors-style bisecting merge queue that batches MR-Beads from completed Polecats. Instead of immediate merging, it runs automated verification gates on the batch and merges them atomically. This ensures that agents working in parallel across different Rigs do not create conflicting changes in the main branch, maintaining repository integrity even under heavy load.

Can Gas Town orchestrate agents across repositories hosted on different platforms?

Yes. Gas Town treats each repository as a Rig, and the orchestration protocol is platform-agnostic. Whether the Git repositories are hosted on GitHub, GitLab, or private Gitea instances, the Mayor dispatches work via gt sling to Polecats in each Rig's local worktree. The Witness and Deacon monitor all Rigs uniformly, consolidating status across heterogeneous hosting environments into a single gt feed dashboard.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}