f43c01de4e
- Rewrite vision.md with enterprise cognitive processing framing - Expand README with comprehensive project overview - Remove internal strategic references from merge-queue-design.md - Position Gas Town as "IDE of 2026" for AI agent orchestration Key messaging: - Enterprise-grade cognitive processing machine - Molecules as structured workflow guardrails - Nondeterministic idempotence for crash recovery - Beads as unified control/data plane - Hierarchical auditability and observability 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
158 lines
4.3 KiB
Markdown
158 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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](docs/architecture.md) for comprehensive documentation.
|
|
|
|
## Molecules
|
|
|
|
Molecules are structured workflow templates:
|
|
|
|
```markdown
|
|
## 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](https://github.com/steveyegge/beads) for issue tracking and coordination:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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](https://github.com/steveyegge/gastown-py) for the Python version.
|
|
|
|
## Documentation
|
|
|
|
- [Architecture](docs/architecture.md) - System design and concepts
|
|
- [Vision](docs/vision.md) - Where Gas Town is going
|
|
- [Federation](docs/federation-design.md) - Multi-machine coordination
|
|
- [Merge Queue](docs/merge-queue-design.md) - Refinery and integration
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Build
|
|
go build -o gt ./cmd/gt
|
|
|
|
# Test
|
|
go test ./...
|
|
|
|
# Install locally
|
|
go install ./cmd/gt
|
|
```
|
|
|
|
## Related
|
|
|
|
- [beads](https://github.com/steveyegge/beads) - Issue tracking for AI agents
|
|
- [gastown-py](https://github.com/steveyegge/gastown-py) - Python version (reference)
|
|
|
|
## License
|
|
|
|
MIT
|