ralph-beads-jq

Choo Choo Ralph

Quick Start • What You Get • Why Beads • Documentation

Relentless like a train. Persistent like Ralph Wiggum. Ships code while you sleep.

🧪 Experimental — This workflow is actively tested on real projects. Smaller, verified tasks trade higher Claude Code usage for more reliable outcomes. Your mileage may vary—I'd love feedback on what works and what doesn't.

---

What is Choo Choo Ralph?

A Claude Code plugin that turns your plans into autonomous, verified work—designed for teams, not just side projects.

Most Ralph implementations use GitHub Issues (latency), scattered markdown files (messy), or monolithic JSON (doesn't scale). Choo Choo Ralph uses Beads—a git-native task tracker where every task has an ID, workflows have real dependencies, and everything syncs through git the way your team already works.

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

---

The Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   1. Plan   │ ──▶ │  2. Spec    │ ──▶ │  3. Pour    │ ──▶ │  4. Ralph   │ ──▶ │ 5. Harvest  │
│    (you)    │     │  (you + AI) │     │    (AI)     │     │    (AI)     │     │ (you + AI)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

1. Plan — Write what you want to build (this part is yours)
2. Spec — AI transforms it into structured tasks; you review
3. Pour — Tasks become beads with workflows and dependencies
4. Ralph — The loop runs autonomously until done
5. Harvest — Extract learnings into skills, docs, or CLAUDE.md

---

What You Get

• Verified, not vibes — Health checks before implementing, tests after, browser verification when needed
• Team-friendly — Git-native sync, no API latency, works with how your team already collaborates
• Traceable — Bead IDs link commits to tasks, learnings to work. Full history of what happened where.
• Structured phases — Bearings → Implement → Verify → Commit (not just "do the thing")
• Bounded context — Each task carries its own history via Beads, no context window bloat
• Compounding knowledge — Agents capture learnings as they work; harvest them into skills and docs that make future sessions smarter
• Customizable workflows — Formulas and scripts are yours to modify, not hardcoded decisions

---

Quick Start

⚠️ Safety Warning — Read before running

Ralph runs Claude with --dangerously-skip-permissions, which allows it to execute commands without confirmation. This is powerful but risky.

We strongly recommend:

• Run in a Docker container or VM
• Use a machine that doesn't have your life's work on it
• Start with small, low-risk tasks until you trust the setup
• Review the formulas and scripts before running

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

Prerequisites: Claude Code, Beads (bd command), jq

# Install plugin
/plugin marketplace add mj-meyer/choo-choo-ralph
/plugin install choo-choo-ralph@choo-choo-ralph

# Set up project
/choo-choo-ralph:install

# Generate spec from your plan
/choo-choo-ralph:spec plans/my-feature.md

# Review the spec, then pour into beads
/choo-choo-ralph:pour

# Start the loop
./ralph.sh

For the complete workflow, see docs/workflow.md.

---

The Problem

Most autonomous coding setups fall into two traps:

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

And most Ralph implementations work fine for side projects but break down for teams. GitHub Issues introduce API latency. Scattered markdown files don't scale. Big JSON files or progress trackers get clunky when multiple people are involved.

Choo Choo Ralph is designed for real teams. The outer loop is dead simple. The workflow inside each task is structured and verified. Every task has an ID that traces through to commits and learnings. And everything syncs through git—no extra infrastructure.

---

Why Beads?