Concepts

Gas Town by Kilo is built around a small set of composable primitives. Understanding these concepts is key to getting the most out of agent orchestration.

Towns

A town is a persistent workspace where agents operate on your code. It maintains:

• Configuration — models, merge strategy, review settings, custom instructions
• Agent state — which agents exist, what they're working on, their capabilities
• Work history — every bead that's been created, worked on, reviewed, and closed
• Rig connections — which repositories are connected and how they're configured

Think of a town as a team's workspace — it accumulates institutional knowledge over time. Agents in your town learn from the history of what's been built, reviewed, and merged.

A town can be personal (owned by you) or organizational (shared across a team).

Beads

A bead is the fundamental unit of work. Every task, review, and coordination action is represented as a bead with a lifecycle:

Bead Types

Convoys

A convoy is a multi-bead workflow where tasks can depend on each other. Instead of slinging isolated tasks, convoys let you express complex work as a directed graph.

When you create a convoy, you define:

• Tasks — what needs to be done (each becomes a bead)
• Dependencies — which tasks must complete before others can start
• Feature branch — a shared branch that convoy work lands on

The reconciler ensures beads are only dispatched when their dependencies are met. This means agents naturally build on each other's work.

Staged Convoys

Convoys can be staged — created but not started immediately. This lets you review the plan before agents begin executing. Un-stage when you're ready to go.

Rigs

A rig connects a repository to your town. Each rig has:

• Its own set of agents (polecats, refinery)
• Branch configuration (default branch, merge target)
• Override settings (model, review mode, merge strategy)

A town can have multiple rigs — useful when your project spans several repositories.

Agents

Agents are the workers in your town. Each has a specialized role:

Polecats (Coding Agents)

Polecats do the actual software engineering:

• Read and understand your codebase
• Write code changes in isolated git worktrees
• Run tests and commands to verify their work
• Push branches when done

Multiple polecats can work in parallel on different beads. The default is 2 per rig, configurable up to 5+.

Each polecat gets its own git worktree — they never conflict with each other or with your local development.

The Refinery (Review Agent)

The refinery is the quality gate. When a polecat finishes a bead:

1. The refinery reviews the diff
2. Checks for issues, style violations, missing tests
3. Either approves and merges or sends feedback
4. If feedback is sent, the polecat revises and resubmits

This creates a micro-adversarial loop — one agent writes, another critiques, forcing iterative improvement before code lands.

The Mayor (Coordination Agent)

The mayor is your interface to the town:

• Plans convoys from high-level descriptions
• Reports on status and progress
• Triages issues and escalations
• Manages agent configuration
• Answers questions about the codebase and work history

The mayor runs persistently — always available for conversation.

The Reconciler

The reconciler is the engine that drives the town forward. It runs on every alarm tick (every 5 seconds when work is active) and:

1. Drains events — agent completions, status changes, failures
2. Evaluates rules — which beads need agents, which convoys are ready to advance
3. Emits actions — dispatch an agent, create a review, update convoy progress
4. Enforces invariants — no double-dispatch, no orphaned hooks, bounded retries

You don't interact with the reconciler directly — it's the autonomous engine that keeps the town moving.

The Micro-Adversarial Loop

The most powerful concept in Gas Town is the micro-adversarial loop. Rather than trusting a single agent's output, every piece of work goes through an adversarial cycle:

This pattern compounds when combined with convoys:

1. Bead 1: Explore the codebase → reviewed → merged to convoy branch
2. Bead 2: Design the schema (builds on bead 1's context) → reviewed → merged
3. Bead 3: Implement the feature (builds on beads 1+2) → reviewed → merged
4. Landing review: The full convoy branch is reviewed as a cohesive unit before merging to main

At every stage, work is critiqued and refined. Combined with Kilo's Code Review product, this creates a pipeline where code is reviewed multiple times by different agents with different perspectives before it ever reaches your main branch.

How It All Fits Together

app.kilo.ai/gastown/town