gastown/README.md

Gas Town

Enterprise-grade cognitive processing for AI agent swarms.

Gas Town is a multi-agent workspace manager that coordinates AI coding agents working on software projects. It provides the infrastructure for spawning workers, processing work through structured workflows (molecules), and coordinating agents through a unified data plane (Beads).

The Idea

Traditional AI coding assistants help you write code. Gas Town writes code for you.

Instead of AI as autocomplete, Gas Town treats AI agents as workers:

• Polecats implement features and fix bugs
• Refineries review and merge code
• Witnesses manage worker lifecycle
• Mayors coordinate across projects

Work flows through molecules - structured workflow templates that encode quality gates, dependencies, and recovery checkpoints. Any worker can continue any workflow from where another left off.

Key Features

• Nondeterministic Idempotence: Workflows survive crashes, context compaction, and agent restarts
• Molecule-Based Quality: Structured workflows with built-in gates, not prompt-based instructions
• Unified Data Plane: All state in Beads (issues, messages, workflows) - queryable, auditable, persistent
• Hierarchical Coordination: Mayor → Witness → Refinery → Polecat chain of command
• Federation Ready: Multiple rigs across machines, coordinated through Beads sync

Quick Start

# Install
go install github.com/steveyegge/gastown/cmd/gt@latest

# Create a town (workspace)
gt install ~/gt --git

# Add a rig for your project
gt rig add myproject --remote=https://github.com/you/myproject.git

# Spawn a polecat to work on an issue
gt spawn --issue myproject-123 --molecule mol-engineer-in-box

Architecture

Town (~/gt/)
├── Mayor (global coordinator)
├── Rig: project-alpha
│   ├── Witness (lifecycle manager)
│   ├── Refinery (merge queue)
│   └── Polecats (workers)
│       ├── furiosa/
│       ├── nux/
│       └── slit/
└── Rig: project-beta
    └── ...

See docs/architecture.md for comprehensive documentation.

Molecules

Molecules are structured workflow templates:

## Molecule: engineer-in-box
Full workflow from design to merge.

## Step: design
Think carefully about architecture.
Write a brief design summary.

## Step: implement
Write the code. Follow codebase conventions.
Needs: design

## Step: test
Write and run tests. Cover edge cases.
Needs: implement

## Step: submit
Submit for merge via refinery.
Needs: test

Built-in molecules:

• mol-engineer-in-box - Full quality workflow (design → implement → review → test → submit)
• mol-quick-fix - Fast path for small changes (implement → test → submit)
• mol-research - Exploration workflow (investigate → document)

Beads

Gas Town uses Beads for issue tracking and coordination:

bd ready              # Show work ready to start
bd list --status=open # All open issues
bd show gt-123        # Issue details
bd create --title="Fix auth bug" --type=bug
bd close gt-123       # Mark complete

Commands

# Town management
gt install <path>     # Create new town
gt status             # Overall status
gt doctor             # Diagnose issues

# Rig management
gt rig add <name>     # Add project rig
gt rig list           # List rigs

# Worker management
gt spawn --issue <id> # Start polecat on issue
gt polecat list <rig> # List polecats

# Communication
gt mail inbox         # Check messages
gt mail send <addr>   # Send message

Status

Work in Progress - This is the Go rewrite of the Python gastown tool.

See gastown-py for the Python version.

Documentation

• Architecture - System design and concepts
• Vision - Where Gas Town is going
• Federation - Multi-machine coordination
• Merge Queue - Refinery and integration

Development

# Build
go build -o gt ./cmd/gt

# Test
go test ./...

# Install locally
go install ./cmd/gt

Related

• beads - Issue tracking for AI agents
• gastown-py - Python version (reference)

License

MIT