Gas Town Agent Types and Their Scopes: A Complete Guide to the AI Worker Hierarchy

Gas Town organizes AI workers into two distinct scopes—Town-level agents (Mayor, Deacon, Dog) that coordinate across all rigs, and Rig-level agents (Witness, Refinery, Polecat, Crew) that handle work within individual rigs.

The open-source Gas Town project (gastownhall/gastown) implements a hierarchical AI worker system where each agent type operates within a specific scope. Understanding these Gas Town agent types and their scopes is essential for managing distributed AI workflows across multiple rigs. The architecture distinguishes between global coordinators that manage the entire town and specialized workers confined to single rig environments.

Understanding the Two-Scope Architecture

According to docs/design/architecture.md (lines 12-39), Gas Town implements a strict two-tier scope system that determines how agents interact with resources and other workers.

Town-Level Scope (Global)

Town-level agents possess visibility across the entire Gas Town installation. These agents manage all rigs simultaneously, coordinate system-wide events, and enforce global health policies. They operate as singletons within the deployment.

Rig-Level Scope (Per Rig)

Rig-level agents are confined to a single rig's workspace. These agents handle user-directed work, patrol operations, and merge activities within their specific rig boundary. They cannot directly access resources or state from other rigs.

Town-Level Agent Types

As documented in docs/reference.md, three primary agent types constitute the Town-level supervisory layer.

Mayor (Chief-of-Staff)

The Mayor serves as the chief-of-staff AI with Town-level scope. It initiates Convoys, distributes work across all rigs, and coordinates high-level events. The Mayor receives escalations from lower-level agents and can issue strategic commands to the entire system. Reference: docs/reference.md#L313.

Deacon (Daemon-Beacon)

The Deacon operates as a daemon-beacon with Town-level scope, running continuous patrol cycles to check system health. It monitors the activity of other agents and triggers recovery actions, such as restarting a stuck Witness. The Deacon also manages a pool of Dog helpers. Reference: docs/reference.md#L343.

Dog (Infrastructure Helper)

Dog agents are ephemeral Town-level helpers under the Deacon's supervision. They perform infrastructure tasks such as health-checks, cleanup, and other maintenance jobs. Unlike Polecats, Dogs are not used for user-directed work and operate globally across the town. Reference: docs/reference.md#L354.

Rig-Level Agent Types

Four agent types operate within the Rig-level scope, handling actual user work and rig-specific operations as detailed in docs/design/polecat-lifecycle-patrol.md (lines 16-254).

Witness (Patrol Agent)

The Witness functions as a patrol agent overseeing the Polecats on its specific rig. It detects stuck or crashed workers and notifies the Deacon, or escalates directly to the Mayor when recovery is needed. Each rig maintains its own Witness instance. Reference: docs/reference.md#L367.

Refinery (Convoy Merger)

The Refinery handles convoy merging and finalization for its assigned rig. It works closely with the Witness to ensure that completed work is merged back into the main codebase. This agent manages the integration phase of the workflow lifecycle. Reference: docs/reference.md#L371.

Polecat (Primary Worker)

The Polecat represents the primary worker that performs user-requested tasks, including code edits, reviews, and testing. Polecats are persistent across sessions but remain strictly scoped to a single rig. They form the main workforce for user-directed operations. Reference: docs/reference.md#L386.

Crew (Persistent Helper)

Crew agents are long-lived Rig-level helpers designed for extended work periods. Unlike Polecats, Crews maintain their own full clones (not worktrees) and can preserve state across many tasks. They provide persistent assistance within their designated rig. Reference: docs/reference.md#L392.

Configuration and Implementation

Agent type definitions and presets are implemented in internal/config/agents.go. This source file contains the builtin agent presets (such as Claude, Gemini, etc.) that map to the architectural roles described above. When configuring Gas Town, these presets determine which AI models and parameters back each specific agent type.

Summary

• Gas Town organizes AI workers into Town-level (global) and Rig-level (per-rig) scopes.
• Town-level agents include the Mayor (coordination), Deacon (health monitoring), and Dog (maintenance helpers).
• Rig-level agents include the Witness (patrol), Refinery (merging), Polecat (primary work), and Crew (persistent helpers).
• Scope boundaries determine whether an agent can access resources across all rigs or is confined to a single workspace.
• Configuration resides in internal/config/agents.go, while architectural details are documented in docs/design/architecture.md.

Frequently Asked Questions

What is the difference between Town-level and Rig-level agents in Gas Town?

Town-level agents operate across the entire Gas Town installation with global visibility, managing all rigs simultaneously. Rig-level agents are confined to a single rig's workspace, handling user work and maintenance within that specific boundary. This distinction prevents resource conflicts and ensures proper isolation between different work environments.

How does the Deacon agent differ from the Witness agent?

The Deacon is a Town-level agent that monitors system health across all rigs and manages recovery actions globally, while the Witness is a Rig-level agent that patrols only its assigned rig's Polecats. The Witness reports issues to the Deacon, which can then trigger town-wide recovery protocols or escalate to the Mayor if necessary.

What is the role of a Crew agent compared to a Polecat?

Both operate at the Rig-level, but Crews are long-lived helpers with full repository clones designed for extended stateful work, whereas Polecats are the primary workers handling individual user tasks using worktrees. Crews maintain persistence across multiple tasks, while Polecats focus on specific, discrete operations within a session.

Where are agent types configured in the Gas Town source code?

Agent types and their builtin presets are configured in internal/config/agents.go. This file maps AI model configurations (such as Claude and Gemini) to the specific agent roles (Mayor, Deacon, Polecat, etc.) that operate within the town's two-scope architecture.

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