Skip to content
Back to search

opencode-ralph-wiggum

Type `ralph "prompt"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/th0rgal--opencode-ralph-wiggum/badge.svg)](/listings/th0rgal--opencode-ralph-wiggum)

HTML

<a href="/listings/th0rgal--opencode-ralph-wiggum"><img src="/api/listings/th0rgal--opencode-ralph-wiggum/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** - [Bun](https://bun.sh) runtime - At least one AI coding agent CLI: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's Claude Code CLI - [Codex](https://github.com/openai/codex) — OpenAI's Codex CLI - [Copilot CLI](https://github.com/github/copilot-cli) — GitHub's Copilot CLI - [Cursor Agent](https://cursor.com/cli/) — Cursor's headless Agent CLI - [Qwen Code](https://github.com/QwenLM/qwen-code) — Alibaba's Qwen Code CLI - [OpenCode](https://opencode.ai) — Open-source AI coding assistant

npm (recommended)

npm install -g @th0rgal/ralph-wiggum

Bun

bun add -g @th0rgal/ralph-wiggum

From source

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
./install.sh
git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
.\install.ps1

This installs the `ralph` CLI command globally.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 921 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <h1 align="center">Open Ralph Wiggum</h1>
  3. <h3 align="center">Autonomous Agentic Loop for Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code & OpenCode</h3>
  4. </p>
  5. <p align="center">
  6. <img src="screenshot.webp" alt="Open Ralph Wiggum - Iterative AI coding loop for multiple AI coding agents" />
  7. </p>
  8. <p align="center">
  9. <em>Works with <b>Claude Code</b>, <b>OpenAI Codex</b>, <b>Copilot CLI</b>, <b>Cursor Agent</b>, <b>Qwen Code</b>, and <b>OpenCode</b> — switch agents with <code>--agent</code>.</em><br>
  10. <em>Based on the <a href="https://ghuntley.com/ralph/">Ralph Wiggum technique</a> by Geoffrey Huntley</em>
  11. </p>
  12. <p align="center">
  13. <a href="https://github.com/Th0rgal/open-ralph-wiggum/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  14. <a href="https://github.com/Th0rgal/open-ralph-wiggum"><img src="https://img.shields.io/badge/built%20with-Bun%20%2B%20TypeScript-f472b6.svg" alt="Built with Bun + TypeScript"></a>
  15. <a href="https://github.com/Th0rgal/open-ralph-wiggum/releases"><img src="https://img.shields.io/github/v/release/Th0rgal/ralph-wiggum?include_prereleases" alt="Release"></a>
  16. </p>
  17. <p align="center">
  18. <a href="#supported-agents">Supported Agents</a> •
  19. <a href="#what-is-open-ralph-wiggum">What is Ralph?</a> •
  20. <a href="#installation">Installation</a> •
  21. <a href="#quick-start">Quick Start</a> •
  22. <a href="#commands">Commands</a>
  23. </p>
  24. <p align="center">
  25. <strong>Tired of agents breaking your local environment?</strong><br>
  26. 🏝️ <a href="https://github.com/Th0rgal/sandboxed.sh">sandboxed.sh</a> gives each task an isolated Linux workspace. Self-hosted. Git-backed.
  27. </p>
  28. <p align="center">
  29. 💬 <strong>Join the community:</strong> <a href="https://relens.ai/community">relens.ai/community</a>
  30. </p>
  31. ---
  32. ## Supported Agents
  33. Open Ralph Wiggum works with multiple AI coding agents. Switch between them using the `--agent` flag:
  34. | Agent | Flag | Description |
  35. |-------|------|-------------|
  36. | **Claude Code** | `--agent claude-code` | Anthropic's Claude Code CLI for autonomous coding |
  37. | **Codex** | `--agent codex` | OpenAI's Codex CLI for AI-powered development |
  38. | **Copilot CLI** | `--agent copilot` | GitHub Copilot CLI for agentic coding |
  39. | **Cursor Agent** | `--agent cursor-agent` | Cursor Agent CLI for headless AI coding |
  40. | **Qwen Code** | `--agent qwen-code` | Alibaba's Qwen Code CLI for headless AI coding |
  41. | **OpenCode** | `--agent opencode` | Default agent, open-source AI coding assistant |
  42. ```bash
  43. # Use Claude Code
  44. ralph "Build a REST API" --agent claude-code --max-iterations 10
  45. # Use OpenAI Codex
  46. ralph "Create a CLI tool" --agent codex --max-iterations 10
  47. # Use Copilot CLI
  48. ralph "Refactor the auth module" --agent copilot --max-iterations 10
  49. # Use Cursor Agent
  50. ralph "Add unit tests" --agent cursor-agent --max-iterations 10
  51. # Use Qwen Code
  52. ralph "Add unit tests" --agent qwen-code --max-iterations 10
  53. # Use OpenCode (default)
  54. ralph "Fix the failing tests" --max-iterations 10
  55. ```
  56. ---
  57. ## What is Open Ralph Wiggum?
  58. Open Ralph Wiggum implements the **Ralph Wiggum technique** — an autonomous agentic loop where an AI coding agent (Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode) receives the **same prompt repeatedly** until it completes a task. Each iteration, the AI sees its previous work in files and git history, enabling self-correction and incremental progress.
  59. This is a **CLI tool** that wraps any supported AI coding agent in a persistent development loop. No plugins required — just install and run.
  60. ```bash
  61. # The essence of the Ralph loop:
  62. while true; do
  63. claude-code "Build feature X. Output <promise>DONE</promise> when complete." # or codex, copilot, cursor-agent, qwen, opencode
  64. done
  65. ```
  66. **Why this works:** The AI doesn't talk to itself between iterations. It sees the same prompt each time, but the codebase has changed from previous iterations. This creates a powerful feedback loop where the agent iteratively improves its work until all tests pass.
  67. ### Multi-Agent Flexibility
  68. Switch between AI coding agents without changing your workflow:
  69. - **Claude Code** (`--agent claude-code`) — Anthropic's powerful coding agent
  70. - **Codex** (`--agent codex`) — OpenAI's code-specialized model
  71. - **Copilot CLI** (`--agent copilot`) — GitHub's agentic coding tool
  72. - **Cursor Agent** (`--agent cursor-agent`) — Cursor's headless AI coding agent
  73. - **Qwen Code** (`--agent qwen-code`) — Alibaba's Qwen Code headless CLI agent
  74. - **OpenCode** (`--agent opencode`) — Open-source default option
  75. ## Key Features
  76. - **Multi-Agent Support** — Use Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code, or OpenCode with the same workflow
  77. - **Self-Correcting Loops** — Agent sees its previous work and fixes its own mistakes
  78. - **Autonomous Execution** — Set it running and come back to finished code
  79. - **Task Tracking** — Built-in task management with `--tasks` mode
  80. - **Live Monitoring** — Check progress with `--status` from another terminal
  81. - **Mid-Loop Hints** — Inject guidance with `--add-context` without stopping
  82. ## Why Use an Agentic Loop?
  83. | Benefit | How it works |
  84. |---------|--------------|
  85. | **Self-Correction** | AI sees test failures from previous runs, fixes them |
  86. | **Persistence** | Walk away, come back to completed work |
  87. | **Iteration** | Complex tasks broken into incremental progress |
  88. | **Automation** | No babysitting—loop handles retries |
  89. | **Observability** | Monitor progress with `--status`, see history and struggle indicators |
  90. | **Mid-Loop Guidance** | Inject hints with `--add-context` without stopping the loop |
  91. ## Installation
  92. **Prerequisites:**
  93. - [Bun](https://bun.sh) runtime
  94. - At least one AI coding agent CLI:
  95. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's Claude Code CLI
  96. - [Codex](https://github.com/openai/codex) — OpenAI's Codex CLI
  97. - [Copilot CLI](https://github.com/github/copilot-cli) — GitHub's Copilot CLI
  98. - [Cursor Agent](https://cursor.com/cli/) — Cursor's headless Agent CLI
  99. - [Qwen Code](https://github.com/QwenLM/qwen-code) — Alibaba's Qwen Code CLI
  100. - [OpenCode](https://opencode.ai) — Open-source AI coding assistant
  101. ### npm (recommended)
  102. ```bash
  103. npm install -g @th0rgal/ralph-wiggum
  104. ```
  105. ### Bun
  106. ```bash
  107. bun add -g @th0rgal/ralph-wiggum
  108. ```
  109. ### From source
  110. ```bash
  111. git clone https://github.com/Th0rgal/open-ralph-wiggum
  112. cd open-ralph-wiggum
  113. ./install.sh
  114. ```
  115. ```powershell
  116. git clone https://github.com/Th0rgal/open-ralph-wiggum
  117. cd open-ralph-wiggum
  118. .\install.ps1
  119. ```
  120. This installs the `ralph` CLI command globally.
  121. ## Quick Start
  122. ```bash
  123. # Simple task with iteration limit
  124. ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \
  125. --max-iterations 5
  126. # Build something real
  127. ralph "Build a REST API for todos with CRUD operations and tests. \
  128. Run tests after each change. Output <promise>COMPLETE</promise> when all tests pass." \
  129. --max-iterations 20
  130. # Use Claude Code instead of OpenCode
  131. ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  132. --agent claude-code --model claude-sonnet-4 --max-iterations 5
  133. # Use Codex instead of OpenCode
  134. ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  135. --agent codex --model gpt-5-codex --max-iterations 5
  136. # Use Codex goal mode through OMX: Ralph owns cross-iteration retries, /goal owns one iteration
  137. RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx \
  138. ralph "Complete the task described in .harness/goal.md. Output <promise>COMPLETE</promise> when everything passes." \
  139. --agent codex --max-iterations 5
  140. # Use Copilot CLI
  141. ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  142. --agent copilot --max-iterations 5
  143. # Use Qwen Code
  144. ralph "Create a small CLI and document usage. Output <promise>COMPLETE</promise> when done." \
  145. --agent qwen-code --max-iterations 5
  146. # Complex project with Tasks Mode
  147. ralph "Build a full-stack web application with user auth and database" \
  148. --tasks --max-iterations 50
  149. ```
  150. ## Environment Variables
  151. Configure agent binaries with these environment variables:
  152. | Variable | Description | Default |
  153. |----------|-------------|---------|
  154. | `RALPH_OPENCODE_BINARY` | Path to OpenCode CLI | `"opencode"` |
  155. | `RALPH_CLAUDE_BINARY` | Path to Claude Code CLI | `"claude"` |
  156. | `RALPH_CODEX_BINARY` | Path to Codex CLI | `"codex"` |
  157. | `RALPH_CODEX_GOAL` | Enable Codex goal mode for `--agent codex` (`1`, `true`, `yes`, `on`) | unset |
  158. | `RALPH_CODEX_BACKEND` | Goal-mode backend: `codex` or `omx` | detected from configured codex command |
  159. | `RALPH_CODEX_GOAL_NATIVE` | Force native `/goal` attempt even when support is not pre-confirmed | unset |
  160. | `OMX_RALPH_OMX_BIN` | Path to OMX CLI when `RALPH_CODEX_BACKEND=omx` | `"omx"` |
  161. | `OMX_RALPH_REASONING` | `model_reasoning_effort` passed to `omx exec` in goal mode | `"high"` |
  162. | `RALPH_COPILOT_BINARY` | Path to Copilot CLI | `"copilot"` |
  163. | `RALPH_CURSOR_AGENT_BINARY` | Path to Cursor Agent CLI | `"cursor-agent"` |
  164. | `RALPH_QWEN_CODE_BINARY` | Path to Qwen Code CLI | `"qwen"` |
  165. **Note for Windows users:** Ralph automatically resolves `.cmd` extensions for npm-installed CLIs. If you encounter "command not found" errors, you can use these environment variables to specify the full path to the executable.
  166. ## Commands
  167. ### Running a Loop
  168. ```bash
  169. ralph "<prompt>" [options]
  170. Options:
  171. --agent AGENT AI agent to use: opencode (default), claude-code, codex, copilot, cursor-agent, qwen-code
  172. --codex-goal Run Codex iterations in goal mode; final Codex/OMX prompt starts with /goal
  173. --codex-backend BACKEND Backend for --codex-goal: codex or omx (default: detect)
  174. --codex-goal-native Force a native /goal attempt even when backend support is unconfirmed
  175. --min-iterations N Minimum iterations before completion allowed (default: 1)
  176. --max-iterations N Stop after N iterations (default: unlimited)
  177. --completion-promise T Text that signals completion (default: COMPLETE)
  178. --abort-promise TEXT Phrase that signals early abort (e.g., precondition failed)
  179. --tasks, -t Enable Tasks Mode for structured task tracking
  180. --task-min-iterations N Require each top-level task to receive N Ralph iterations before completion (default: 1)
  181. --task-promise T Text that signals task completion (default: READY_FOR_NEXT_TASK)
  182. --model MODEL Model to use (agent-specific)
  183. --rotation LIST Agent/model rotation for each iteration (comma-separated)
  184. --prompt-file, --file, -f Read prompt content from a file
  185. --prompt-template PATH Use custom prompt template (see Custom Prompts)
  186. --no-stream Buffer agent output and print at the end
  187. --verbose-tools Print every tool line (disable compact tool summary)
  188. --questions Enable interactive question handling (default: enabled)
  189. --no-questions Disable interactive question handling (agent will loop on questions)
  190. --no-plugins Disable non-auth OpenCode plugins for this run (opencode only)
  191. --no-commit Don't auto-commit after iterations
  192. --allow-all Auto-approve all tool permissions (default: on)
  193. --no-allow-all Require interactive permission prompts
  194. --config PATH Use custom agent config file
  195. --init-config [PATH] Write default agent config to PATH and exit
  196. --help Show help
  197. ```
  198. ### Codex / OMX Goal Mode
  199. `--codex-goal` is an opt-in mode for `--agent codex`. Open Ralph still owns the outer loop: max iterations, process restarts, promise detection, `.ralph/ralph-history.json`, git/file-system state, and optional auto-commits. Inside each Ralph iteration, the Codex backend receives a final prompt whose first token is `/goal`, so Codex goal mode can own the single-session push for that iteration.
  200. ```bash
  201. ralph \
  202. "Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes." \
  203. --agent codex \
  204. --codex-goal \
  205. --codex-backend omx \
  206. --max-iterations 5
  207. ```
  208. Equivalent environment form:
  209. ```bash
  210. RALPH_CODEX_GOAL=1 RALPH_CODEX_BACKEND=omx ralph \
  211. "Complete the task in .harness/goal.md. Run .harness/checks.sh. Output <promise>COMPLETE</promise> when everything passes." \
  212. --agent codex \
  213. --max-iterations 5
  214. ```
  215. Goal-mode iterations write a small durable audit ledger to `.ralph/codex-goal-ledger.jsonl`. This is intentionally file-system state, not Codex thread state, so later Ralph iterations can start fresh while retaining repo-native progress evidence. If native `/goal` cannot be pre-confirmed, Ralph prints an explicit warning; simulated fallback is used only when native Codex goal support is not available for the selected backend.
  216. ### Tasks Mode
  217. Tasks Mode allows you to break complex projects into smaller, manageable tasks. Ralph works on one task at a time and tracks progress in a markdown file.
  218. ```bash
  219. # Enable Tasks Mode
  220. ralph "Build a complete web application" --tasks --max-iterations 20
  221. # Custom task completion signal
  222. ralph "Multi-feature project" --tasks --task-promise "TASK_DONE"
  223. # Require each top-level task to receive three Ralph iterations before task/final completion
  224. ralph "Multi-feature project" --tasks --task-min-iterations 3 --max-iterations 20
  225. ```
  226. #### Task Management Commands
  227. ```bash
  228. # List current tasks
  229. ralph --list-tasks
  230. # Add a new task
  231. ralph --add-task "Implement user authentication"
  232. # Remove task by index
  233. ralph --remove-task 3
  234. # Show status (tasks shown automatically when tasks mode is active)
  235. ralph --status
  236. ```
  237. #### How Tasks Mode Works
  238. 1. **Task File**: Tasks are stored in `.ralph/ralph-tasks.md`
  239. 2. **One Task Per Iteration**: Ralph focuses on a single task to reduce confusion
  240. 3. **Automatic Progression**: When a task completes (`<promise>READY_FOR_NEXT_TASK</promise>`), Ralph moves to the next eligible task
  241. 4. **Task Minimum Iterations**: `--task-min-iterations N` requires every top-level task to receive N Ralph outer-loop iterations before task or final completion is accepted. This is separate from global `--min-iterations`, which gates the whole run.
  242. 5. **Task Ledger Fallback**: With task minimums enabled, if the selected top-level task is already `[x]` with all subtasks `[x]` after its required iterations, Ralph advances from the task ledger even if the agent forgets to emit `READY_FOR_NEXT_TASK`
  243. 6. **Persistent State**: Tasks survive loop restarts; per-task attempt counts are stored in `.ralph/ralph-task-runs.json` when task minimums are enabled
  244. 7. **Focused Context**: Smaller contexts per iteration reduce costs and improve reliability
  245. Task status indicators:
  246. - `[ ]` - Not started
  247. - `[/]` - In progress
  248. - `[x]` - Complete
  249. Example task file:
  250. ```markdown
  251. # Ralph Tasks
  252. - [ ] Set up project structure
  253. - [x] Initialize git repository
  254. - [/] Implement user authentication
  255. - [ ] Create login page
  256. - [ ] Add JWT handling
  257. - [ ] Build dashboard UI
  258. ```
  259. ### Custom Prompt Templates
  260. You can fully customize the prompt sent to the agent using `--prompt-template`. This is useful for integrating with custom workflows or tools.
  261. ```bash
  262. ralph "Build a REST API" --prompt-template ./my-template.md
  263. ```
  264. **Available variables:**
  265. | Variable | Description |
  266. |----------|-------------|
  267. | `{{iteration}}` | Current iteration number |
  268. | `{{max_iterations}}` | Maximum iterations (or "unlimited") |
  269. | `{{min_iterations}}` | Minimum iterations |
  270. | `{{prompt}}` | The user's task prompt |
  271. | `{{completion_promise}}` | Completion promise text (e.g., "COMPLETE") |
  272. | `{{abort_promise}}` | Abort promise text (if configured) |
  273. | `{{task_promise}}` | Task promise text (for tasks mode) |
  274. | `{{task_min_iterations}}` | Configured per-task minimum Ralph iterations (for tasks mode) |
  275. | `{{task_id}}` | Current selected top-level task id when task-min tracking is active |
  276. | `{{task_text}}` | Current selected top-level task text when task-min tracking is active |
  277. | `{{task_attempt}}` | Current selected task attempt count when task-min tracking is active |
  278. | `{{task_min_required}}` | Required attempts for the current selected task |
  279. | `{{task_can_complete}}` | `true` when the selected task has met its task minimum |
  280. | `{{task_gate_instruction}}` | Ready-to-embed task-min guidance for custom templates |
  281. | `{{context}}` | Additional context added mid-loop |
  282. | `{{tasks}}` | Task list content (for tasks mode) |
  283. **Example template (`my-template.md`):**
  284. ```markdown
  285. # Iteration {{iteration}} / {{max_iterations}}
  286. ## Task
  287. {{prompt}}
  288. ## Instructions
  289. 1. Check beads for current status
  290. 2. Decide what to do next
  291. 3. When the epic in beads is complete, output:
  292. <promise>{{completion_promise}}</promise>
  293. {{context}}
  294. ```
  295. ### Monitoring & Control
  296. ```bash
  297. # Check status of active loop (run from another terminal)
  298. ralph --status
  299. # Add context/hints for the next iteration
  300. ralph --add-context "Focus on fixing the auth module first"
  301. # Clear pending context
  302. ralph --clear-context
  303. ```
  304. ### Status Dashboard
  305. The `--status` command shows:
  306. - **Active loop info**: Current iteration, elapsed time, prompt
  307. - **Pending context**: Any hints queued for next iteration
  308. - **Current tasks**: Automatically shown when tasks mode is active (or use `--tasks`)
  309. - **Iteration history**: Last 5 iterations with tools used, duration
  310. - **Struggle indicators**: Warnings if agent is stuck (no progress, repeated errors)
  311. ```
  312. ╔══════════════════════════════════════════════════════════════════╗
  313. ║ Ralph Wiggum Status ║
  314. ╚══════════════════════════════════════════════════════════════════╝
  315. 🔄 ACTIVE LOOP
  316. Iteration: 3 / 10
  317. Elapsed: 5m 23s
  318. Promise: COMPLETE
  319. Prompt: Build a REST API...
  320. 📊 HISTORY (3 iterations)
  321. Total time: 5m 23s
  322. Recent iterations:
  323. 🔄 #1: 2m 10s | Bash:5 Write:3 Read:2
  324. 🔄 #2: 1m 45s | Edit:4 Bash:3 Read:2
  325. 🔄 #3: 1m 28s | Bash:2 Edit:1
  326. ⚠️ STRUGGLE INDICATORS:
  327. - No file changes in 3 iterations
  328. 💡 Consider using: ralph --add-context "your hint here"
  329. ```
  330. ### Mid-Loop Context Injection
  331. Guide a struggling agent without stopping the loop:
  332. ```bash
  333. # In another terminal while loop is running
  334. ralph --add-context "The bug is in utils/parser.ts line 42"
  335. ralph --add-context "Try using the singleton pattern for config"
  336. ```
  337. Context is automatically consumed after one iteration.
  338. ## Troubleshooting
  339. ### Plugin errors
  340. This package is **CLI-only**. If OpenCode tries to load a `ralph-wiggum` or `open-ralph-wiggum` plugin,
  341. remove it from your OpenCode `plugin` list (opencode.json), or run:
  342. ```bash
  343. ralph "Your task" --no-plugins
  344. ```
  345. ### ProviderModelNotFoundError / Model not configured
  346. If you see `ProviderModelNotFoundError` or "Provider returned error", you need to configure a default model:
  347. **For OpenCode:**
  348. 1. Edit `~/.config/opencode/opencode.json`:
  349. ```json
  350. {
  351. "$schema": "https://opencode.ai/config.json",
  352. "model": "your-provider/model-name"
  353. }
  354. ```
  355. 2. Or use the `--model` flag: `ralph "task" --model provider/model`
  356. **For other agents:**
  357. Use the `--model` flag to specify the model explicitly.
  358. ### "command not found" on Windows
  359. Ralph automatically tries `.cmd` extensions on Windows. If you still have issues:
  360. 1. Set the full path using environment variables:
  361. ```powershell
  362. $env:RALPH_OPENCODE_BINARY = "C:\path\to\opencode.cmd"
  363. ```
  364. 2. Or add the CLI to your PATH
  365. ### "bun: command not found"
  366. Install Bun: https://bun.sh
  367. ## Writing Good Prompts
  368. ### Include Clear Success Criteria
  369. ❌ Bad:
  370. ```
  371. Build a todo API
  372. ```
  373. ✅ Good:
  374. ```
  375. Build a REST API for todos with:
  376. - CRUD endpoints (GET, POST, PUT, DELETE)
  377. - Input validation
  378. - Tests for each endpoint
  379. Run tests after changes. Output <promise>COMPLETE</promise> when all tests pass.
  380. ```
  381. ### Use Verifiable Conditions
  382. ❌ Bad:
  383. ```
  384. Make the code better
  385. ```
  386. ✅ Good:
  387. ```
  388. Refactor auth.ts to:
  389. 1. Extract validation into separate functions
  390. 2. Add error handling for network failures
  391. 3. Ensure all existing tests still pass
  392. Output <promise>DONE</promise> when refactored and tests pass.
  393. ```
  394. ### Always Set Max Iterations
  395. ```bash
  396. # Safety net for runaway loops
  397. ralph "Your task" --max-iterations 20
  398. ```
  399. ## Recommended PRD Format
  400. Ralph treats prompt files as plain text, so any format works. For best results, use a concise PRD with:
  401. - **Goal**: one sentence summary of the desired outcome
  402. - **Scope**: what is in/out
  403. - **Requirements**: numbered, testable items
  404. - **Constraints**: tech stack, performance, security, compatibility
  405. - **Acceptance criteria**: explicit success checks
  406. - **Completion promise**: include `<promise>COMPLETE</promise>` (or match your `--completion-promise`)
  407. Example (Markdown):
  408. ```markdown
  409. # PRD: Add Export Button
  410. ## Goal
  411. Let users export reports as CSV from the dashboard.
  412. ## Scope
  413. - In: export current report view
  414. - Out: background exports, scheduling
  415. ## Requirements
  416. 1. Add "Export CSV" button to dashboard header.
  417. 2. CSV includes columns: date, revenue, sessions.
  418. 3. Works for reports up to 10k rows.
  419. ## Constraints
  420. - Keep current UI styling.
  421. - Use existing CSV utility in utils/csv.ts.
  422. ## Acceptance Criteria
  423. - Clicking button downloads a valid CSV.
  424. - CSV opens cleanly in Excel/Sheets.
  425. - All existing tests pass.
  426. ## Completion Promise
  427. <promise>COMPLETE</promise>
  428. ```
  429. ### JSON Feature List (Recommended for Complex Projects)
  430. For larger projects, a structured JSON feature list works better than prose. Based on [Anthropic's research on effective agent harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), JSON format reduces the chance of agents inappropriately modifying test definitions.
  431. Create a `features.json` file:
  432. ```json
  433. {
  434. "features": [
  435. {
  436. "category": "functional",
  437. "description": "Export button downloads CSV with current report data",
  438. "steps": [
  439. "Navigate to dashboard",
  440. "Click 'Export CSV' button",
  441. "Verify CSV file downloads",
  442. "Open CSV and verify columns: date, revenue, sessions",
  443. "Verify data matches displayed report"
  444. ],
  445. "passes": false
  446. },
  447. {
  448. "category": "functional",
  449. "description": "Export handles large reports up to 10k rows",
  450. "steps": [
  451. "Load report with 10,000 rows",
  452. "Click 'Export CSV' button",
  453. "Verify export completes without timeout",
  454. "Verify all rows present in CSV"
  455. ],
  456. "passes": false
  457. },
  458. {
  459. "category": "ui",
  460. "description": "Export button matches existing dashboard styling",
  461. "steps": [
  462. "Navigate to dashboard",
  463. "Verify button uses existing button component",
  464. "Verify button placement in header area"
  465. ],
  466. "passes": false
  467. }
  468. ]
  469. }
  470. ```
  471. Then reference it in your prompt:
  472. ```
  473. Read features.json for the feature list. Work through each feature one at a time.
  474. After verifying a feature works end-to-end, update its "passes" field to true.
  475. Do NOT modify the description or steps - only change the passes boolean.
  476. Output <promise>COMPLETE</promise> when all features pass.
  477. ```
  478. **Why JSON?** Agents are less likely to inappropriately modify JSON test definitions compared to Markdown. The structured format keeps agents focused on implementation rather than redefining success criteria.
  479. ## When to Use Ralph
  480. **Good for:**
  481. - Tasks with automatic verification (tests, linters, type checking)
  482. - Well-defined tasks with clear completion criteria
  483. - Greenfield projects where you can walk away
  484. - Iterative refinement (getting tests to pass)
  485. **Not good for:**
  486. - Tasks requiring human judgment
  487. - One-shot operations
  488. - Unclear success criteria
  489. - Production debugging
  490. ## How It Works
  491. ```
  492. ┌─────────────────────────────────────────────────────────────┐
  493. │ │
  494. │ ┌──────────┐ same prompt ┌──────────┐ │
  495. │ │ │ ───────────────▶ │ │ │
  496. │ │ ralph │ │ AI Agent │ │
  497. │ │ CLI │ ◀─────────────── │ │ │
  498. │ │ │ output + files │ │ │
  499. │ └──────────┘ └──────────┘ │
  500. │ │ │ │
  501. │ │ check for │ modify │
  502. │ │ <promise> │ files │
  503. │ ▼ ▼ │
  504. │ ┌──────────┐ ┌──────────┐ │
  505. │ │ Complete │ │ Git │ │
  506. │ │ or │ │ Repo │ │
  507. │ │ Retry │ │ (state) │ │
  508. │ └──────────┘ └──────────┘ │
  509. │ │
  510. └─────────────────────────────────────────────────────────────┘
  511. ```
  512. 1. Ralph sends your prompt to the selected agent
  513. 2. The agent works on the task, modifies files
  514. 3. Ralph checks output for completion promise
  515. 4. If not found, repeat with same prompt
  516. 5. AI sees previous work in files
  517. 6. Loop until success or max iterations
  518. ## Project Structure
  519. ```
  520. ralph-wiggum/
  521. ├── bin/ralph.js # CLI entrypoint (npm wrapper)
  522. ├── ralph.ts # Main loop implementation
  523. ├── package.json # Package config
  524. ├── install.sh / install.ps1 # Installation scripts
  525. └── uninstall.sh / uninstall.ps1 # Uninstallation scripts
  526. ```
  527. ### State Files (in .ralph/)
  528. During operation, Ralph stores state in `.ralph/`:
  529. - `ralph-loop.state.json` - Active loop state
  530. - `ralph-history.json` - Iteration history and metrics
  531. - `ralph-context.md` - Pending context for next iteration
  532. - `ralph-tasks.md` - Task list for Tasks Mode (created when `--tasks` is used)
  533. - `ralph-questions.json` - Pending user answers to agent questions
  534. ## Uninstall
  535. ```bash
  536. npm uninstall -g @th0rgal/ralph-wiggum
  537. ```
  538. ```powershell
  539. npm uninstall -g @th0rgal/ralph-wiggum
  540. ```
  541. ## Agent-Specific Notes
  542. ### Claude Code
  543. [Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official CLI for Claude. Use it with Open Ralph Wiggum for powerful autonomous coding:
  544. ```bash
  545. ralph "Refactor the auth module and ensure tests pass" \
  546. --agent claude-code \
  547. --model claude-sonnet-4 \
  548. --max-iterations 15
  549. ```
  550. ### OpenAI Codex
  551. [Codex](https://github.com/openai/codex) is OpenAI's code-specialized agent. Perfect for code generation and refactoring tasks:
  552. ```bash
  553. ralph "Generate unit tests for all utility functions" \
  554. --agent codex \
  555. --model gpt-5-codex \
  556. --max-iterations 10
  557. ```
  558. ### OpenCode
  559. [OpenCode](https://opencode.ai) is an open-source AI coding assistant. It's the default agent:
  560. ```bash
  561. ralph "Fix all TypeScript errors" --max-iterations 10
  562. ```
  563. ### Copilot CLI
  564. [Copilot CLI](https://github.com/github/copilot-cli) is GitHub's agentic coding tool (public preview). It requires a GitHub Copilot subscription and authentication via `GH_TOKEN`, `GITHUB_TOKEN`, or prior `copilot /login`.
  565. **Install:**
  566. ```bash
  567. npm install -g @github/copilot
  568. # or
  569. brew install copilot-cli
  570. ```
  571. **Usage:**
  572. ```bash
  573. ralph "Refactor the auth module and add tests" \
  574. --agent copilot \
  575. --max-iterations 15
  576. # With a specific model
  577. ralph "Build a REST API" \
  578. --agent copilot \
  579. --model claude-opus-4.6 \
  580. --max-iterations 10
  581. ```
  582. **Notes:**
  583. - Default model is Claude Sonnet 4.5; override with `--model`
  584. - `--allow-all` (default) maps to `--allow-all` + `--no-ask-user` in Copilot CLI
  585. - `--no-plugins` has no effect with Copilot CLI
  586. - Authentication: set `GH_TOKEN` / `GITHUB_TOKEN` env var, or run `copilot /login` first
  587. ### Qwen Code
  588. [Qwen Code](https://github.com/QwenLM/qwen-code) is Alibaba's headless AI coding CLI agent based on the Qwen model family. It uses the same stream-JSON output format as Claude Code.
  589. **Install:**
  590. ```bash
  591. npm install -g @qwen-code/qwen-code
  592. ```
  593. **Usage:**
  594. ```bash
  595. ralph "Refactor the database layer" \
  596. --agent qwen-code \
  597. --max-iterations 10
  598. # With a specific model
  599. ralph "Add integration tests for the API" \
  600. --agent qwen-code \
  601. --model qwen-coder-plus \
  602. --max-iterations 15
  603. ```
  604. **Notes:**
  605. - The CLI binary is `qwen`; override path with `RALPH_QWEN_CODE_BINARY` env var
  606. - `--allow-all` (default) maps to `--yolo` in Qwen Code CLI (auto-approves all actions)
  607. - `--no-plugins` has no effect with Qwen Code
  608. - Headless mode uses `--output-format stream-json --include-partial-messages`
  609. - See [headless docs](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/) for details
  610. ### Cursor Agent
  611. [Cursor Agent](https://cursor.com/cli/) is Cursor's headless CLI agent. It works with any model available through your Cursor subscription.
  612. **Install:**
  613. ```bash
  614. curl https://cursor.com/install -fsSL | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 795 on GitHub
  615. ```
  616. **Usage:**
  617. ```bash
  618. ralph "Add integration tests for the API" \
  619. --agent cursor-agent \
  620. --max-iterations 10
  621. # With a specific model
  622. ralph "Refactor the database layer" \
  623. --agent cursor-agent \
  624. --model sonnet-4 \
  625. --max-iterations 15
  626. ```
  627. **Notes:**
  628. - `--allow-all` (default) maps to `--force` in Cursor Agent CLI
  629. - `--no-plugins` has no effect with Cursor Agent
  630. - For headless environments (no Cursor window), set the `CURSOR_API_KEY` environment variable
  631. - The binary is `cursor-agent`; override with `RALPH_CURSOR_AGENT_BINARY` env var
  632. ## Agent Rotation
  633. Agent rotation lets you cycle through different agent/model combinations across iterations. This is useful for leveraging the strengths of different models or comparing their performance on a task.
  634. ### Format
  635. Each rotation entry uses the `agent:model` format:
  636. ```
  637. --rotation "agent1:model1,agent2:model2,agent3:model3"
  638. ```
  639. **Valid agents:** `opencode`, `claude-code`, `codex`, `copilot`, `cursor-agent`, `qwen-code`
  640. ### Example Usage
  641. ```bash
  642. # Alternate between OpenCode and Claude Code
  643. ralph "Build a REST API" \
  644. --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4" \
  645. --max-iterations 10
  646. # Cycle through three different configurations
  647. ralph "Refactor the auth module" \
  648. --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex" \
  649. --max-iterations 15
  650. # Include Copilot in the rotation
  651. ralph "Build a REST API" \
  652. --rotation "opencode:claude-sonnet-4,copilot:claude-sonnet-4" \
  653. --max-iterations 10
  654. ```
  655. ### Flag Interaction
  656. When `--rotation` is used, the `--agent` and `--model` flags are **ignored**. The rotation list takes precedence for agent/model selection.
  657. ### Cycling Behavior
  658. The rotation cycles back to the first entry after reaching the end:
  659. - Iteration 1 → Entry 1
  660. - Iteration 2 → Entry 2
  661. - Iteration 3 → Entry 1 (wraps around for a 2-entry rotation)
  662. - ...and so on
  663. ### Error Messages
  664. Invalid rotation entries produce clear error messages:
  665. **Invalid agent name:**
  666. ```
  667. Error: Invalid agent 'invalid' in rotation entry 'invalid:model'. Valid agents: opencode, claude-code, codex, copilot, cursor-agent, qwen-code
  668. ```
  669. **Malformed entry (missing colon):**
  670. ```
  671. Error: Invalid rotation entry 'opencode-model'. Expected format: agent:model
  672. ```
  673. **Empty values:**
  674. ```
  675. Error: Invalid rotation entry 'opencode:'. Both agent and model are required.
  676. ```
  677. ### Status Display
  678. When using `--status` with an active rotation, the output shows all rotation entries and marks the current one:
  679. ```
  680. 🔄 ACTIVE LOOP
  681. Iteration: 3 / 10
  682. Prompt: Build a REST API...
  683. Rotation (position 1/2):
  684. 1. opencode:claude-sonnet-4 **ACTIVE**
  685. 2. claude-code:claude-sonnet-4
  686. ```
  687. ### Iteration History
  688. The `--status` command shows which agent and model was used for each iteration:
  689. ```
  690. 📊 HISTORY (3 iterations)
  691. Total time: 5m 23s
  692. Recent iterations:
  693. #1 2m 10s opencode / claude-sonnet-4 Bash(5) Write(3) Read(2)
  694. #2 1m 45s claude-code / claude-sonnet-4 Edit(4) Bash(3) Read(2)
  695. #3 1m 28s opencode / claude-sonnet-4 Bash(2) Edit(1)
  696. ```
  697. ## Learn More
  698. - [Original Ralph Wiggum technique by Geoffrey Huntley](https://ghuntley.com/ralph/)
  699. - [Ralph Orchestrator](https://github.com/mikeyobrien/ralph-orchestrator)
  700. ## See Also
  701. Check out 🏝️ [sandboxed.sh](https://github.com/Th0rgal/sandboxed.sh) — a dashboard for orchestrating AI agents with workspace management, real-time monitoring, and multi-agent workflows.
  702. ## License
  703. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.