Ralph for Claude Code
Run Claude Code in a safeguarded autonomous loop that keeps developing until its work is explicitly complete.
- Source repo
- frankbria/ralph-claude-code
- Stars
- ★ 9.7k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Shell
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer already using Claude Code who wants it to work through a prioritized
.ralph/fix_plan.mduntil a feature set is complete. - Not a fit if
- Teams needing coding agents other than Claude Code; multi-provider support is still in progress
- Environments that cannot install Bash, jq, Git, and the Claude Code CLI
- Teams that cannot send code or issue content to a cloud model
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Ralph is a command-line autonomous development loop built specifically around Claude Code, installed globally and configured per project through .ralph/. It reads project instructions, task plans, and optional specifications, repeatedly invokes Claude Code, and records sessions, logs, status, and metrics. Its completion gate requires both heuristic completion indicators and EXIT_SIGNAL: true, while rate limits, timeouts, circuit breaking, and API-limit handling control long-running loops. Projects can be initialized with ralph-enable, ralph-setup, or ralph-import, including import from GitHub Issues. Claude execution can stay on the host or run in Docker or E2B sandboxes, but the documented core remains tied to Claude Code; multi-provider support is described as in progress.
The ralph command loads the project prompt and task priorities, invokes the configured CLAUDE_CODE_CMD (default claude), then parses JSON or text output after every loop. It persists session state in .ralph/.ralph_session, writes logs under .ralph/logs/, exposes status through ralph --status, and summarizes JSON Lines metrics with ralph-stats. ralph-enable detects a project environment and creates .ralph/ and .ralphrc; ralph-import creates PROMPT.md, fix_plan.md, and specification files from local requirements or GitHub Issues. ralph-queue stores issues or local PRDs in .ralph/queue.json and processes ready work sequentially by priority and dependency. With --monitor, Ralph uses tmux for a live dashboard; --sandbox docker and --sandbox e2b move Claude Code execution into the selected sandbox.
- A solo developer already using Claude Code who wants it to work through a prioritized
.ralph/fix_plan.mduntil a feature set is complete. - A team maintaining an existing TypeScript, Python, Rust, or Go codebase that needs
ralph-enableto add project configuration and import a task source. - An engineer turning a PRD, technical specification, PDF, or other documented requirement into a generated prompt, specifications, and prioritized implementation plan.
- A repository maintainer using GitHub Issues who needs to filter work by labels, milestone, assignee, or title and optionally comment, create a PR, and close an issue.
- A team that wants Claude Code's edits and command execution isolated in a Docker container or E2B cloud sandbox.
- An engineering lead processing a backlog of issues or PRDs one at a time in priority and dependency order with a persistent queue.
How do you install or deploy this agent?
The documented prerequisites are Bash 4.0+, the Claude Code CLI, jq, Git, and GNU coreutils for timeout; on macOS, the README specifies brew install coreutils for gtimeout. The documented Claude Code CLI installation example is npm install -g @anthropic-ai/claude-code. Then run:
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.shThis adds ralph, ralph-monitor, ralph-setup, ralph-import, ralph-queue, ralph-migrate, ralph-enable, and ralph-enable-ci to PATH. Normal use requires a working Claude Code CLI; the supplied documentation does not prescribe its normal authentication sequence. Docker mode accepts ANTHROPIC_API_KEY or the host ~/.claude/.credentials.json; E2B mode requires pip install e2b and E2B_API_KEY.
How do you use this agent?
For an existing project:
cd my-existing-project
ralph-enable
ralph --monitorTo begin from a requirements document, run ralph-import product-requirements.md my-app, enter the generated directory, and run ralph --monitor. For non-interactive setup, use ralph-enable-ci --from github --json. In .ralphrc, configure values such as CLAUDE_CODE_CMD="claude", MAX_CALLS_PER_HOUR=100, CLAUDE_TIMEOUT_MINUTES=15, ALLOWED_TOOLS, and session settings; the default prompt is .ralph/PROMPT.md. For isolated execution, start with ralph --sandbox docker or ralph --sandbox e2b.
What are this agent's strengths and limitations?
- Its dual-condition exit gate combines completion indicators with Claude's explicit
EXIT_SIGNAL, reducing the chance that a natural-language completion claim ends productive work too early. - Hourly call and token limits, 5-hour API-limit handling, circuit breaking, session expiry, and timeouts provide documented controls for unattended loops.
- It covers a concrete development workflow from requirement or GitHub Issue import through queued execution and optional PR creation or issue closure.
- Docker and E2B sandbox modes separate Claude execution from the host loop; Docker preserves container state across iterations, while E2B adds file synchronization and cost-limit controls.
ralph-enable,ralph-enable-ci,.ralphrc, tmux monitoring, live output, log rotation, metrics, and backup/rollback provide practical CLI-oriented operations.
- Core operation depends on the Claude Code CLI. The repository describes multi-provider agent abstraction as in progress, so it is not evidence of current cross-provider support.
- Adoption requires Bash, jq, Git, GNU coreutils, and Claude Code CLI; integrated monitoring also needs tmux, while macOS requires
gtimeouthandling. - Ralph can halt when Claude Code lacks permission for a needed command, so projects must maintain an appropriate
ALLOWED_TOOLSconfiguration. - GitHub Issue import and lifecycle actions require an installed, authenticated
ghCLI, and importing public issue comments requires a trust decision by the operator. - E2B sync propagates sandbox deletions and renames to the host, and commits made inside the sandbox are not synchronized; both sandbox modes also add environment and credential-management work.
How does this agent compare with similar options?
The README names Aider as a related project and attributes Ralph's approach to Geoffrey Huntley's Ralph technique. Ralph is explicitly documented as a Claude Code development loop; the repository does not provide a feature-by-feature comparison with Aider.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Ralph for Claude Code This agent | 53 · Major gaps | CLIFree + model costs | ★ 9.7k | 2d ago | Shell | Claude Code |
| Forgeo Software Factory | 76 · Some gaps | CLIFree + model costs | ★ 35 | 5d ago | Python | Codex · Claude Code |
| mini-swe-agent | 54 · Major gaps | CLIFree + model costs | ★ 9.2k | 2mo ago | Python | — |
| Pilot | 53 · Major gaps | CLIFree + model costs | ★ 727 | today | Go | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes --allowed-tools to restrict tool permissions, --dry-run simulation, --backup/--rollback backup restore, --include-comments default exclusion of comments, and other security features; GitHub Actions workflows use minimal permissions and read-only checkout. Deductions: no actual code verification of permission implementation, dependency security only mentions pinned action versions without dependency audit; data flow transparency only describes features without showing actual log content; sensitive data handling not explicitly stated.
Evidence shows: README and test files demonstrate error detection, stuck loop detection logic, test files contain specific test cases, self-consistency is good. Deductions: dependency availability only mentions bats etc., no complete dependency list; failure messages are reflected in tests but not all scenarios covered.
Evidence shows: README describes multiple usage scenarios (new project, existing project, PRD import, GitHub Issues), supports multiple project types and frameworks, provides ralph-enable wizard and configuration options. Deductions: capability boundaries not explicitly stated, trigger precision depends on Claude output, environment fit not covering all platforms.
Evidence shows: README structure is clear, includes installation, usage, configuration, troubleshooting sections; provides install.sh and uninstall.sh; version numbers inconsistent between README (0.11.5) and package.json (1.0.0); changelog exists but not as separate file; known limitations not explicitly listed.
Evidence shows: README describes output formats (JSON, text), live streaming, log rotation, output usability is good; marginal value reflected in automation loop and intelligent exit detection; cost-benefit not provided with actual data, only claims 784 tests passing.
Evidence shows: README claims 784 tests passing but no test report link; test files exist but no independent verification; facts and inferences not clearly separated.
- Version number inconsistency: README shows 0.11.5, package.json shows 1.0.0, may cause confusion.
- Dependency security lacks audit, only pins action versions, recommend checking for vulnerabilities.
- Sensitive data handling not explicitly stated, especially regarding GitHub tokens and API keys, caution advised.
- Tests claim 784 passing but no reproducible test report, recommend independent verification.
FAQ
When does Ralph stop a development loop?
completion_indicators >= 2 and EXIT_SIGNAL: true. Ralph also evaluates task completion, repeated completion signals, test-focused loops, and the Claude API 5-hour usage limit.Does it call the Anthropic API directly?
ANTHROPIC_API_KEY into the sandbox or copy host Claude credentials; the documentation does not describe Ralph as a standalone general Anthropic API client.How can I control cost or prevent a runaway loop?
MAX_CALLS_PER_HOUR and optional MAX_TOKENS_PER_HOUR, then use timeouts, the circuit breaker, cooldown settings, --dry-run, and, for E2B, --sandbox-max-cost.Can it start from a GitHub Issue and finish the issue workflow?
ralph-import --github-issue can turn an issue into a Ralph project. During development, --comment-progress, --create-pr, --link-issue, --close-summary, and --auto-close are available, subject to authenticated gh access.How do Docker and E2B differ?
.git is excluded by default, so commits made inside E2B do not become host commits.