Autonomous Claude Code task orchestrator. Picks up tasks from a backlog, works them one at a time in fresh-context iterations, verifies the result, and merges — unattended.
# Install ralph and dependencies (bd, gh, tmux, Go)
./install.sh
# Create some tasks (run from your project directory)
cd ~/myproject
ralph task
# Run the loop
ralph loop --auto-merge --base-branch main --evolveAdd this alias for rapid iteration:
alias loop='ralph loop --auto-merge --base-branch main --evolve'--auto-merge— squash-merges each PR automatically after CI passes--base-branch main— rebases and merges intomain(change to match your repo)--evolve— re-execs ralph after each merge so improvements take effect immediately
The loop runs until you press Ctrl-C. When the backlog empties it polls for new tasks — no flag needed. To rebuild the project on each iteration (useful for self-improving loops), add --post-task <build-script> alongside --evolve.
Run two windows side by side, named {project}-loop and {project}-task:
{project}-loop: loop # runs the loop alias indefinitely
{project}-task: ralph task # interactive triage: create tasks, write specs
The loop window runs unattended while the task window gives you a live triage interface — add tasks at any time and the loop picks them up immediately. Both windows stay live so you can monitor and triage from anywhere, including from your phone via Shellfish (iOS) or any SSH client on Android.
Ralph runs Claude Code repeatedly, one task per iteration. Each iteration gets a task from the backlog (bd), works it on an isolated git worktree, runs a verification pipeline, and the orchestrator pushes, creates a PR, and merges. Each task produces one commit that stacks linearly on the previous.
ralph loop
│
├─ pick next task from bd backlog
├─ create branch, start agent
│
│ ┌──────────────────────────────────────────┐
│ │ agent works → signals complete │
│ │ ↓ │
│ │ test suite │
│ │ ↓ │
│ │ fails? → fix agent → re-test (×3) │
│ │ ↓ │
│ │ LLM verification against criteria │
│ │ ↓ │
│ │ rejected? → fix agent → re-verify (×3) │
│ └──────────────────────────────────────────┘
│
│ ┌──────────────────────────────────────────┐
│ │ rebase onto latest base │
│ │ ↓ │
│ │ squash to one commit, push │
│ │ ↓ │
│ │ wait for CI │
│ │ ↓ │
│ │ CI fails? → fix agent → loop (×4) │
│ │ base moved? → loop │
│ │ ↓ │
│ │ merge PR │
│ └──────────────────────────────────────────┘
│
└─ next task (stacks on previous commit)
| Command | Purpose |
|---|---|
ralph loop |
Autonomous executor — picks tasks, writes code, verifies, merges |
ralph task |
Interactive triage session — create tasks, write specs, manage backlog |
ralph stop |
Halt after the current iteration |
ralph feedback |
Append feedback to bead notes and restart the agent |
ralph attach |
Attach to a running loop's tmux session |
ralph review |
Post-mortem review of reflections, tests, and refactoring opportunities |
ralph merge |
Rebase and merge a stacked PR chain bottom-up |
Run ralph task to build up a backlog, then ralph loop to work through it.
| Flag | Description | Default | Env var |
|---|---|---|---|
-n, --max <N> |
Max iterations | 50 | RALPH_MAX_ITERATIONS |
-v, --verbose |
Show all tool calls in stream log | — | |
--base-branch <name> |
Base branch for rebase/merge | develop | RALPH_BASE_BRANCH |
--auto-merge |
Squash-merge PRs after task completion | — | |
--evolve |
Self-improving mode: re-exec ralph after each merged task so improvements take effect immediately (requires --auto-merge) |
— | |
--post-task <script> |
Run a script after each task completes, before evolve re-exec. Receives RALPH_TASK_ID, RALPH_PR_NUMBER, and RALPH_MERGED env vars. |
— | |
--verify-build <script> |
Run a script before pre-iteration tests to check project-level build health | — | |
--model-ceiling <model> |
Model ceiling for all LLM interactions — no call may use a higher-tier model than this | claude-sonnet-4-6 | |
--notify |
Send macOS notification on each task completion | — | |
--tmux |
Run in tmux 3-pane layout (status / output / plan) | — |
All other tuning (timeouts, model escalation, attempt limits, thresholds) lives in .ralph/config.toml — see Configuration below.
Ralph reads .ralph/config.toml on startup. The file is created automatically with defaults on first run. CLI flags override config file values.
Example .ralph/config.toml:
base_branch = "main"
post_task = "make build"
# Tuning — defaults shown
max_iterations = 50
calls_per_hour = 80
test_timeout = "5m"
verify_model = "claude-haiku-4-5-20251001"
fix_model = "claude-sonnet-4-6"
fix_escalation_model = "claude-opus-4-6"Run ralph loop --help to see all available options and their corresponding config keys.
The orchestrator owns the entire push/PR/merge lifecycle. The agent writes code and signals completion — it never pushes, creates PRs, or closes tasks. These operations are enforced via disallowed tools:
git push— orchestrator pushes after verification passesgh pr create— orchestrator creates the PR and links it to the bead viaexternal-refbd close— orchestrator closes the bead only after successful mergegit checkout/git branch— prevents sub-agents from interfering with branch management
The loop uses a tiered model strategy to balance cost and quality:
- Agent first pass — sonnet
- Agent retry — opus; escalated automatically on subsequent attempts
- Verification first pass — haiku
- Verification retry — sonnet
- Fix agent first pass — sonnet; covers test/compile/verify/CI/Copilot/conflict fix agents
- Fix agent retry — opus; escalated automatically on subsequent attempts
--model-ceiling sets the ceiling from the CLI — no LLM call may use a higher-tier model than the value set. Per-stage model defaults are configured in .ralph/config.toml (verify_model, fix_model, fix_escalation_model, etc.).
After the agent signals completion:
- Test suite — full
make test(or equivalent) must pass. If it fails, a fix agent is spawned to address the failures (up to 3 retries). - LLM diff review — haiku reviews the diff against the bead's acceptance criteria. If rejected, a fix agent addresses the issues (up to 3 retries, escalating to sonnet).
After verification passes:
- Rebase onto the latest base branch
- Squash to a single commit and push
- Wait for CI — only required checks from branch protection are evaluated
- CI fix loop — if CI fails, a fix agent patches, force-pushes, and re-checks (up to 4 retries). If the base moved during the loop, rebase and retry.
- Merge the PR
ralph feedback "msg" appends the message to the bead's notes via bd update --append-notes, then kills the running agent via context cancellation — aborting any in-flight operation (CI polling, merge wait, review wait). The loop restarts immediately with a fresh context. The agent must acknowledge feedback with a FEEDBACK: line before proceeding.
Ctrl-C cancels the running operation but leaves the bead open. The loop exits cleanly — no bead is closed or skipped. Resume by restarting the loop.
Each task produces one commit, stacked linearly on the previous. PRs target the previous task's branch (not the base), so each PR shows only its own changes.
When the base moves (e.g. direct pushes), Ralph rebases onto the latest base on startup. If the rebase conflicts, the stack diverges — Ralph continues building on top without trying to auto-resolve. To resolve a diverged stack later: git rebase --update-refs origin/main from the stack tip.
With --evolve, ralph re-execs itself after each successful merge to pick up the latest binary. This means ralph can work on its own codebase — improvements to prompts, verification logic, or merge behavior take effect on the next iteration. Use --post-task to run a rebuild script before the re-exec.
Requirements:
- Go 1.26+
- Claude Code CLI installed and authenticated
- Homebrew (for dependency installation)
./install.shThis installs bd, gh, and tmux via Homebrew if missing, builds the Go binary, and places it at ~/.local/bin/ralph.
To build manually:
make build # produces ./ralph binary
make install # copies to ~/.local/bin/ralph
make test # runs the test suiteRalph uses bd as its task backend. The loop reads from the bd backlog, claims tasks, and closes them after successful merge. Use ralph task for interactive triage:
ralph taskRalph stores all runtime state in .ralph/ inside the project directory. Add it to .gitignore.
.ralph/
config.toml # tuning knobs — created automatically with defaults on first run
state.json # iteration count, status, current task, skipped tasks
reflections/ # post-task reflections from the agent
worktrees/ # git worktree directories
.signal_complete # agent completion signal
.signal_current_task # current task signal
feedback # queued user feedback
stop # create to halt gracefully
ralph loop --tmux starts a tmux session with three panes:
┌──────────────────┬──────────────────┐
│ │ │
│ ralph loop │ stream filter │
│ (orchestrator) │ (agent output) │
│ │ │
├──────────────────┴──────────────────┤
│ │
│ plan / state watcher │
│ │
└─────────────────────────────────────┘
Use ralph attach to connect to a running loop's session from another terminal.
MIT