066ef722ae
- Fix slashes in agent identity causing invalid hook file paths (gt-vqhc) - Add Prerequisites section to README (gt-vzic) - Create CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md (gt-xbfw) - Update Install section for future package managers (gt-7wcf) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
107 lines
2.9 KiB
Markdown
107 lines
2.9 KiB
Markdown
# Gas Town
|
|
|
|
> **Status**: Experimental (v0.1) - We're exploring these ideas and invite you to explore with us.
|
|
|
|
Gas Town is an experiment in multi-agent coordination for Claude Code. It provides infrastructure for spawning workers, tracking work via molecules, and coordinating merges.
|
|
|
|
We think of it using steam-age metaphors:
|
|
|
|
```
|
|
Claude = Fire (the energy source)
|
|
Claude Code = Steam Engine (harnesses the fire)
|
|
Gas Town = Steam Train (coordinates engines on tracks)
|
|
Beads = Railroad Tracks (the persistent ledger)
|
|
```
|
|
|
|
The goal is a "village" architecture - not rigid hierarchy, but distributed awareness where agents can help neighbors when something is stuck. Whether this actually works at scale is something we're still discovering.
|
|
|
|
## Prerequisites
|
|
|
|
- **Go 1.23+** - For building from source
|
|
- **Git** - For rig management and beads sync
|
|
- **tmux** - Required for agent sessions (all workers run in tmux panes)
|
|
- **Claude Code CLI** - Required for agents (`claude` command must be available)
|
|
|
|
## Install
|
|
|
|
**From source (recommended for now):**
|
|
|
|
```bash
|
|
go install github.com/steveyegge/gastown/cmd/gt@latest
|
|
```
|
|
|
|
**Package managers (coming soon):**
|
|
|
|
```bash
|
|
# Homebrew (macOS/Linux)
|
|
brew install gastown
|
|
|
|
# npm (cross-platform)
|
|
npm install -g @anthropic/gastown
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Create a town (workspace)
|
|
gt install ~/gt
|
|
|
|
# Add a project rig
|
|
gt rig add myproject --remote=https://github.com/you/myproject.git
|
|
|
|
# Spawn a worker on an issue
|
|
gt spawn --issue myproject-123
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Town (~/gt/)
|
|
├── Mayor (global coordinator)
|
|
└── Rig: myproject
|
|
├── Witness (lifecycle manager)
|
|
├── Refinery (merge queue)
|
|
└── Polecats (workers)
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
Ideas we're exploring:
|
|
|
|
- **Molecular Chemistry of Work**: Protos (templates) → Mols (flowing work) → Wisps (ephemeral) → Digests (outcomes)
|
|
- **Beads**: Git-backed, human-readable ledger for tracking work ([github.com/steveyegge/beads](https://github.com/steveyegge/beads))
|
|
- **Village Model**: Distributed awareness instead of centralized monitoring
|
|
- **Propulsion Principle**: Agents pull work from molecules rather than waiting for commands
|
|
- **Nondeterministic Idempotence**: The idea that any worker can continue any molecule after crashes
|
|
|
|
Some of these are implemented; others are still aspirational. See docs for current status.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
gt status # Town status
|
|
gt rig list # List rigs
|
|
gt spawn --issue <id> # Start worker
|
|
gt mail inbox # Check messages
|
|
gt peek <worker> # Check worker health
|
|
gt nudge <worker> # Wake stuck worker
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Vision](docs/vision.md) - Core innovations and philosophy
|
|
- [Architecture](docs/architecture.md) - System design
|
|
- [Molecular Chemistry](docs/molecular-chemistry.md) - Work composition
|
|
- [Molecules](docs/molecules.md) - Workflow templates
|
|
|
|
## Development
|
|
|
|
```bash
|
|
go build -o gt ./cmd/gt
|
|
go test ./...
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|