johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: humility pass - frame as exploration, not declaration

Browse Source 
- Remove "IDE of 2026" and "Integrated Delegation Engine" claims
- Rename "Core Innovations" to "Ideas We're Exploring"
- Remove "Universal" from data plane and propulsion docs
- Add experimental status badges
- Frame concepts as discovery, invite others to explore

Closes gt-qvn7.5.2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-24 17:57:04 -08:00
parent b77e0fe09a
commit 5e9b204d2b
6 changed files with 87 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
README.md
View File

@@ -1,21 +1,19 @@
# Gas Town
**The IDE of 2026** - not Integrated Development Environment, but **Integrated Delegation Engine**.
> **Status**: Experimental (v0.1) - We're exploring these ideas and invite you to explore with us.
Gas Town turns Claude Code (the Steam Engine) into a Steam Train, with Beads as the globally distributed railway network. Workers spawn, work molecules, submit to merge queues, and get cleaned up - all autonomously.
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.
## The Vision
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 of work)
Beads = Railroad Tracks (the persistent ledger)
```
**Core principle: Gas Town is a Village.**
Not a rigid hierarchy with centralized monitoring, but an anti-fragile village where every agent understands the whole system and can help any neighbor. If you see something stuck, you can help. The village heals itself through distributed awareness.
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.
## Install
@@ -49,11 +47,15 @@ Town (~/gt/)
## Key Concepts
Ideas we're exploring:
- **Molecular Chemistry of Work**: Protos (templates) → Mols (flowing work) → Wisps (ephemeral) → Digests (outcomes)
- **Beads as Universal Data Plane**: Git-backed, human-readable, fractal ledger ([github.com/steveyegge/beads](https://github.com/steveyegge/beads))
- **Antifragility**: Self-monitoring village, not centralized hierarchy
- **Propulsion Principle**: Agents pull work from molecules, don't wait for commands
- **Nondeterministic Idempotence**: Any worker can continue any molecule after crashes
- **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

29
docs/architecture.md
View File

@@ -108,32 +108,29 @@ Gas Town has four AI agent roles:
| **Refinery** | Per-rig | Merge queue processing, PR review, integration |
| **Polecat** | Per-rig | Implementation work on assigned issues |
### Gas Town is a Village
### Village Architecture
**Core Operating Principle**: Gas Town is anti-fragile by design.
We're experimenting with a "village" model for agent coordination.
The anti-pattern we reject:
The pattern we're trying to avoid:
```
Centralized Monitor → watches all workers → single point of failure
→ fragile protocols → cascading failures
```
The pattern we embrace:
The pattern we're exploring:
```
Every worker → understands the whole → can help any neighbor
→ peek is encouraged → distributed awareness
→ ant colony without murder → self-healing system
```
**Key properties:**
**Properties we're building toward:**
- **Distributed awareness**: Every agent understands the system deeply
- **Distributed awareness**: Agents understand the system, not just their task
- **Mutual monitoring**: Any agent can peek at any other agent's health
- **Collective intervention**: If you see something stuck, you can help
- **No single point of failure**: The village survives individual failures
- **Organic healing**: Problems get fixed by whoever notices them first
This is an ant colony, except the ants don't kill defective members - they help them recover. Workers who crash are respawned. Workers who get stuck are nudged. Workers who need help receive it.
Whether this achieves actual resilience at scale is still being tested.
**Practical implications:**
@@ -215,11 +212,13 @@ sync-branch: beads-sync # Separate branch for beads commits
**Why sync-branch?** When multiple agents share a beads database, using a dedicated sync branch prevents beads commits from interleaving with code commits on feature branches.
#### Beads as Universal Data Plane (and Control Plane)
#### Beads as Data Plane
Beads is the data plane for ALL Gas Town operations. Everything flows through beads.
Gas Town uses Beads for persistence. We've combined the data plane and control plane:
- Traditional systems separate "what's stored" from "what to do next"
- We store both in beads, so agent state survives crashes
**Key architectural insight**: Gas Town intentionally blurs the line between data plane and control plane. In traditional systems:
In traditional systems:
- **Data plane**: Stores information (issues, messages)
- **Control plane**: Coordinates behavior (what to do next, who does what)
@@ -745,9 +744,9 @@ gt spawn --issue gt-xyz --molecule mol-engineer-in-box
### Why Molecules?
**The core value proposition: Nondeterministic Idempotence**
**Goal: Nondeterministic Idempotence**
Molecules guarantee that any workflow, once started, will eventually complete correctly - even through crashes, context compaction, and agent restarts. This is what enables Gas Town to run autonomously for extended periods.
The idea is that workflows can survive crashes, context compaction, and restarts because state is stored externally in beads, not in agent memory.
1. **Crash recovery**: Agent dies mid-workflow? Restart and continue from last completed step. No work is lost.
2. **Context survival**: Claude's context compacts? Agent re-reads molecule state from beads and knows exactly where it was.

15
docs/beads-data-plane.md
View File

@@ -1,19 +1,16 @@
# Beads: The Universal Data Plane
# Beads as Data Plane
> **Status**: Canonical Architecture Documentation
> **Status**: Design documentation
> **See also**: [pinned-beads-design.md](pinned-beads-design.md), [propulsion-principle.md](propulsion-principle.md)
## Overview
Gas Town agents coordinate through a single, unified data store: **Beads**. Every
piece of agent state - work assignments, mail messages, molecules, hooks - lives
in beads as issues with consistent field semantics.
Gas Town agents coordinate through **Beads** - a git-backed issue tracker.
We store agent state (work assignments, mail, molecules, hooks) as beads issues.
This document explains the universal data model that powers agent coordination.
## How We Use It
## The Core Insight
Beads is not just an issue tracker. It's a **universal data plane** where:
We're treating beads as more than an issue tracker:
- **Work molecules** are issues with steps as child issues
- **Mail messages** are issues with sender/recipient encoded in fields

8
docs/propulsion-principle.md
View File

@@ -1,11 +1,11 @@
# The Universal Gas Town Propulsion Principle
# The Propulsion Principle
> **Status**: Canonical Theory-of-Operation Documentation
> **Status**: Design document (experimental)
> **See also**: [sling-design.md](sling-design.md) for implementation details
## The One Rule
## The Core Idea
Gas Town runs on a single, universal rule:
We're trying a simple rule for agent behavior:
> **If you find something on your hook, YOU RUN IT.**

9
docs/sling-design.md
View File

@@ -1,17 +1,16 @@
# The Sling: Gas Town's Universal Work Dispatch
# The Sling: Work Dispatch
> **Status**: Design Draft
> **Issue**: gt-z3qf
## The Propulsion Principle
Gas Town runs on one rule:
We're experimenting with a simple rule for agent behavior:
> **If you find something on your hook, YOU RUN IT.**
No decisions. No "should I?" Just ignition. This is the Universal Gas Town
Propulsion Principle. Every agent - polecat, deacon, witness, refinery - follows
this single rule.
No decisions. No "should I?" Just ignition. We call this the Propulsion
Principle - agents execute what's on their hook rather than deciding what to do.
```
Hook has work → Work happens.

