Autonomous plan execution with Claude Code

ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates Claude Code to execute implementation plans autonomously - no IDE plugins or cloud services required, just Claude Code 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.

Task Execution Screenshot

Review Mode Screenshot

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
• Streaming output - real-time progress with timestamps and colors
• Progress logging - detailed execution logs for debugging
• Web dashboard - browser-based real-time view with --serve flag
• Multiple modes - full execution, review-only, codex-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.

How It Works

ralphex executes plans in four phases with automated code reviews.

Execution Flow Diagram

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

Phase 2: First Code Review

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.

Phase 3: Codex External Review (optional)

1. Runs codex (GPT-5.2) for independent code review
2. Claude evaluates codex findings, fixes valid issues
3. Iterates until codex finds no open issues

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.

Plan Creation

Plans can be created in several ways:

• Claude Code - use slash commands like /ralphex-plan or your own planning workflows
• Manually - write markdown files directly in docs/plans/
• --plan flag - integrated option that handles the entire flow

The --plan flag provides a simpler integrated experience:

ralphex --plan "add health check endpoint"

Claude explores your codebase, asks clarifying questions via a terminal picker (fzf or numbered fallback), and generates a complete plan file in docs/plans/.

Example session:

$ ralphex --plan "add caching for API responses"
[10:30:05] analyzing codebase structure...
[10:30:12] found existing store layer in pkg/store/

QUESTION: Which cache backend?
  > Redis
    In-memory
    File-based

[10:30:45] ANSWER: Redis
[10:31:00] continuing plan creation...
[10:32:05] plan written to docs/plans/add-api-caching.md

Continue with plan implementation?
  > Yes, execute plan
    No, exit

After plan creation, you can choose to continue with immediate execution or exit to run ralphex later. Progress is logged to progress-plan-<name>.txt.

Installation

From source

go install github.com/umputun/ralphex/cmd/ralphex@latest

Using Homebrew

brew install umputun/apps/ralphex

From releases

Download the appropriate binary from releases.

Usage

Note: ralphex must be run from the repository root directory (where .git is located).

# execute plan with task loop + reviews
ralphex docs/plans/feature.md

# use fzf to select plan
ralphex

# review-only mode (skip task execution)
ralphex --review docs/plans/feature.md

# codex-only mode (skip tasks and first claude review)
ralphex --codex-only

# interactive plan creation
ralphex --plan "add user authentication"

# with custom max iterations
ralphex --max-iterations=100 docs/plans/feature.md

# with web dashboard
ralphex --serve docs/plans/feature.md

# web dashboard on custom port
ralphex --serve --port 3000 docs/plans/feature.md

Options

Flag	Description	Default
-m, --max-iterations	Maximum task iterations	50
-r, --review	Skip task execution, run full review pipeline	false
-c, --codex-only	Skip tasks and first review, run only codex loop	false
--plan	Create plan interactively (provide description)	-
-s, --serve	Start web dashboard for real-time streaming	false
-p, --port	Web dashboard port (used with --serve)	8080
-w, --watch	Directories to watch for progress files (repeatable)	-
-d, --debug	Enable debug logging	false
--no-color	Disable color output	false

Plan File Format

Plans are markdown files with task sections. Each task has checkboxes that claude marks complete.

# Plan: Add User Authentication

## Overview
Add JWT-based authentication to the API.

## Validation Commands
- `go test ./...`
- `golangci-lint run`

### Task 1: Add auth middleware
- [ ] Create JWT validation middleware
- [ ] Add to router for protected routes
- [ ] Add tests
- [ ] Mark completed

### Task 2: Add login endpoint
- [ ] Create /api/login handler
- [ ] Return JWT on successful auth
- [ ] Add tests
- [ ] Mark completed

Requirements:

• Task headers must use ### Task N: or ### Iteration N: format
• Checkboxes: - [ ] (incomplete) or - [x] (completed)
• Include ## Validation Commands section with test/lint commands
• Place plans in docs/plans/ directory (configurable via plans_dir)

Review Agents

The review pipeline is fully customizable. ralphex ships with sensible defaults that work for any language, but you can modify agents, add new ones, or replace prompts entirely to match your specific workflow.

Default Agents

These 5 agents cover common review concerns and work well out of the box. Customize or replace them based on your needs:

Agent	Phase	Purpose
quality	1st & 2nd	bugs, security issues, race conditions
implementation	1st & 2nd	verifies code achieves stated goals
testing	1st only	test coverage and quality
simplification	1st only	detects over-engineering
documentation	1st only	checks if docs need updates

Template Syntax

