# How Gas Town Orchestrates AI Agents Across Repositories

> Discover how Gas Town orchestrates AI agents across repositories. Learn about the Mayor, Convoys, Polecats, and Witness roles in managing distributed workflows.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: architecture
- Published: 2026-07-07

---

**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](https://github.com/gastownhall/gastown/blob/main/README.md#basic-workflow), 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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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:

```bash

# 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`](https://github.com/gastownhall/gastown/blob/main/internal/witness/handlers.go) – Witness health monitoring and slot-open detection
- [`internal/deacon/patrol.go`](https://github.com/gastownhall/gastown/blob/main/internal/deacon/patrol.go) – Cross-rig patrol cycles and Dog dispatch
- [`internal/nudge/poller.go`](https://github.com/gastownhall/gastown/blob/main/internal/nudge/poller.go) – Reliable nudge delivery implementation
- [`internal/cmd/sling.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/sling.go) – Polecat creation and runtime attachment
- [`internal/daemon/refinery.go`](https://github.com/gastownhall/gastown/blob/main/internal/daemon/refinery.go) – Merge-queue orchestration and MR-Bead handling
- [`internal/scheduler/capacity/dispatch.go`](https://github.com/gastownhall/gastown/blob/main/internal/scheduler/capacity/dispatch.go) – Capacity-governed dispatch logic
- [`internal/convoy/convoy.go`](https://github.com/gastownhall/gastown/blob/main/internal/convoy/convoy.go) – Convoy and Bead tracking implementation
- [`internal/web/fetcher.go`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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.