umputun/ralphex

Autonomous plan execution with Claude Code and codex

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.

Features

• Zero setup - works out of the box with sensible defaults, no configuration required
• Autonomous task execution - executes plan tasks one at a time with automatic retry
• Interactive plan creation - create plans through dialogue with Claude via --plan flag
• Multi-phase code review - 5 agents → codex → 2 agents review pipeline
• Custom review agents - configurable agents with {{agent:name}} template system and user defined prompts
• Automatic branch creation - creates git branch from plan filename
• Plan completion tracking - moves completed plans to completed/ folder
• Automatic commits - commits after each task and review fix
• Real-time monitoring - streaming output with timestamps, colors, and detailed logs
• Web dashboard - browser-based real-time view with --serve flag
• Docker support - run in isolated container for safer autonomous execution
• Notifications - optional alerts on completion/failure via Telegram, Email, Slack, Webhook, or custom script
• Worktree isolation - run multiple plans in parallel via --worktree flag
• Multiple modes - full execution, tasks-only, review-only, external-only, or plan creation

Quick Start

Make 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 uses claude --print internally, so unattended ralphex runs are part of that pool. See Anthropic's Agent SDK credit article for the current billing rules.

Practical options:

1. 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.
2. Use a skill-based flow in an interactive Claude Code session. The author's umputun/cc-thingz plugin collection includes the planning family (/planning:make and /planning:exec). That keeps work inside the normal interactive Claude Code flow instead of claude --print.
3. Switch the ralphex executor to codex. First-class --codex support routes plan creation, task execution, both review phases, and finalize through the codex CLI and skips the external codex review phase.
4. Use a claude -p compatible wrapper that drives an interactive Claude Code session and emits Claude-compatible stream-json. Examples that match ralphex's invocation shape include umputun/fya, melonamin/agentrun, Equality-Machine/claude-p, and kcosr/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.

How It Works

ralphex executes plans in four phases with automated code reviews, plus an optional finalize step.

Phase 1: Task Execution

1. Reads plan file and finds first incomplete task (### Task N: with - [ ] checkboxes)
2. Sends task to Claude Code for execution
3. Runs validation commands (tests, linters) after each task
4. Marks checkboxes as done [x], commits changes
5. Repeats until all tasks complete or max iterations reached

Steering 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.

Phase 2: First Code Review

Launches 5 review agents in parallel via Claude Code Task tool:

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.

Phase 3: External Review (optional)

1. Runs external review tool (codex by default, or custom script)
2. Claude evaluates findings, fixes valid issues
3. Iterates until no open issues

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:

• codex (default): OpenAI Codex for independent code review
• custom: Your own script wrapping any AI (OpenRouter, local LLM, etc.)
• none: Skip external review entirely

See Custom External Review for details on using custom scripts.

Phase 4: Second Code Review

1. Launches 2 agents (quality + implementation) for final review
2. Focuses on critical/major issues only
3. Iterates until no issues found
4. Moves plan to completed/ folder on success

Second review agents are configurable via prompts/review_second.txt.

Finalize Step (optional)

After all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.

What it does: runs a single Claude Code session with a customizable prompt. The default finalize.txt prompt rebases commits onto the default branch and optionally squashes related commits into logical groups.

How to enable:

Set finalize_enabled = true in ~/.config/ralphex/config or .ralphex/config.

Behavior:

• Runs once (no iteration loop)
• Best-effort — failures are logged but don't block success
• Triggers on modes with review pipeline: full, review-only, external-only
• Uses task color (green) for output

Customization:

Edit ~/.config/ralphex/prompts/finalize.txt (or .ralphex/prompts/finalize.txt) to change what happens after reviews. Examples: push to remote, send notifications, run deployment scripts, or any post-completion automation. Template variables like {{DEFAULT_BRANCH}} are available.

Plan Move Behavior (optional)

After successful execution, ralphex moves the plan file into docs/plans/completed/. Enabled by default.

How to disable:

Set move_plan_on_completion = false in ~/.config/ralphex/config or .ralphex/config. Default is true.

When to disable: workflows that manage plan file lifecycle externally (e.g. spec-driven tooling where the plan lives inside a bundle that a separate archive step consumes) should opt out so ralphex doesn't fight the external tool's file layout.

Review-Only Mode

Review-only mode (--review) runs the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already present on the current branch. This is useful when changes were made outside ralphex — via Claude Code's built-in plan mode, manual edits, other AI agents, or any other workflow.

Workflow:

1. Make changes on a feature branch (using any tool or workflow)
2. Commit the changes
3. Run ralphex --review

ralphex compares the branch against the default branch (git diff master...HEAD), launches multi-agent reviews, and iterates fixes until all agents report clean. No plan file is required — if provided, it gives reviewers additional context about the intended changes.

# switch to feature branch with existing changes
git checkout feature-auth

# run review pipeline on those changes
ralphex --review

# optionally pass a plan file for context
ralphex --review docs/plans/add-auth.md

External-Only Mode

External-only mode (--external-only, alias -e) skips the task and first review phases and runs the external review pipeline (Phase 3 → Phase 4) on changes already present on the current branch. The flag name follows the same cutoff convention as --review: it marks where execution starts, not which single phase runs. After the external review loop converges (or hits its iteration limit), the post-external critical/major review (Phase 4) runs to catch regressions from fixes applied during the loop.

If the external review loop finds no issues on its first pass, Phase 4 is skipped automatically because there is nothing to regress.

# run external review pipeline on current branch changes
ralphex --external-only

# optionally pass a plan file for context
ralphex --external-only docs/plans/feature.md

Codex Executor Mode

The --codex flag routes interactive plan creation (--plan), task execution, both review phases, and the optional finalize step through the codex CLI instead of Claude Code. The external review phase is automatically skipped because codex-reviewing-codex is a same-model self-review with weak signal; the cross-model independence between Claude and codex was the original reason that phase existed.

Why this exists: in June 2026 Anthropic split the Claude Max subscription from the Claude Agent SDK, putting unattended ralphex runs on a separate $200 credit pool rather than the Max plan. Users with an OpenAI/codex plan can switch the entire ralphex pipeline to codex with one flag and stay on their existing OpenAI subscription instead.

# create a plan through codex
ralphex --codex --plan "add user authentication"

# run the full pipeline (task, first review, second review, finalize) through codex
ralphex --codex docs/plans/feature.md

# additionally let codex read project CLAUDE.md as AGENTS.md
ralphex --codex --pass-claude-md docs/plans/feature.md

How it differs from codex-as-claude.sh: the --codex flag is the native codex path. It calls the codex CLI directly and configures multi-agent reviews through additive -c flag overrides on the codex command line. Review prompts are shared with claude. The {{agent:<name>}} expansion produces spawn_agent calls for codex and Task-tool calls for claude at runtime. The scripts/codex-as-claude/codex-as-claude.sh wrapper still exists for backwards compatibility. It translates codex JSONL output into Claude stream-json events, which adds overhead and keeps Claude-flavored prompt vocabulary in front of a