ralph

ralph

Long-running agent loop for Claude Code, in the Ralph pattern.

A stable prompt, a mutable plan, a loop that runs until the plan is empty.

---

Should you use Ralph?

As of 2026-05-28, Claude Code ships dynamic workflows, which run tens to hundreds of parallel subagents in a single session with built-in verification, persist progress across interruptions, and handle codebase-scale work (e.g. the Bun port from Zig to Rust, 750K LOC). For most "build a project end-to-end" tasks, dynamic workflows is now the official answer.

Ralph is for a narrower case. Use Ralph when one or more of these is true:

• You want to author the plan, not have Claude plan it. Ralph executes a checklist you wrote; dynamic workflows decides what subtasks to spawn from a prompt.
• You want a shell process you can supervise. Ralph is a bash script — cron, tmux, ssh, systemd all work normally on it. Dynamic workflows runs inside a Claude Code session.
• You are on Pro, or on a tier where dynamic workflows isn't available. Dynamic workflows requires Max, Team, or admin-enabled Enterprise. Ralph runs on any tier.
• You want token cost bounded per iteration. Ralph caps cost per iteration via --max-budget-usd. Dynamic workflows "consumes substantially more tokens than a typical Claude Code session" (their words).
• You want the loop to be inspectable. Ralph is ~150 lines of bash you can read, modify, and audit. Dynamic workflows is managed infrastructure.

If none of those apply, try dynamic workflows first.

---

Install

# As a one-off, from this directory:
claude --plugin-dir .

# Or symlink into your plugins:
ln -s "$PWD" ~/.claude/plugins/ralph

---

Commands

/ralph-init

Scaffolds .ralph/ in the current working directory:

.ralph/
├── plan.md            — flat markdown checklist of tasks
├── ralph.prompt.md    — per-iteration system-prompt rules
├── config             — model, budget, iteration cap
└── logs/              — one JSON file per iteration

Adds .ralph/ to .gitignore if a repo is present. Idempotent — does nothing if .ralph/ already exists.

/ralph-run

Runs the loop. Each iteration is an independent claude -p invocation with a fresh context window: no --continue, no carried conversation. The plan file is the only state between iterations.

The model's job each turn:

1. Read .ralph/plan.md
2. Pick the first - [ ] item
3. Do the work
4. Edit .ralph/plan.md to flip it to - [x]
5. Stop

The loop exits when the plan has zero - [ ] items, RALPH_MAX_ITERATIONS is hit, or Ctrl+C.

/ralph-goal <condition>

Single-session alternate mode. Spawns one claude -p "/goal <condition>" process whose built-in evaluator decides when the condition holds. Unlike /ralph-run, this rides on one continued conversation — useful for shorter, well-scoped work where one session is enough.

/ralph-goal every test in test/auth passes and lint is clean

---

When to use which mode

	/ralph-run	/ralph-goal
Context per turn	Fresh every iteration	One continued conversation
Exit decided by	Bash grep of plan.md for - [ ]	Fast-model evaluator after every turn
Scales to	Long plans (hours, days, overnight)	Short well-scoped tasks
Resistant to context rot	Yes — no context to rot	No — accumulates until auto-compact
State between iterations	plan.md only	Full conversation

Default to /ralph-run for anything substantial. Reach for /ralph-goal when the work is small enough to fit comfortably in one session and the success condition is easy to phrase. For codebase-scale work where Claude can plan the subtasks itself, prefer dynamic workflows over either of these.

---

Configuration

.ralph/config is a shell-sourceable file with sensible defaults:

RALPH_MAX_ITERATIONS=100                  # hard cap on loop count
RALPH_MAX_TURNS=10                        # agentic turns per claude -p call
RALPH_BUDGET_USD=2.00                     # per-iteration USD cap
RALPH_MODEL=sonnet                        # sonnet | opus | full model ID
RALPH_PERMISSION_MODE=bypassPermissions   # canonical Ralph: model runs anything

The bypassPermissions default matches canonical Ralph (snarktank uses --dangerously-skip-permissions). It's the only mode where the loop can build a project end-to-end without stalling on the first npm install or pytest. Run Ralph in a worktree, a container, or a disposable directory. Less-risky options (acceptEdits, auto, dontAsk) are documented in the config file.

---

Subscription note