124
docs/vision.md
View File

@@ -1,15 +1,14 @@
# Gas Town Vision: Core Innovations
# Gas Town: Ideas We're Exploring
> *"Work is fractal. Money is crystallized labor. Blockchain was the mechanism
> searching for its purpose."*
> **Status**: These are ideas we're experimenting with, not proven solutions.
> We're sharing them in case others find them useful or want to explore together.
Gas Town is the IDE of 2026 - not an Integrated Development Environment, but an
**Integrated Delegation Engine**. It turns Claude Code (the Steam Engine) into a
Steam Train, with Beads as the globally distributed railway network.
Gas Town is an experiment in multi-agent coordination. We use steam-age metaphors
to think about how work flows through a system of AI agents.
---
## Core Innovation 1: The Steam Engine Metaphor
## Idea 1: The Steam Engine Metaphor
```
Claude = Fire (the energy source)
@@ -31,27 +30,29 @@ ensuring nothing is lost.
---
## Core Innovation 2: Gas Town is a Village
## Idea 2: Village vs Hierarchy
**The anti-pattern we reject:**
We're exploring whether a "village" model works better than centralized monitoring.
**The pattern we're trying to avoid:**
```
Centralized Monitor → watches all workers → single point of failure
→ fragile protocols → cascading failures
```
**The pattern we embrace:**
**The pattern we're experimenting with:**
```
Every worker → understands the whole → can help any neighbor
→ peek is encouraged → distributed awareness
→ ant colony without murder → self-healing system
```
### The Antifragility Principle
### Aspiration: Antifragility
Gas Town is **anti-fragile by design**. Not merely resilient (bounces back from
stress), but anti-fragile (gets stronger from stress).
We're aiming for anti-fragility - a system that gets stronger from stress rather
than just surviving it. Whether we achieve this is an open question.
Key properties:
Properties we're trying to build:
- **Distributed awareness**: Every agent understands the system deeply
- **Mutual monitoring**: Any agent can peek at any other agent's health
@@ -87,7 +88,7 @@ Workers who need help receive it.
---
## Core Innovation 3: Rig, Cook, Run
## Idea 3: Rig, Cook, Run
Work in Gas Town flows through three phases:
@@ -173,37 +174,26 @@ This enables patterns like:
---
## Core Innovation 4: Beads as Universal Data Plane
## Idea 4: Beads as Data Plane
Beads is Git + Issues + Molecules in one human-readable format.
We use Beads (a separate project) as the persistence layer. It's Git + Issues
in one human-readable format.
**Key properties:**
- **Git-backed**: Cryptographic hashes, Merkle trees, distributed
- **Human-readable**: Markdown, auditable, trustworthy
- **Fractal**: Work at any scale (task → epic → project → organization)
- **Federated**: Multi-repo, multi-org, platform-agnostic
**Properties we liked:**
- **Git-backed**: Uses existing infrastructure
- **Human-readable**: You can read `.beads/` files directly
- **Portable**: No vendor lock-in
**The insight:**
> "Git IS already a blockchain (Merkle tree, cryptographic hashes, distributed
> consensus). Beads is what blockchain was meant to enable - not coin
> speculation, but a universal ledger of work and capability."
See [github.com/steveyegge/beads](https://github.com/steveyegge/beads) for more.
### The GUPP Principle
**Git as Universal Persistence Protocol**
### Git as Persistence
Everything persists through git:
- Issues are JSONL in `.beads/`
- Molecules are structured issues
- Mail is issues with labels
- Work history is commit history
- Entity chains are git histories
This means:
- Offline-first by default
- Distributed without infrastructure
- Auditable forever
- No vendor lock-in
This gives us offline-first operation and no infrastructure requirements.
### Control Plane = Data Plane
@@ -222,7 +212,7 @@ There is no separate orchestrator - Beads IS the orchestrator.
---
## Core Innovation 5: The Patrol System
## Idea 5: Patrol Loops
Gas Town runs on continuous monitoring loops called **patrols**.
@@ -262,11 +252,10 @@ squashes to a summary digest.
---
## Core Innovation 6: Propulsion Over Protocol
## Idea 6: Propulsion Over Protocol
**The Propulsion Principle**
Agents don't wait for explicit commands. They propel themselves through work:
We're experimenting with "pull-based" work where agents propel themselves
rather than waiting for explicit commands:
1. **Check hook/pin** - What's attached to me?
2. **Find next step** - What's ready in my molecule?
@@ -274,8 +263,7 @@ Agents don't wait for explicit commands. They propel themselves through work:
4. **Advance** - Close step, find next
5. **Exit properly** - One of four exit types
This is **pull-based work**, not push-based commands. The molecule IS the
instruction set. The agent IS the executor.
The idea is pull-based work: the molecule provides instructions, the agent executes.
### Hooks and Pins
@@ -311,9 +299,9 @@ The polecat never exits directly - it waits to be killed by the Witness.
---
## Core Innovation 7: Nondeterministic Idempotence
## Idea 7: Nondeterministic Idempotence
The key property enabling autonomous operation:
An idea we're exploring for crash recovery:
- **Deterministic structure**: Molecule defines exactly what steps exist
- **Nondeterministic execution**: Any worker can execute any ready step
@@ -403,43 +391,23 @@ The flywheel spins. The village watches itself. The train keeps running.
---
## Why "IDE of 2026"?
## What We're Building Toward
The IDE evolved from text editor → syntax highlighting → autocomplete → AI suggestions.
We're interested in exploring AI as collaborator rather than just assistant.
Instead of AI suggesting code, what if AI could complete tasks while humans
review the outcomes?
The next evolution isn't better suggestions - it's **AI as worker, not assistant**.
| 2024 IDE | 2026 IDE (Gas Town) |
|----------|---------------------|
| AI suggests code | AI writes code |
| Human reviews suggestions | Human reviews pull requests |
| AI helps with tasks | AI completes tasks |
| Single agent | Coordinated village |
| Context in memory | Context in Beads |
| Manual quality checks | Molecule-enforced gates |
Gas Town is what happens when you treat AI agents as employees, not tools.
This is early-stage experimentation. Some of it works, much of it doesn't yet.
We're sharing it in case the ideas are useful to others.
---
## The Vision
## Summary
Gas Town is the **Integrated Delegation Engine**.
Gas Town explores:
- Multi-agent coordination via "molecules" of work
- Git-backed persistence via Beads
- Distributed monitoring via the "village" model
- Crash recovery via nondeterministic idempotence
For developers today. For all knowledge workers tomorrow.
The world has never had a system where:
- Work is fractal and composable
- Execution is distributed and self-healing
- History is permanent and auditable
- Agents are autonomous yet accountable
- The village watches itself
Beads is the ledger.
Gas Town is the execution engine.
The village watches itself.
The train keeps running.
---
*"If you're not a little bit scared, you're not paying attention."*
We don't know if these ideas will pan out. We invite you to explore with us.