npm install -g @th0rgal/ralph-wiggum

bun add -g @th0rgal/ralph-wiggum

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

ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \
  --max-iterations 5

ralph "Build a REST API with tests. Output <promise>COMPLETE</promise> when all tests pass." \
  --agent claude-code --model claude-sonnet-4 --max-iterations 20

ralph "Refactor auth module, ensure all tests pass. Output <promise>COMPLETE</promise> when done." \
  --agent codex --model gpt-5-codex --max-iterations 20

ralph "Implement login feature. Output <promise>COMPLETE</promise> when done." \
  --agent copilot --max-iterations 15

opencode models

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

claude --version

codex --version

copilot /status   # shows login state and available models

undefined

for bin in opencode claude codex copilot; do
  if command -v "$bin" &>/dev/null; then echo "✅ $bin: $(which $bin)"; else echo "❌ $bin: not found"; fi
done && \
  [[ -n "$GH_TOKEN" ]] && echo "✅ GH_TOKEN set (Copilot CLI)" || echo "ℹ️  GH_TOKEN not set (needed only for Copilot CLI)"

--agent AGENT            Agent to use (opencode|claude-code|codex|copilot)
--model MODEL            Model name (agent-specific, e.g. claude-sonnet-4, gpt-5-codex)
--max-iterations N       Stop after N iterations (always set this as a safety net)
--min-iterations N       Require at least N iterations before allowing completion (default: 1)
--completion-promise T   Text that signals task completion (default: COMPLETE)
--abort-promise TEXT     Text that signals early abort/precondition failure
--tasks / -t             Enable Tasks Mode (structured multi-task tracking)
--prompt-file / -f PATH  Read prompt from a file instead of CLI argument
--prompt-template PATH   Use a custom Mustache-style prompt template
--no-commit              Skip git auto-commit after each iteration
--no-plugins             Disable OpenCode plugins (useful to avoid plugin conflicts)
--allow-all              Auto-approve all tool permission prompts (default: on)
--status                 Show live loop status from another terminal
--add-context TEXT       Inject a hint for the next iteration without stopping the loop
--clear-context          Remove pending context
--list-tasks             List current tasks (Tasks Mode)
--add-task TEXT          Add a task (Tasks Mode)
--remove-task N          Remove task by index (Tasks Mode)
--rotation LIST          Cycle through agent/model pairs each iteration (comma-separated agent:model)
--verbose-tools          Print every tool line (disable compact tool summary)
--last-activity-timeout DURATION  Kill and restart iteration after inactivity (e.g., 30m, 1h)
--no-questions           Disable interactive question handling (agent will loop on questions)
--task-promise T        Text that signals task completion (default: READY_FOR_NEXT_TASK)
--no-stream             Buffer agent output and print at the end
--no-allow-all          Require interactive permission prompts
--config PATH           Use custom agent config file
--init-config [PATH]    Write default agent config to PATH and exit
--questions             Enable interactive question handling (default: enabled)

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --max-iterations 20

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent claude-code --model claude-sonnet-4 --max-iterations 20

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent codex --model gpt-5-codex --max-iterations 20

:split | terminal ralph "Your task. Output <promise>COMPLETE</promise> when done." --agent copilot --max-iterations 20

ralph --prompt-file ./task.md --max-iterations 30

ralph --prompt-file ./task.md --agent claude-code --model claude-sonnet-4 --max-iterations 30

ralph --prompt-file ./task.md --agent codex --model gpt-5-codex --max-iterations 30

ralph --prompt-file ./task.md --agent copilot --max-iterations 30

undefined

Tasks are stored in `.ralph/ralph-tasks.md`. Each task uses one loop iteration, signaled by `<promise>READY_FOR_NEXT_TASK</promise>`.

---

ralph --status      # Shows iteration progress, history, struggle indicators
ralph --add-context "The bug is in utils/parser.ts line 42"  # Guide the agent
ralph --clear-context  # Remove queued hint

Build a todo API

Build a REST API for todos with:
- CRUD endpoints (GET, POST, PUT, DELETE)
- Input validation
- Tests for each endpoint

Run tests after each change.
Output <promise>COMPLETE</promise> when all tests pass.

undefined

Available variables: `{{iteration}}`, `{{max_iterations}}`, `{{min_iterations}}`, `{{prompt}}`, `{{completion_promise}}`, `{{abort_promise}}`, `{{task_promise}}`, `{{context}}`, `{{tasks}}`.

Use with:

```bash
ralph "Your task" --prompt-template ./my-template.md

undefined

Format: `agent:model` entries separated by commas. When `--rotation` is set, `--agent` and `--model` are ignored. The list cycles (iteration 3 of a 2-entry rotation goes back to entry 1).

---

ralph "Refactor the auth module and ensure tests pass" \
  --agent claude-code --model claude-sonnet-4 --max-iterations 15

ralph "Generate unit tests for all utility functions" \
  --agent codex --model gpt-5-codex --max-iterations 10

copilot /login   # or set GH_TOKEN / GITHUB_TOKEN env var

npm install -g @github/copilot

Usage:

```bash
ralph "Refactor the auth module and add tests" \
  --agent copilot --max-iterations 15

Notes:

- Default model is Claude Sonnet 4.5; override with `--model`
- `--no-plugins` has no effect with Copilot CLI
- `--allow-all` (default) maps to `--allow-all` + `--no-ask-user` in Copilot CLI

---

---

{
  "features": [
    {
      "category": "functional",
      "description": "Feature description",
      "steps": ["Step 1", "Step 2"],
      "passes": false
    }
  ]
}

npm uninstall -g @th0rgal/ralph-wiggum