Choo Choo

🚂 Choo! Choo! - hits you like a freight train!

Documentation | Claude Plugin | Codex Plugin | Cursor Plugin

• What is Choo! Choo!?
• Design Thesis
• Safety Warning
• Project Structure
• Getting Started
  • Requirements
  • Runner Installation
  • Agentic Coding Tool Plugin
  • Your First Choo! Choo! Run
• Further Reading

---

What is Choo! Choo!?

Choo! Choo! is a Ralph Coding toolset forked off of Choo Choo Ralph by M.J. Meyer and based on the Ralph Wiggum Technique.

Choo! Choo! translates product requirements documents (PRDs) to autonomous work handled by AI coding agents in four steps:

• Plan - You plan a new feature
• Spec - Agent creates a specification, you review
• Pour - Agent creates actionable tickets and stores them in a DB
• Loop - Agent executes the tickets in a loop

flowchart LR
    subgraph You
        Plan["🧠 **Plan**<br/>Write a PRD or<br/>feature plan"]
    end

    subgraph Plugin["Plugin (Spec & Pour)"]
        Spec["📋 **Spec**<br/>Agent generates spec,<br/>you review"]
        Pour["🫗 **Pour**<br/>Agent breaks spec<br/>into granular beads"]
    end

    subgraph Runner["Runner (choochoo CLI)"]
        Loop["🚂 **Loop**<br/>Autonomous execution:<br/>work → inspect →<br/>merge → next"]
    end

    Plan -->|"PRD"| Spec
    Spec -->|"reviewed spec"| Pour
    Spec -->|"refine"| Spec
    Pour -->|"beads"| Loop
    Loop -->|"working code"| Done["✅ Done"]

Loading

The runner loop is autonomous. It processes a compound (linear chain of molecules) one at a time:

flowchart LR
    subgraph runner_pre ["Runner"]
        Pick["Pick molecule<br/>(compound cursor)"]
        Worktree["Create<br/>worktree"]
    end

    subgraph agent ["Agent (isolated worktree)"]
        Read["Read bead<br/>(bd show)"]
        Work["Work through<br/>steps"]
        Close["Close steps<br/>(bd close)"]
    end

    subgraph runner_post ["Runner"]
        Inspect["Inspector<br/>(acceptance criteria)"]
        Merge["Refinery<br/>(ff-only merge)"]
        Next["Advance cursor"]
    end

    Pick --> Worktree
    Worktree --> Read
    Read --> Work
    Work --> Close
    Close --> Inspect
    Inspect -->|pass| Merge
    Merge --> Next
    Next -->|"next molecule"| Pick
    Inspect -->|"fail (retries left)"| Read
    Inspect -->|"fail (max retries)"| Rejected["🚫 Rejected"]

Loading

Choo! Choo! currently supports the following agentic coding tools:

• Claude Code
• Cursor
• Codex (deprecated)

---

Design Thesis

The original Choo Choo Ralph 051ee8 follows the following thesis:

Most autonomous coding setups fall into two traps:

Too simple — Run Claude in a loop, hope for the best, watch it spiral when something breaks Too complex — Build elaborate orchestration that's harder to debug than the code it writes

[...]

The thesis: Simple loop + structured workflows + persistent memory = autonomous coding that actually works.

We wish to extend this further by adding bells and whistles to the original concept until we're trespassing to too complex territory:

• Dedicated runner - No more installing shell scripts
• Git worktrees - Each molecule runs in an isolated worktree; the agent can only damage its own copy
• Acceptance criteria - Machine-checkable CI commands; throw the task back to the agent on failure
• Inspector + Refinery - Automated verification and fast-forward merge gates
• Compound model - Linear chain of molecules processed sequentially, with handoff support
• Multi-backend - Claude Code, Codex, and Cursor support

The tooling consists of two major building blocks: the Choo! Choo! CLI choochoo (the runner) and the Choo! Choo! plugin for your favorite agentic coding tool (spec, pour, install).

---

Safety Warning

All backends are launched in dangerous/YOLO permissions mode by default. The worktree provides isolation, but only use Choo! Choo! in a properly sandboxed environment — agents can still leak sensitive information.

Important

By using this project, you accept full responsibility for any consequences.

I only use Choo! Choo! in a VM with an outbound firewall. Domains required for tool installation and tests are manually whitelisted.

---

Project Structure

• This repository contains the Choo! Choo! runner (src/choochoo/) and documentation
• https://github.com/maltekliemann/choochoo-plugin contains the plugins for the supported ACTs

---

Getting Started

Requirements

Choo! Choo! requires the following tools:

• Beads >= v0.58.0 (Dolt-only; SQLite backend was removed in 0.58). Dolt is bundled inside the bd binary — no separate install needed. Install via one of:
  • brew install beads (recommended)
  • npm install -g @beads/bd
  • curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
  • See INSTALLING.md for all options
• Python 3.10 and either pip or uv
• Agentic coding tool (Claude Code, Codex, or Cursor)

Runner Installation

To install the Choo! Choo! runner, execute one of the following:

• (Recommended) just install (if you have just and uv)
• uv tool install . (if you have uv)
• pip install . (if you have pip)

You can now run choochoo in terminal.

Agentic Coding Tool Plugin

You also need the Choo! Choo! plugin for your agentic coding tool to execute the spec and pour steps. Install the plugin by following the steps in one of the supported ACTs:

• Claude Code: https://github.com/maltekliemann/choochoo-claude
• Codex: https://github.com/maltekliemann/choochoo-codex
• Cursor: https://github.com/maltekliemann/choochoo-cursor

Your First Choo! Choo! Run

1. Go to your project and open your ACT (claude, codex, open Cursor IDE)
2. Use the choochoo-install command/skill to let your agent guide you through the setup
3. Write a PRD new-feature.md for a new feature in your project
4. Use choochoo-spec new-feature.md and let your agent create a specification
5. Review the spec and make change requests using the XML <review> tag
6. Continue to call choochoo-spec and review until you are satisfied
7. Use choochoo-pour to let your agent create tickets (larger tasks will be broken into multiple molecules, chained in a linear compound)
8. Run choochoo — you should see something like this:

🚂 Choo! Choo!

  📂 Logs: /home/user/.local/state/choochoo/log
  Loading compound...

  ○ proj-mol-abc  Add login form with validation
  ○ proj-mol-def  Implement auth API endpoint
  ○ proj-mol-ghi  Add password reset flow

  Compound: 3 molecules, 15 steps total

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[0:03] ▶ Molecule 1/3: proj-mol-abc — Add login form with validation (5 steps)
[0:03]   🌿 Worktree created: .choochoo/worktrees/proj-mol-abc
[0:03]   🤖 Agent started (pid: 12345)
[0:09]       🧠 Let me read the root bead first...
[0:12]       🗣️ I'll implement the login form component...

---

Further Reading

• Documentation — full reference (concepts, CLI, config, troubleshooting)
• Original Design Doc - this was used to spec and pour Choo! Choo!
• Ralph Wiggum as a "software engineer"
• 11 Tips For AI Coding With Ralph Wiggum
• Effective harnesses for long-running agents