Want to run Ralph Wiggum loops right now? You need LLM API access. Ralph uses a lot of tokens, which gets expensive quickly.
Zai Coding Plan is a great way to get access to a lot of tokens for a low price.
Zai Coding Plan — starts at $3/month, works with Claude Code, Amp, Cline, and 10+ coding tools. This link gets you 10% off (full disclosure: I'm @mikehostetler and by using this link you help support my work on Wreckit).
npm install -g wreckit && wreckit init
wreckit ideas < YOUR_IDEAS.md
wreckit # go touch grassOnce you have API access, you can set up Claude Code to use the Zai API:
👉 Claude Code setup instructions
"I'm gonna wreck it!" — Wreck-It Ralph
"I'm in danger." — Ralph Wiggum, also your codebase
Your AI agent, unsupervised, wrecking through your backlog while you sleep.
wreckit ideas < BACKLOG.md && wreckit # go touch grassA CLI that runs a Ralph Wiggum Loop over your roadmap:
ideas → research → plan → implement → PR → done
└──────────────────────────────────┘
"I'm helping!" — the agent, probably
You dump a text file of half-baked ideas. Wreckit turns them into researched, planned, implemented, and PR'd code. You review. Merge. Ship.
It's the HumanLayer Research → Plan → Implement workflow, fully automated. The agent researches your codebase, writes a detailed plan, then executes it story-by-story until there's a PR ready for your review.
Files are truth. Everything lives in .wreckit/ as JSON and Markdown. Git-trackable. Inspectable. Resumable. No magic databases. No cloud sync. Just files.
# Install the chaos
npm install -g wreckit
# Initialize in your repo
cd my-project
wreckit init
# Feed it ideas (literally anything)
wreckit ideas < IDEAS.md
# or: echo "add dark mode" | wreckit ideas
# or: wreckit ideas --file ROADMAP.md
# Let Ralph loose
wreckit
# Go do something else. Come back to PRs.Each item progresses through states:
raw → researched → planned → implementing → in_pr → done
| State | What Happened |
|---|---|
raw |
Ingested, waiting for attention |
researched |
Agent analyzed codebase, wrote research.md |
planned |
Agent created plan.md + prd.json with user stories |
implementing |
Agent coding through stories, committing as it goes |
in_pr |
PR opened, awaiting your review |
done |
Merged. Ralph did it. |
-
Research — Agent reads your codebase thoroughly. Finds patterns. Documents file paths, conventions, integration points. Outputs
research.md. -
Plan — Agent designs the solution. Breaks it into phases with success criteria. Creates user stories with acceptance criteria. Outputs
plan.md+prd.json. -
Implement — Agent picks the highest priority story, implements it, runs tests, commits, marks it done. Repeats until all stories complete.
-
PR — Agent opens a pull request. You review. You merge. You ship.
| Command | What It Does |
|---|---|
wreckit |
Run everything. TUI shows progress. |
wreckit init |
Initialize .wreckit/ in repo |
wreckit ideas < FILE |
Ingest ideas from stdin |
wreckit status |
List all items with state |
wreckit run <id> |
Run single item through all phases |
wreckit next |
Run the next incomplete item |
wreckit doctor |
Validate items, find issues |
| Command | Transition |
|---|---|
wreckit research <id> |
raw → researched |
wreckit plan <id> |
researched → planned |
wreckit implement <id> |
planned → implementing |
wreckit pr <id> |
implementing → in_pr |
wreckit complete <id> |
in_pr → done |
| Flag | What |
|---|---|
--verbose |
More logs |
--quiet |
Errors only |
--no-tui |
Disable TUI (CI mode) |
--dry-run |
Preview, don't execute |
--force |
Regenerate artifacts |
Lives in .wreckit/config.json:
{
"schema_version": 1,
"base_branch": "main",
"branch_prefix": "wreckit/",
"agent": {
"command": "amp",
"args": ["--dangerously-allow-all"],
"completion_signal": "<promise>COMPLETE</promise>"
},
"max_iterations": 100,
"timeout_seconds": 3600
}Wreckit supports two agent execution modes:
Uses the Claude Agent SDK directly for better performance and error handling:
{
"agent": {
"mode": "sdk",
"sdk_model": "claude-sonnet-4-20250514",
"sdk_max_tokens": 8192,
"sdk_tools": ["Read", "Edit", "Bash", "Glob", "Grep"]
}
}Spawns an external Claude Code process (backward compatible):
Amp:
{
"agent": {
"mode": "process",
"command": "amp",
"args": ["--dangerously-allow-all"],
"completion_signal": "<promise>COMPLETE</promise>"
}
}Claude:
{
"agent": {
"mode": "process",
"command": "claude",
"args": ["--dangerously-skip-permissions", "--print"],
"completion_signal": "<promise>COMPLETE</promise>"
}
}See MIGRATION.md for detailed migration guide.
.wreckit/
├── config.json # Global config
├── index.json # Registry of all items
├── prompts/ # Customizable prompt templates
│ ├── research.md
│ ├── plan.md
│ └── implement.md
└── <section>/
└── <nnn>-<slug>/
├── item.json # State and metadata
├── research.md # Codebase analysis
├── plan.md # Implementation plan
├── prd.json # User stories
├── prompt.md # Generated agent prompt
└── progress.log # What the agent learned
Items are organized by section (e.g., features/, bugs/, infra/) with sequential numbering.
Edit files in .wreckit/prompts/ to customize agent behavior:
research.md— How the agent analyzes your codebaseplan.md— How it designs solutionsimplement.md— How it executes user stories
| Variable | Description |
|---|---|
{{id}} |
Item ID (e.g., features/001-dark-mode) |
{{title}} |
Item title |
{{section}} |
Section name |
{{overview}} |
Item description |
{{item_path}} |
Path to item folder |
{{branch_name}} |
Git branch name |
{{base_branch}} |
Base branch |
{{completion_signal}} |
Agent completion signal |
{{research}} |
Contents of research.md |
{{plan}} |
Contents of plan.md |
{{prd}} |
Contents of prd.json |
{{progress}} |
Contents of progress.log |
$ cat IDEAS.md
Add dark mode toggle
Fix the login timeout bug
Migrate auth to OAuth2
$ wreckit ideas < IDEAS.md
Created 3 items:
features/001-dark-mode-toggle
bugs/001-login-timeout
infra/001-oauth2-migration
$ wreckit status
ID STATE
features/001-dark-mode-toggle raw
bugs/001-login-timeout raw
infra/001-oauth2-migration raw
$ wreckit
# TUI runs, agent researches, plans, implements...
# You go do literally anything else
$ wreckit status
ID STATE PR
features/001-dark-mode-toggle in_pr #42
bugs/001-login-timeout in_pr #43
infra/001-oauth2-migration implementing
$ # Review PRs, merge, done- Files are truth — JSON + Markdown, git-trackable
- Idempotent — Re-run anything safely
- Resumable — Ctrl-C and pick up where you left off
- Transparent — Every prompt is inspectable and editable
- Recoverable —
wreckit doctor --fixrepairs broken state
Wreckit is designed for multi-actor parallelism — spin up multiple sandboxes, each working on different items from the same repo. The file-based state in .wreckit/ means no conflicts, no coordination headaches.
We recommend Sprites from Fly.io for cloud dev environments. Spin up a fleet of Ralphs, let them wreck in parallel.
# Each sandbox pulls the repo, runs one item
wreckit next # grabs the next incomplete item, runs it- Node.js 18+
ghCLI (for GitHub PRs)- An AI agent:
git clone https://github.com/mikehostetler/wreckit.git
cd wreckit
bun install
bun run build
bun run test| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error |
| 130 | Interrupted (Ctrl-C) |
The "Ralph Wiggum Loop" methodology stands on the shoulders of giants:
- Ryan Carson — for the Ralph pattern that inspired the core loop
- Geoff Huntley — for evangelizing the Ralph Wiggum agent pattern
- Dexter Horthy and the entire HumanLayer team — for the Research → Plan → Implement workflow that makes agents actually useful
- Everyone in the community teaching agents to stop vibing and start shipping
MIT
"My code is in danger!" — your codebase, nervously