Core Concepts
Gas Town is built on a small set of powerful primitives. Understanding these concepts is the key to effective use of the system, whether you are a human operator or an AI agent.
Overview
| Concept | Purpose | Primary CLI |
|---|---|---|
| Beads | AI-native, git-backed issue tracking | bd |
| Hooks | Persistent work state that survives crashes | gt hook, gt sling |
| Convoys | Batch tracking of related work items | gt convoy |
| Molecules & Formulas | Multi-step workflow orchestration | gt mol, gt formula |
| Gates | Async coordination and synchronization | bd gate |
| Rigs | Project containers wrapping git repositories | gt rig |
| The MEOW Stack | Layered abstraction model for work organization | -- |
| GUPP & NDI | Core design principles for reliability at scale | -- |
How They Fit Together
The Lifecycle at a Glance
A typical unit of work moves through these primitives in order:
- Bead is created to track an issue or task
- Beads are bundled into a Convoy for batch tracking
- A bead is slung to an agent, attaching it to the agent's Hook
- The agent executes a Molecule (instantiated from a Formula) that defines the work steps
- If a step requires an async wait, a Gate pauses execution until a condition is met
- All of this runs inside a Rig -- the project container that hosts the git repository and agent infrastructure
Mental Model
Think of Gas Town as a shipping operation. Beads are packages, Convoys are trucks, Hooks are loading docks, Molecules are delivery instructions, Gates are traffic lights, and Rigs are warehouses.
Design Principles
These concepts share several common design principles, rooted in GUPP & NDI:
- Git as ground truth -- All persistent state lives in git or git-adjacent storage (SQLite, worktrees, JSONL)
- CLI-first -- Every operation is available through the command line, making it natural for both humans and AI agents
- Crash-safe -- State is designed to survive crashes, restarts, compaction, and handoffs between sessions (see Hooks and GUPP)
- Forward-only progress -- Operations move the system forward or leave it unchanged, never backward (GUPP)
- Discovery over tracking -- Agents observe reality each patrol cycle rather than maintaining fragile in-memory state
- Composable -- Primitives combine to form complex workflows without a monolithic orchestration layer