Reference agents in prompt files using {{agent:name}} syntax:

Launch the following review agents in parallel:
{{agent:quality}}
{{agent:implementation}}
{{agent:testing}}

Each {{agent:name}} expands to Task tool instructions that tell Claude Code to run that agent.

Customization

The entire system is designed for customization - both task execution and reviews:

Agent files (~/.config/ralphex/agents/):

• Edit existing files to modify agent behavior
• Add new .txt files to create custom agents
• Delete all files and restart to restore defaults
• Alternatively, reference agents already installed in your Claude Code directly in prompt files (see example below)

Prompt files (~/.config/ralphex/prompts/):

• task.txt - task execution prompt
• review_first.txt - comprehensive review (default: 5 language-agnostic agents - quality, implementation, testing, simplification, documentation; customizable)
• codex.txt - codex review prompt
• review_second.txt - final review, critical/major issues only (default: 2 agents - quality, implementation; customizable)

Comment syntax: Lines starting with # (after optional whitespace) are treated as comments and stripped when loading prompt and agent files. Use comments to document your customizations:

# security agent - checks for vulnerabilities
# updated: 2024-01-15
check for SQL injection
check for XSS

Note: Inline comments are not supported (text # comment keeps the entire line).

Examples:

• Add a security-focused agent for fintech projects
• Remove simplification agent if over-engineering isn't a concern
• Create language-specific agents (Python linting, TypeScript types)
• Modify prompts to change how many agents run per phase

Using Claude Code agents directly:

Instead of creating agent files, you can reference agents installed in your Claude Code directly in prompt files:

# in review_first.txt - just list agent names with their prompts
Agents to launch:
1. qa-expert - "Review for bugs and security issues"
2. go-test-expert - "Review test coverage and quality"
3. go-smells-expert - "Review for code smells"

Requirements

• claude - Claude Code CLI
• fzf - for plan selection (optional)
• codex - for external review (optional)

Configuration

ralphex uses a configuration directory at ~/.config/ralphex/ with the following structure:

~/.config/ralphex/
├── config              # main configuration file (INI format)
├── prompts/            # custom prompt templates
│   ├── task.txt
│   ├── review_first.txt
│   ├── review_second.txt
│   └── codex.txt
└── agents/             # custom review agents (*.txt files)

On first run, ralphex creates this directory with default configuration.

Local Project Config

Projects can override global settings with a .ralphex/ directory in the project root:

project/
├── .ralphex/           # optional, project-local config
│   ├── config          # overrides specific settings
│   ├── prompts/        # custom prompts for this project
│   └── agents/         # custom agents for this project

Priority: CLI flags > local .ralphex/ > global ~/.config/ralphex/ > embedded defaults

Merge behavior:

• Config file: per-field override (local values override global, missing fields fall back)
• Prompts: per-file fallback (local → global → embedded for each prompt file)
• Agents: replace entirely (if local agents/ has .txt files, use ONLY local agents)

Configuration options

Option	Description	Default
claude_command	Claude CLI command	claude
claude_args	Claude CLI arguments	--dangerously-skip-permissions --output-format stream-json --verbose
codex_enabled	Enable codex review phase	true
codex_command	Codex CLI command	codex
codex_model	Codex model ID	gpt-5.2-codex
codex_reasoning_effort	Reasoning effort level	xhigh
codex_timeout_ms	Codex timeout in ms	3600000
codex_sandbox	Sandbox mode	read-only
iteration_delay_ms	Delay between iterations	2000
task_retry_count	Task retry attempts	1
plans_dir	Plans directory	docs/plans
color_task	Task execution phase color (hex)	#00ff00
color_review	Review phase color (hex)	#00ffff
color_codex	Codex review color (hex)	#ff00ff
color_claude_eval	Claude evaluation color (hex)	#64c8ff
color_warn	Warning messages color (hex)	#ffff00
color_error	Error messages color (hex)	#ff0000
color_signal	Completion/failure signals color (hex)	#ff6464
color_timestamp	Timestamp prefix color (hex)	#8a8a8a
color_info	Informational messages color (hex)	#b4b4b4

Colors use 24-bit RGB (true color), supported natively by all modern terminals (iTerm2, Kitty, Terminal.app, Windows Terminal, GNOME Terminal, Alacritty, Zed, VS Code, etc). Older terminals will degrade gracefully. Use --no-color to disable colors entirely.

Custom prompts

Place custom prompt files in ~/.config/ralphex/prompts/ to override the built-in prompts. Missing files fall back to embedded defaults. See Review Agents section for agent customization.

FAQ

I installed ralphex, what do I do next?

Create a plan file in docs/plans/ (see Quick Start for format), then run ralphex docs/plans/your-plan.md. ralphex will create a branch, execute tasks, and run reviews automatically.

Why are there two review phases?

First review is comprehensive (5 agents by default), second is a final check focusing on critical/major issues only (2 agents). See How It Works.

How do I use my own Claude Code agents?

Reference them directly in prompt files by name, e.g., qa-expert - "Review for bugs". See Customization.

What if codex isn't installed?

Codex is optional. If not installed, the codex review phase is skipped automatically.

Can I run just reviews without task execution?

Yes, use --review flag. See CLI Options.

Can I run ralphex in a non-git directory?

No. Git is required for branch management, automatic commits, and diff-based code reviews.

Should I run ralphex on master or a feature branch?

For full mode, start on master - ralphex creates a branch automatically from the plan filename. For --review mode, switch to your feature branch first - reviews compare against master using git diff master...HEAD.

How do I restore default agents after customizing?

Delete all .txt files from ~/.config/ralphex/agents/ and restart ralphex.

How does local .ralphex/ config interact with global config?

Priority: CLI flags > local .ralphex/config > global ~/.config/ralphex/config > embedded defaults. Each local setting overrides the corresponding global one—no need to duplicate the entire file. For agents: if local agents/ has any .txt files, it replaces global agents entirely.

What happens to uncommitted changes if ralphex fails?

Ralphex commits after each completed task. If execution fails, completed tasks are already committed to the feature branch. Uncommitted changes from the failed task remain in the working directory for manual inspection.

What if ralphex is interrupted mid-execution?

Completed tasks are already committed to the feature branch. To resume, re-run ralphex docs/plans/<plan>.md. Ralphex detects completed tasks via [x] checkboxes in the plan and continues from the first incomplete task. For review sessions, simply restart. Reviews re-run from iteration 1, but fixes from previous iterations remain in the codebase.

What's the difference between progress file and plan file?

Progress file (progress-*.txt) is a real-time execution log—tail it to monitor. Plan file tracks task state ([ ] vs [x]). To resume, re-run ralphex on the plan file; it finds incomplete tasks automatically.

Do I need to commit changes before running ralphex?

No, but recommended. Ralphex creates a new branch and commits per-task. Pre-existing uncommitted changes stay untouched but may cause confusion about what's part of the plan.

What's the difference between agents/ and prompts/?

Agents define what to check (review instructions). Prompts define how the workflow runs (execution steps, signal handling).

Web Dashboard

The --serve flag starts a browser-based dashboard for real-time monitoring of plan execution.

ralphex --serve docs/plans/feature.md
# web dashboard: http://localhost:8080

Features

• Real-time streaming - SSE connection for live output updates
• Phase navigation - filter by All/Task/Review/Codex phases
• Collapsible sections - organized output with expand/collapse
• Text search - find text with highlighting (keyboard: / to focus, Escape to clear)
• Auto-scroll - follows output, click to disable
• Late-join support - new clients receive full history

The dashboard uses a dark theme with phase-specific colors matching terminal output. All file and stdout logging continues unchanged when using --serve.

Multi-Session Mode

The --watch flag enables monitoring multiple ralphex sessions simultaneously:

# watch specific directories for progress files
ralphex --serve --watch ~/projects/frontend --watch ~/projects/backend

# configure watch directories in config file
# watch_dirs = /home/user/projects, /var/log/ralphex

Multi-session features:

• Session sidebar - lists all discovered sessions, click to switch (keyboard: S to toggle)
• Active detection - pulsing indicator for running sessions via file locking
• Auto-discovery - new sessions appear automatically as they start

Claude Code Integration (Optional)

ralphex works standalone from the terminal. Optionally, you can add slash commands to Claude Code for a more integrated experience.

Available Commands

Command	Description
/ralphex	Launch and monitor ralphex execution with interactive mode/plan selection
/ralphex-plan	Create structured implementation plans with guided context gathering

Installation

The slash command definitions are hosted at:

• /ralphex
• /ralphex-plan

To install, ask Claude Code to "install ralphex slash commands" or manually copy the files to ~/.claude/commands/.

Usage

Once installed:

# in Claude Code conversation
/ralphex-plan add user authentication    # creates plan interactively
/ralphex docs/plans/auth.md              # launches execution
"check ralphex"                          # gets status update

The /ralphex command runs ralphex in the background and provides status updates on request. The /ralphex-plan command guides you through creating well-structured plans with context discovery and approach selection.

For LLMs

See llms.txt for LLM-optimized documentation.

License

MIT License - see LICENSE file.