Run Claude Code in a retry loop until the task is done.
ralph-loop --yolo "Fix all lint errors"
Claude runs inside a tmux pane you can attach to and watch. The outer loop checks for a sentinel file after each iteration. The sentinel instruction is auto-injected — just describe the task.
git clone https://github.com/jonkhler/ralph-loop.git
cd ralph-loop
./install.shOr just copy ralph-loop somewhere on your PATH.
ralph-loop [OPTIONS] <prompt>
ralph-loop [OPTIONS] --prompt-file <file>
| Flag | Description | Default |
|---|---|---|
-n, --max <N> |
Max iterations | 20 |
-s, --sentinel <path> |
Sentinel file path | .ralph-done |
-t, --session <name> |
Tmux session name | ralph |
-f, --prompt-file <file> |
Read prompt from file | — |
--fresh |
New Claude session each iteration | continue |
--yolo |
--dangerously-skip-permissions |
off |
--model <model> |
Model (opus, sonnet, haiku) | — |
--name <name> |
Claude session name | — |
--dir <path> |
Working directory | CWD |
--dry-run |
Show commands without running | — |
┌─────────────────────────┐ ┌──────────────────────────┐
│ your terminal │ │ tmux session "ralph" │
│ │ │ │
│ ralph-loop │ │ claude --print ... │
│ ├─ iteration 1 ──────┼────▶│ (readable output │
│ │ wait... │◀────┼──── streams here) │
│ │ check sentinel │ │ │
│ ├─ iteration 2 ──────┼────▶│ claude --print --cont.. │
│ │ ... │ │ ... │
│ └─ ✓ sentinel found │ │ │
│ │ │ (cleaned up on exit) │
└─────────────────────────┘ └──────────────────────────┘
- Creates a tmux session (default:
ralph) - Each iteration sends
claude --print <prompt>into the pane - Blocks via
tmux wait-foruntil Claude finishes - Checks for the sentinel file — if found, done
- Otherwise, next iteration with
--continue(unless--fresh) - Tmux session is cleaned up on exit
Attach to the tmux session to see Claude's output streaming in real time:
tmux attach -t ralph # watch Claude work
# Ctrl-b d # detach without interruptingCustom session name:
ralph-loop -t my-task --yolo "Fix all tests"
tmux attach -t my-task- Claude Code CLI installed and authenticated
- tmux
- bash 4+