by umputun
Extended Ralph loop for autonomous AI-driven plan execution
# Add to your Claude Code skills
git clone https://github.com/umputun/ralphexLast scanned: 5/1/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-01T06:38:40.014Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates Claude Code or codex to execute implementation plans autonomously - no IDE plugins or cloud services required, just a coding agent and a single binary.
Claude Code is powerful but interactive - it requires you to watch, approve, and guide each step. For complex features spanning multiple tasks, this means hours of babysitting. Worse, as context fills up during long sessions, the model's quality degrades - it starts making mistakes, forgetting earlier decisions, and producing worse code.
ralphex solves both problems. Each task executes in a fresh Claude Code session with minimal context, keeping the model sharp throughout the entire plan. Write a plan with tasks and validation commands, start ralphex, and walk away. Come back to find your feature implemented, reviewed, and committed - or check the progress log to see what it's doing.



--plan flag{{agent:name}} template system and user defined promptscompleted/ folder--serve flag--worktree flagMake sure ralphex is installed and your project is a git repository. You need a plan file in docs/plans/, for example:
# Plan: My Feature
## Validation Commands
- `go test ./...`
### Task 1: Implement feature
- [ ] Add the new functionality
- [ ] Add tests
Then run:
ralphex docs/plans/my-feature.md
ralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to completed/ when done.
[!WARNING] Anthropic Agent SDK billing change on June 15, 2026
Anthropic is moving
claude -p/claude --print, Claude Agent SDK, and Claude Code GitHub Actions usage to a separate monthly Agent SDK credit pool for Claude subscription users. The default Claude mode in ralphex usesclaude --printinternally, so unattended ralphex runs are part of that pool. See Anthropic's Agent SDK credit article for the current billing rules.Practical options:
- Do nothing. Light use may fit inside the included monthly credit. This should also be transparent for users who already run Claude Code through API-key billing, Bedrock, Vertex, Foundry, or another non-subscription provider path.
- Use a skill-based flow in an interactive Claude Code session. The author's
umputun/cc-thingzplugin collection includes theplanningfamily (/planning:makeand/planning:exec). That keeps work inside the normal interactive Claude Code flow instead ofclaude --print.- Switch the ralphex executor to codex. First-class
--codexsupport routes plan creation, task execution, both review phases, and finalize through the codex CLI and skips the external codex review phase.- Use a
claude -pcompatible wrapper that drives an interactive Claude Code session and emits Claude-compatiblestream-json. Examples that match ralphex's invocation shape includeumputun/fya,melonamin/agentrun,Equality-Machine/claude-p, andkcosr/claude-pty-wrapper. These wrappers are unofficial and may break if Anthropic changes or blocks this pattern.
Install fya with Homebrew:
brew install umputun/apps/fya
command -v fya
Use the absolute path printed by command -v fya in ralphex config. On Apple Silicon Homebrew this is normally /opt/homebrew/bin/fya:
# in ~/.config/ralphex/config or .ralphex/config
claude_command = /opt/homebrew/bin/fya
claude_args = --dangerously-skip-permissions --output-format stream-json --verbose
On Intel Homebrew the path is normally /usr/local/bin/fya. If command -v fya prints another path, use that exact path instead.
For agentrun, use its tmux-backed path if the goal is avoiding direct claude --print:
claude_command = /absolute/path/to/agentrun
claude_args = --persist-session --no-session-persistence --dangerously-skip-permissions --output-format stream-json --verbose
These tools depend on interactive Claude Code behavior and local transcript files staying usable. Anthropic may detect or block wrapper-style automation later, so test the exact tool before relying on it.
ralphex executes plans in four phases with automated code reviews, plus an optional finalize step.

### Task N: with - [ ] checkboxes)[x], commits changesSteering mid-run: Press Ctrl+\ (SIGQUIT) during a task iteration to pause execution. ralphex cancels the current Claude session and prompts "press Enter to continue, Ctrl+C to abort". While paused, you can edit the plan file — on Enter, the same task re-runs with a fresh session that re-reads the plan. Press Ctrl+C to abort cleanly. Not available on Windows.
Launches 5 review agents in parallel via Claude Code Task tool:
| Agent | Purpose |
|-------|---------|
| quality | bugs, security issues, race conditions |
| implementation | verifies code achieves stated goals |
| testing | test coverage and quality |
| simplification | detects over-engineering |
| documentation | checks if docs need updates |
Claude verifies findings, fixes confirmed issues, and commits.
Default agents provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See Customization for details.
The loop terminates when: all issues resolved, max iterations reached, stalemate detected (via --review-patience), or manual break via Ctrl+\ (SIGQUIT).
Stalemate detection: When the external tool and Claude can't agree on findings, the loop can waste tokens iterating to the max. Set --review-patience=N (or review_patience in config) to terminate after N consecutive rounds with no commits or working tree changes.
Manual break: Press Ctrl+\ (SIGQUIT) during the external review loop to terminate it immediately. The current executor run is cancelled via context cancellation. During the task phase, Ctrl+\ pauses instead — see Phase 1: Task Execution. Not available on Windows.
Supported tools:
See Custom External Review for details on using custom scripts.
quality + implementation) for final reviewcompleted/ folder on successSecond review agents are configurable via prompts/review_second.txt.