A CLI tool for turning ideas into automated PRs through an autonomous agent loop
npm install wreckit

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).
``bash`
npm install -g wreckit && wreckit init
wreckit ideas < YOUR_IDEAS.md
wreckit # go touch grass
Once 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.
`bash`
wreckit ideas < BACKLOG.md && wreckit # go touch grass
---
A 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.
---
`bashInstall the chaos
npm install -g wreckit
---
The Loop
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. |$3
1. Research ā Agent reads your codebase thoroughly. Finds patterns. Documents file paths, conventions, integration points. Outputs
research.md.2. Plan ā Agent designs the solution. Breaks it into phases with success criteria. Creates user stories with acceptance criteria. Outputs
plan.md + prd.json.3. Implement ā Agent picks the highest priority story, implements it, runs tests, commits, marks it done. Repeats until all stories complete.
4. PR ā Agent opens a pull request. You review. You merge. You ship.
---
CLI Commands
$3
| 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 | Run single item through all phases |
| wreckit next | Run the next incomplete item |
| wreckit doctor | Validate items, find issues |$3
| Command | Transition |
|---------|------------|
|
wreckit research | raw ā researched |
| wreckit plan | researched ā planned |
| wreckit implement | planned ā implementing |
| wreckit pr | implementing ā in_pr |
| wreckit complete | in_pr ā done |$3
| Flag | What |
|------|------|
|
--verbose | More logs |
| --quiet | Errors only |
| --no-tui | Disable TUI (CI mode) |
| --dry-run | Preview, don't execute |
| --force | Regenerate artifacts |---
Configuration
Lives in
.wreckit/config.json:`json
{
"schema_version": 1,
"base_branch": "main",
"branch_prefix": "wreckit/",
"agent": {
"command": "amp",
"args": ["--dangerously-allow-all"],
"completion_signal": "COMPLETE "
},
"max_iterations": 100,
"timeout_seconds": 3600
}
`$3
Wreckit supports two agent execution modes:
#### SDK Mode (Recommended)
Uses the Claude Agent SDK directly for better performance and error handling:
`json
{
"agent": {
"mode": "sdk",
"sdk_model": "claude-sonnet-4-20250514",
"sdk_max_tokens": 8192,
"sdk_tools": ["Read", "Edit", "Bash", "Glob", "Grep"]
}
}
`#### Process Mode (Default)
Spawns an external Claude Code process (backward compatible):
Amp:
`json
{
"agent": {
"mode": "process",
"command": "amp",
"args": ["--dangerously-allow-all"],
"completion_signal": "COMPLETE "
}
}
`Claude:
`json
{
"agent": {
"mode": "process",
"command": "claude",
"args": ["--dangerously-skip-permissions", "--print"],
"completion_signal": "COMPLETE "
}
}
`See MIGRATION.md for detailed migration guide.
---
Folder Structure
`
.wreckit/
āāā config.json # Global config
āāā index.json # Registry of all items
āāā prompts/ # Customizable prompt templates
ā āāā research.md
ā āāā plan.md
ā āāā implement.md
āāā /
āāā -/
āāā 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.---
Customization
$3
Edit files in
.wreckit/prompts/ to customize agent behavior:-
research.md ā How the agent analyzes your codebase
- plan.md ā How it designs solutions
- implement.md ā How it executes user stories$3
| 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 |---
Example Session
`bash
$ 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
`---
Design Principles
1. Files are truth ā JSON + Markdown, git-trackable
2. Idempotent ā Re-run anything safely
3. Resumable ā Ctrl-C and pick up where you left off
4. Transparent ā Every prompt is inspectable and editable
5. Recoverable ā
wreckit doctor --fix repairs broken state---
Cloud Sandboxes
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.
`bash
Each sandbox pulls the repo, runs one item
wreckit next # grabs the next incomplete item, runs it
`---
Requirements
- Node.js 18+
-
gh CLI (for GitHub PRs)
- An AI agent:
- SDK Mode (recommended): Set ANTHROPIC_API_KEY environment variable
- Process Mode: Amp or Claude CLI---
Development
`bash
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