{"id":37864727,"url":"https://github.com/mikehostetler/wreckit","last_synced_at":"2026-01-16T16:36:02.776Z","repository":{"id":332391503,"uuid":"1133151333","full_name":"mikehostetler/wreckit","owner":"mikehostetler","description":"My code is in danger!","archived":false,"fork":false,"pushed_at":"2026-01-13T18:46:01.000Z","size":357,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T18:46:58.545Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikehostetler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-13T00:34:07.000Z","updated_at":"2026-01-13T18:46:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikehostetler/wreckit","commit_stats":null,"previous_names":["mikehostetler/wreckit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mikehostetler/wreckit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehostetler%2Fwreckit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehostetler%2Fwreckit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehostetler%2Fwreckit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehostetler%2Fwreckit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikehostetler","download_url":"https://codeload.github.com/mikehostetler/wreckit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehostetler%2Fwreckit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T16:36:02.199Z","updated_at":"2026-01-16T16:36:02.760Z","avatar_url":"https://github.com/mikehostetler.png","language":"TypeScript","funding_links":[],"categories":["others","Autonomous Loop Runners","Implementations","Harnesses \u0026 orchestration"],"sub_categories":["Orchestrators \u0026 autonomous loops"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/wreckit.png\" alt=\"Wreck it Ralph Wiggum holding a sign 'MY CODE IS IN DANGER'\" width=\"1024\"\u003e\n\u003c/p\u003e\n\n## ⚡ Quickstart: Run Ralph Loops Now\n\nWant to run Ralph Wiggum loops right now? You need LLM API access. Ralph uses a lot of tokens, which gets expensive quickly.\n\n[Zai Coding Plan](https://z.ai/subscribe?ic=F8BPSXJHOC) is a great way to get access to a lot of tokens for a low price.\n\n**[Zai Coding Plan](https://z.ai/subscribe?ic=F8BPSXJHOC)** — 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](https://github.com/mikehostetler) and by using this link you help support my work on Wreckit).\n\n```bash\nnpm install -g wreckit \u0026\u0026 wreckit init\nwreckit ideas \u003c YOUR_IDEAS.md\nwreckit  # go touch grass\n```\n\nOnce you have API access, you can set up Claude Code to use the Zai API:\n\n👉 [Claude Code setup instructions](https://docs.z.ai/devpack/tool/claude)\n\n---\n\n# Wreck it Ralph Wiggum 🔨\n\n\u003e *\"I'm gonna wreck it!\"* — Wreck-It Ralph  \n\u003e *\"I'm in danger.\"* — Ralph Wiggum, also your codebase\n\n**Your AI agent, unsupervised, wrecking through your backlog while you sleep.**\n\n```bash\nwreckit ideas \u003c BACKLOG.md \u0026\u0026 wreckit  # go touch grass\n```\n\n---\n\n## What Is This\n\nA CLI that runs a **Ralph Wiggum Loop** over your roadmap:\n\n```\nideas → research → plan → implement → PR → done\n       └──────────────────────────────────┘\n         \"I'm helping!\" — the agent, probably\n```\n\nYou dump a text file of half-baked ideas. Wreckit turns them into researched, planned, implemented, and PR'd code. You review. Merge. Ship.\n\nIt's the [HumanLayer](https://github.com/humanlayer/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.\n\n**Files are truth.** Everything lives in `.wreckit/` as JSON and Markdown. Git-trackable. Inspectable. Resumable. No magic databases. No cloud sync. Just files.\n\n---\n\n## Quick Start\n\n```bash\n# Install the chaos\nnpm install -g wreckit\n\n# Initialize in your repo\ncd my-project\nwreckit init\n\n# Feed it ideas (literally anything)\nwreckit ideas \u003c IDEAS.md\n# or: echo \"add dark mode\" | wreckit ideas\n# or: wreckit ideas --file ROADMAP.md\n\n# Let Ralph loose\nwreckit\n\n# Go do something else. Come back to PRs.\n```\n\n---\n\n## The Loop\n\nEach item progresses through states:\n\n```\nraw → researched → planned → implementing → in_pr → done\n```\n\n| State | What Happened |\n|-------|---------------|\n| `raw` | Ingested, waiting for attention |\n| `researched` | Agent analyzed codebase, wrote `research.md` |\n| `planned` | Agent created `plan.md` + `prd.json` with user stories |\n| `implementing` | Agent coding through stories, committing as it goes |\n| `in_pr` | PR opened, awaiting your review |\n| `done` | Merged. Ralph did it. |\n\n### The Workflow\n\n1. **Research** — Agent reads your codebase thoroughly. Finds patterns. Documents file paths, conventions, integration points. Outputs `research.md`.\n\n2. **Plan** — Agent designs the solution. Breaks it into phases with success criteria. Creates user stories with acceptance criteria. Outputs `plan.md` + `prd.json`.\n\n3. **Implement** — Agent picks the highest priority story, implements it, runs tests, commits, marks it done. Repeats until all stories complete.\n\n4. **PR** — Agent opens a pull request. You review. You merge. You ship.\n\n---\n\n## CLI Commands\n\n### The Essentials\n\n| Command | What It Does |\n|---------|--------------|\n| `wreckit` | Run everything. TUI shows progress. |\n| `wreckit init` | Initialize `.wreckit/` in repo |\n| `wreckit ideas \u003c FILE` | Ingest ideas from stdin |\n| `wreckit status` | List all items with state |\n| `wreckit run \u003cid\u003e` | Run single item through all phases |\n| `wreckit next` | Run the next incomplete item |\n| `wreckit doctor` | Validate items, find issues |\n\n### Phase Commands (for debugging)\n\n| Command | Transition |\n|---------|------------|\n| `wreckit research \u003cid\u003e` | raw → researched |\n| `wreckit plan \u003cid\u003e` | researched → planned |\n| `wreckit implement \u003cid\u003e` | planned → implementing |\n| `wreckit pr \u003cid\u003e` | implementing → in_pr |\n| `wreckit complete \u003cid\u003e` | in_pr → done |\n\n### Flags\n\n| Flag | What |\n|------|------|\n| `--verbose` | More logs |\n| `--quiet` | Errors only |\n| `--no-tui` | Disable TUI (CI mode) |\n| `--dry-run` | Preview, don't execute |\n| `--force` | Regenerate artifacts |\n\n---\n\n## Configuration\n\nLives in `.wreckit/config.json`:\n\n```json\n{\n  \"schema_version\": 1,\n  \"base_branch\": \"main\",\n  \"branch_prefix\": \"wreckit/\",\n  \"agent\": {\n    \"command\": \"amp\",\n    \"args\": [\"--dangerously-allow-all\"],\n    \"completion_signal\": \"\u003cpromise\u003eCOMPLETE\u003c/promise\u003e\"\n  },\n  \"max_iterations\": 100,\n  \"timeout_seconds\": 3600\n}\n```\n\n### Agent Options\n\nWreckit supports two agent execution modes:\n\n#### SDK Mode (Recommended)\nUses the Claude Agent SDK directly for better performance and error handling:\n\n```json\n{\n  \"agent\": {\n    \"mode\": \"sdk\",\n    \"sdk_model\": \"claude-sonnet-4-20250514\",\n    \"sdk_max_tokens\": 8192,\n    \"sdk_tools\": [\"Read\", \"Edit\", \"Bash\", \"Glob\", \"Grep\"]\n  }\n}\n```\n\n#### Process Mode (Default)\nSpawns an external Claude Code process (backward compatible):\n\n**Amp:**\n```json\n{\n  \"agent\": {\n    \"mode\": \"process\",\n    \"command\": \"amp\",\n    \"args\": [\"--dangerously-allow-all\"],\n    \"completion_signal\": \"\u003cpromise\u003eCOMPLETE\u003c/promise\u003e\"\n  }\n}\n```\n\n**Claude:**\n```json\n{\n  \"agent\": {\n    \"mode\": \"process\",\n    \"command\": \"claude\",\n    \"args\": [\"--dangerously-skip-permissions\", \"--print\"],\n    \"completion_signal\": \"\u003cpromise\u003eCOMPLETE\u003c/promise\u003e\"\n  }\n}\n```\n\nSee [MIGRATION.md](./MIGRATION.md) for detailed migration guide.\n\n---\n\n## Folder Structure\n\n```\n.wreckit/\n├── config.json              # Global config\n├── index.json               # Registry of all items\n├── prompts/                 # Customizable prompt templates\n│   ├── research.md\n│   ├── plan.md\n│   └── implement.md\n└── \u003csection\u003e/\n    └── \u003cnnn\u003e-\u003cslug\u003e/\n        ├── item.json        # State and metadata\n        ├── research.md      # Codebase analysis\n        ├── plan.md          # Implementation plan\n        ├── prd.json         # User stories\n        ├── prompt.md        # Generated agent prompt\n        └── progress.log     # What the agent learned\n```\n\nItems are organized by section (e.g., `features/`, `bugs/`, `infra/`) with sequential numbering.\n\n---\n\n## Customization\n\n### Prompt Templates\n\nEdit files in `.wreckit/prompts/` to customize agent behavior:\n\n- `research.md` — How the agent analyzes your codebase\n- `plan.md` — How it designs solutions\n- `implement.md` — How it executes user stories\n\n### Template Variables\n\n| Variable | Description |\n|----------|-------------|\n| `{{id}}` | Item ID (e.g., `features/001-dark-mode`) |\n| `{{title}}` | Item title |\n| `{{section}}` | Section name |\n| `{{overview}}` | Item description |\n| `{{item_path}}` | Path to item folder |\n| `{{branch_name}}` | Git branch name |\n| `{{base_branch}}` | Base branch |\n| `{{completion_signal}}` | Agent completion signal |\n| `{{research}}` | Contents of research.md |\n| `{{plan}}` | Contents of plan.md |\n| `{{prd}}` | Contents of prd.json |\n| `{{progress}}` | Contents of progress.log |\n\n---\n\n## Example Session\n\n```bash\n$ cat IDEAS.md\nAdd dark mode toggle\nFix the login timeout bug\nMigrate auth to OAuth2\n\n$ wreckit ideas \u003c IDEAS.md\nCreated 3 items:\n  features/001-dark-mode-toggle\n  bugs/001-login-timeout\n  infra/001-oauth2-migration\n\n$ wreckit status\nID                              STATE\nfeatures/001-dark-mode-toggle   raw\nbugs/001-login-timeout          raw\ninfra/001-oauth2-migration      raw\n\n$ wreckit\n# TUI runs, agent researches, plans, implements...\n# You go do literally anything else\n\n$ wreckit status\nID                              STATE     PR\nfeatures/001-dark-mode-toggle   in_pr     #42\nbugs/001-login-timeout          in_pr     #43\ninfra/001-oauth2-migration      implementing\n\n$ # Review PRs, merge, done\n```\n\n---\n\n## Design Principles\n\n1. **Files are truth** — JSON + Markdown, git-trackable\n2. **Idempotent** — Re-run anything safely\n3. **Resumable** — Ctrl-C and pick up where you left off\n4. **Transparent** — Every prompt is inspectable and editable\n5. **Recoverable** — `wreckit doctor --fix` repairs broken state\n\n---\n\n## Cloud Sandboxes\n\nWreckit 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.\n\nWe recommend [Sprites](https://sprites.dev/) from Fly.io for cloud dev environments. Spin up a fleet of Ralphs, let them wreck in parallel.\n\n```bash\n# Each sandbox pulls the repo, runs one item\nwreckit next  # grabs the next incomplete item, runs it\n```\n\n---\n\n## Requirements\n\n- Node.js 18+\n- `gh` CLI (for GitHub PRs)\n- An AI agent:\n  - **SDK Mode** (recommended): Set `ANTHROPIC_API_KEY` environment variable\n  - **Process Mode**: [Amp](https://ampcode.com) or [Claude](https://claude.ai) CLI\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/mikehostetler/wreckit.git\ncd wreckit\nbun install\nbun run build\nbun run test\n```\n\n---\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Error |\n| 130 | Interrupted (Ctrl-C) |\n\n---\n\n## Acknowledgements\n\nThe \"Ralph Wiggum Loop\" methodology stands on the shoulders of giants:\n\n- [Ryan Carson](https://x.com/ryancarson) — for the Ralph pattern that inspired the core loop\n- [Geoff Huntley](https://x.com/GeoffreyHuntley) — for evangelizing the Ralph Wiggum agent pattern\n- [Dexter Horthy](https://x.com/dexhorthy) and the entire [HumanLayer](https://humanlayer.dev) team — for the Research → Plan → Implement workflow that makes agents actually useful\n- Everyone in the community teaching agents to stop vibing and start shipping\n\n---\n\n## License\n\nMIT\n\n---\n\n*\"My code is in danger!\"* — your codebase, nervously\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikehostetler%2Fwreckit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikehostetler%2Fwreckit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikehostetler%2Fwreckit/lists"}