Ralphex: Autonomous AI-Driven Plan Execution

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:

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: 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 codex model.

Project CLAUDE.md passthrough (--pass-claude-md): adds -c project_doc_fallback_filenames=["CLAUDE.md"] to the codex invocation so codex's native AGENTS.md walk picks up the project-level ./CLAUDE.md file. This works for project-level CLAUDE.md only. For user-level ~/.claude/CLAUDE.md, ralphex never modifies the user's ~/.codex/ directory. If ~/.claude/CLAUDE.md exists and ~/.codex/AGENTS.md does not, ralphex prints a one-time hint suggesting ln -s ~/.claude/CLAUDE.md ~/.codex/AGENTS.md and continues; the user opts in by running the command themselves.

Configuration alternative: instead of passing --codex every run, set it in ~/.config/ralphex/config or .ralphex/config:

executor       = codex
pass_claude_md = true

When executor = codex is set in config and the user has also set external_review_tool = codex (or custom), ralphex automatically overrides external_review_tool to none and prints a warning to stderr that the config-file value was overridden. Only CLI-flag conflicts are hard errors; config-only conflicts resolve with a warning.

Mutual exclusion: the codex executor (whether enabled via --codex or executor = codex in config) cannot be combined with --external-only (alias -e), --codex-only (alias -c), or --external-review-tool=<X> where <X> is not none. --pass-claude-md requires the codex executor (CLI --codex or config executor = codex). Each combination fails with a clear error message at startup.

Requirements: --codex requires the codex CLI version 0.130.0 or newer. The mode relies on [features] multi_agent, [agents.<name>] agent registration, and (with --pass-claude-md) project_doc_fallback_filenames, all supported in 0.130.0. Older codex versions silently ignore unknown -c overrides, so a misconfigured run will not error visibly. It will simply behave as if the overrides were absent. There is no runtime version check; verify your codex version with codex --version if behavior is unexpected.

Model selection under --codex: under --codex the --plan-model / --task-model / --review-model flags (and their config equivalents plan_model / task_model / review_model) select the model and effort per phase. --plan-model sets plan creation and falls back to --task-model when unset. --task-model sets the task phase. --review-model sets the review phase and falls back to --task-model when unset. Codex builds a separate review executor when the resolved review model/effort differs from task, so tasks and reviews can run on different codex models. Each model[:effort] spec is resolved against codex_model / codex_reasoning_effort (default gpt-5.5 / xhigh): an unset spec inherits those defaults, and each populated half overrides its default (--task-model=:high changes effort only). The max effort level is claude-only. A spec requesting it under --codex is warned about and ignored. So codex model selection is: --plan-model / --task-model / --review-model (CLI or config), then codex_model / codex_reasoning_effort in ralphex config, applied as -c overrides to the codex CLI; set either codex value to empty (e.g. codex_model =) in your user config to inherit that field from ~/.codex/config.toml instead. Commenting the line out keeps the embedded default. The startup banner under --codex shows the resolved plan/task model/effort for the current mode, plus a separate review model / review reasoning effort line when the review phase resolves differently.

Worktree Isolation

The --worktree flag runs plan execution in an isolated git worktree at .ralphex/worktrees/<branch>, enabling parallel execution of multiple plans on the same repo without branch conflicts.

Supported modes: --worktree only applies to full mode and --tasks-only. It is silently ignored for --review, --external-only, and --plan — these modes operate from the current directory.

Re-running reviews on a worktree branch: if the task phase completed in a worktree but the review phase needs to be re-run, cd into the worktree directory and run the review from there:

# find the worktree
ls .ralphex/worktrees/

# run review from inside it
cd .ralphex/worktrees/my-feature-branch
ralphex --review
# or
ralphex --external-only

Worktrees are automatically removed on successful completion. If a run is interrupted, the worktree directory may remain and can be reused or removed manually.

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
• Auto-detection - running ralphex without arguments on master/main prompts for plan creation if no plans exist

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/. When reviewing the draft, you can accept, revise with text feedback, open it in $EDITOR for interactive annotation, or reject it.

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
    Other (type your own answer)

[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 .ralphex/progress/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.

Using Docker

Download the wrapper script and install to PATH:

curl -sL https://raw.githubusercontent.com/umputun/ralphex/master/scripts/ralphex-dk.sh -o /usr/local/bin/ralphex
chmod +x /usr/local/bin/ralphex

The script defaults to the Go image (ralphex-go). For other languages, build a custom image from the base with your toolchain installed (see Available images for examples), then point the wrapper at it:

export RALPHEX_IMAGE=my-ralphex

Then use ralphex as usual - it runs in a container with Claude Code and Codex pre-installed. The script shows which image it's using at startup.

Why use Docker? ralphex runs Claude Code with --dangerously-skip-permissions, giving it full access to execute commands and modify files. Running in a container provides isolation - Claude can only access the mounted project directory, not your entire system. This makes autonomous execution significantly safer.

Container CAN access (read-write):

• Project directory mounted at /workspace - full access to create, modify, delete files
• Git operations within the project (branch, commit, etc.)

Container CAN access (read-only):

• ~/.claude/ - credentials and settings (copied at startup, not modified)
• ~/.codex/ - codex credentials if present
• ~/.config/ralphex/ - user-level ralphex configuration
• ~/.gitconfig - git identity for commits
• Global gitignore (core.excludesFile) - auto-detected and mounted
• .ralphex/ - project-level configuration if present

Container CANNOT access:

• Host filesystem outside mounted directories
• Other projects or repositories
• SSH keys, AWS credentials, or other secrets in ~/.ssh, ~/.aws, etc.
• System files, binaries, or configurations
• Other running processes or containers

Network: Full network access (required for Claude API calls)

Privileges: Runs as non-root user with no elevated capabilities

Volume mounts:

• Read-only: ~/.claude and ~/.codex mounted to /mnt/, copied at startup to preserve isolation
• Read-write: project directory (/workspace) - where ralphex creates branches, edits code, and commits
• Extra mounts: user-defined volumes via -v/--volume flags or RALPHEX_EXTRA_VOLUMES env var

Requirements:

• Python 3.9+ (for the wrapper script)
• Docker installed and running
• Claude Code credentials in ~/.claude/ (or in $CLAUDE_CONFIG_DIR when set)
• Codex credentials in ~/.codex/ (optional, for codex review phase)
• Git config in ~/.gitconfig (for commits)

Environment variables:

• RALPHEX_IMAGE - Docker image to use (default: ghcr.io/umputun/ralphex-go:latest). CLI flag: --image
• RALPHEX_PORT - Port for web dashboard when using --serve (default: 8080). CLI flag: --port
• RALPHEX_CONFIG_DIR - Custom config directory (default: ~/.config/ralphex). Overrides global config location for prompts, agents, and settings
• CLAUDE_CONFIG_DIR - Claude config directory (default: ~/.claude). Use for alternate Claude installations (e.g., ~/.claude2). Works both with Docker wrapper (volume mounts and keychain derivation) and non-Docker usage (passed through to Claude Code directly). Keychain service name is derived automatically from the path.
• RALPHEX_EXTRA_VOLUMES - Extra volume mounts, comma-separated (e.g., /data:/mnt/data:ro,/models:/mnt/models). Entries without : are silently skipped
• RALPHEX_EXTRA_ENV - Extra environment variables, comma-separated (e.g., DEBUG=1,API_KEY). Format: VAR=value or VAR (inherit from host). Security warning emitted for sensitive names (KEY, SECRET, TOKEN, etc.) with explicit values - use name-only form for secure credential passing
• RALPHEX_DOCKER_SOCKET - Enable Docker socket mount: 1, true, or yes (Docker wrapper only). CLI flag: --docker
• RALPHEX_DOCKER_NETWORK - Docker network mode (e.g., host, my-network). Useful for reaching docker-compose services. CLI flag: --network
• RALPHEX_CLI_UPDATE - Refresh claude/codex to their current npm releases at container start: 1, true, or yes (Docker images only). Off by default in the base image; baked on in ralphex-go
• TZ - Override container timezone (default: auto-detected from host via /etc/localtime). Example: TZ=Europe/Berlin ralphex docs/plans/feature.md
• RALPHEX_CLAUDE_PROVIDER - Claude provider mode: default or bedrock (Docker wrapper only)

CLI freshness in the container:

The image installs claude and codex unpinned, so a published tag freezes them at whatever npm served on that build. Both ship far more often than ralphex is tagged, and a stale claude fails silently rather than loudly: a short model alias like sonnet resolves to whatever that build knew about, so --task-model=sonnet can quietly run an older model. Claude's own updater cannot help here, since npm installs it root-owned and the container runs as the app user.

Setting RALPHEX_CLI_UPDATE=1 refreshes both CLIs to their current npm releases on start, before dropping privileges. It usually adds about 5 seconds and is capped by a 90 second deadline. Best effort: if npm fails or the deadline is hit, the versions baked into the image are used and the run continues. If the install succeeds but a CLI does not run, the container says so rather than failing later without explanation.

The base ralphex image leaves this off so anyone building on it gets no surprise npm install, network call, or version drift at container start. The ralphex-go image (the wrapper's default) bakes it on, so the common path stays current. Enable it yourself for a single run:

RALPHEX_CLI_UPDATE=1 ralphex docs/plans/feature.md

Or bake it into a custom image so every run refreshes:

FROM ghcr.io/umputun/ralphex:latest
ENV RALPHEX_CLI_UPDATE=1

Docker socket support:

The --docker flag (or RALPHEX_DOCKER_SOCKET=1) mounts the host Docker socket into the container, enabling testcontainers and Docker-dependent workflows:

ralphex --docker docs/plans/feature.md
ralphex --docker --dry-run   # verify socket mount in command

• Auto-detects socket GID and passes DOCKER_GID env var for baseimage group setup
• Emits security warning on Linux (macOS has VM isolation, no warning needed)
• Exits with error if socket file doesn't exist (fail-fast, no silent degradation)

AWS Bedrock support:

When --claude-provider=bedrock or RALPHEX_CLAUDE_PROVIDER=bedrock is set:

• Keychain credential extraction is skipped (not needed for Bedrock auth)
• AWS credentials are automatically exported from AWS_PROFILE via aws configure export-credentials
• Required Bedrock env vars are passed to container: CLAUDE_CODE_USE_BEDROCK, AWS_REGION, credentials

Required environment for Bedrock:

• AWS_REGION - AWS region where Bedrock is enabled
• AWS_PROFILE or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY - authentication

Note: CLAUDE_CODE_USE_BEDROCK=1 is automatically set when using --claude-provider=bedrock.

# with AWS profile (credentials exported automatically)
export AWS_PROFILE=my-bedrock-profile
export AWS_REGION=us-east-1
ralphex --claude-provider=bedrock docs/plans/feature.md

# or use env var for session-wide setting
export RALPHEX_CLAUDE_PROVIDER=bedrock
ralphex docs/plans/feature.md

See Bedrock setup documentation for detailed IAM policies and setup instructions.

Extra volume mounts:

# via CLI flags (can use multiple -v)
ralphex -v /data:/mnt/data:ro -v /models:/mnt/models docs/plans/feature.md

# via environment variable (comma-separated)
RALPHEX_EXTRA_VOLUMES="/data:/mnt/data:ro,/models:/mnt/models" ralphex docs/plans/feature.md

Extra environment variables:

# via CLI flags (can use multiple -E)
ralphex -E DEBUG=1 -E API_KEY docs/plans/feature.md

# via environment variable (comma-separated)
RALPHEX_EXTRA_ENV="DEBUG=1,LOG_LEVEL=verbose" ralphex docs/plans/feature.md

# name-only form inherits value from host (recommended for secrets)
export API_KEY=secret123
ralphex -E API_KEY docs/plans/feature.md

# values containing commas require -E flag (env var splits on commas)
ralphex -E "TAGS=foo,bar,baz" docs/plans/feature.md

Debugging:

ralphex --dry-run docs/plans/feature.md  # show docker command without executing

The --dry-run flag prints the full docker run command that would be executed. Useful for debugging container configuration or copying the command for manual execution.

Note: inherited env vars (-E FOO without =value) won't work when copying the command to a different shell. Use explicit values for portability.

Updating:

ralphex --update         # pull latest docker image
ralphex --update-script  # update the wrapper script itself

Two images are published:

Image	Description
ghcr.io/umputun/ralphex:latest	Base image with Claude Code, Codex, and core tools
ghcr.io/umputun/ralphex-go:latest	Go development (extends base with Go toolchain)

Base image includes:

Tool	Version	Purpose
Claude Code	latest	AI coding assistant
Codex	latest	External code review
fya	latest	Optional claude print-mode wrapper (PTY-backed)
Node.js/npm	24.x	Required for Claude Code
Python/pip	3.x	Scripts and automation
git	2.x	Version control
docker-cli	-	Docker client for container workflows
make	4.x	Build automation
gcc, musl-dev	-	C compiler for native extensions
bash	5.x	Shell
fzf	-	Fuzzy finder for plan selection
ripgrep	-	Fast search (used by Claude Code)

Go image adds:

Tool	Version	Purpose
Go	1.26.0	Go compiler and runtime
golangci-lint	latest	Go linter
moq	latest	Mock generator
goimports	latest	Import formatter

For Go projects, use the -go image:

RALPHEX_IMAGE=ghcr.io/umputun/ralphex-go:latest ralphex docs/plans/feature.md

For other languages, create a custom image by extending the base with your language toolchain. The Go image (Dockerfile-go) shows the pattern:

FROM ghcr.io/umputun/ralphex:latest

# install go from official distribution
ARG GO_VERSION=1.26.0
RUN ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') && \
    wget -qO- "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" | tar -xz -C /usr/local

ENV GOROOT=/usr/local/go
ENV GOPATH=/home/app/go
ENV PATH="${PATH}:${GOROOT}/bin:${GOPATH}/bin"

# install go tools
RUN wget -qO- https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin && \
    GOBIN=/usr/local/bin go install github.com/matryer/moq@latest && \
    GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest

Same approach for Rust, Java, or any other language:

FROM ghcr.io/umputun/ralphex:latest

# rust
RUN apk add --no-cache rust cargo
ENV CARGO_HOME=/home/app/.cargo PATH="${PATH}:${CARGO_HOME}/bin"

# java
RUN apk add --no-cache openjdk21-jdk
ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk PATH="${PATH}:${JAVA_HOME}/bin"

Add ENV RALPHEX_CLI_UPDATE=1 to your image if you want it to refresh claude/codex to the latest npm release on every container start, the way ralphex-go does. The base image leaves it off.

Build and use:

docker build -t my-ralphex -f Dockerfile.python .
RALPHEX_IMAGE=my-ralphex ralphex docs/plans/feature.md

Example with custom port:

RALPHEX_PORT=3000 ralphex --serve --port=3000 docs/plans/feature.md

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

# select plan with fzf, or create one interactively if none exist
ralphex

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

# external-only mode (skip tasks and first review, run only external review loop)
ralphex --external-only

# codex executor mode (run task, review, and finalize phases through codex; skip external review)
ralphex --codex docs/plans/feature.md

# codex executor mode with project CLAUDE.md passthrough (codex reads CLAUDE.md as AGENTS.md)
ralphex --codex --pass-claude-md docs/plans/feature.md

# tasks-only mode (run only task phase, skip all reviews)
ralphex --tasks-only docs/plans/feature.md

# run in isolated git worktree (full and tasks-only modes only)
ralphex --worktree docs/plans/feature.md

# override default branch for review diffs
ralphex --review --base-ref develop
ralphex --review --base-ref abc1234 --skip-finalize

# initialize local .ralphex/ config in current project (commented-out defaults)
ralphex --init

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

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

# limit external review iterations (0 = auto, derived from max-iterations)
ralphex --max-external-iterations=5 docs/plans/feature.md

# terminate external review after 3 unchanged rounds (stalemate detection)
ralphex --review-patience=3 docs/plans/feature.md

# wait and retry on rate limit (instead of exiting)
ralphex --wait=1h docs/plans/feature.md

# use a stronger model for plan creation
ralphex --plan-model=fable:high --plan="add caching"

# use different models for tasks and reviews
ralphex --task-model=opus --review-model=sonnet:low docs/plans/feature.md

# use provider overrides for one run without editing config
ralphex --claude-command=/path/to/codex-as-claude.sh --external-review-tool=custom --custom-review-script=/path/to/review.sh docs/plans/feature.md

# set per-session timeout to kill hanging sessions (external review in Claude mode excluded)
ralphex --session-timeout=30m docs/plans/feature.md

# kill claude/codex executor session when no output for 5 minutes
ralphex --idle-timeout=5m docs/plans/feature.md

# preserve ANTHROPIC_API_KEY in the claude child env (for API-key auth users)
ralphex --preserve-anthropic-api-key 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
--max-external-iterations	Override external review iteration limit (0 = auto)	0
--review-patience	Terminate external review after N unchanged rounds (0 = disabled)	0
-r, --review	Skip task execution, run full review pipeline	false
-e, --external-only	Skip tasks and first review, run only external review loop	false
-c, --codex-only	Alias for --external-only (deprecated)	false
--codex	Use codex CLI as the executor for plan creation, task, review, and finalize phases. Skips the external review phase (codex-reviewing-codex is a same-model self-review with weak signal). Requires codex CLI ≥ 0.130.0	false
--pass-claude-md	Pass project CLAUDE.md to codex via -c project_doc_fallback_filenames=["CLAUDE.md"]. User-level ~/.claude/CLAUDE.md is NOT auto-passed (a one-time setup hint is shown). Requires the codex executor (--codex or executor = codex)	false
-t, --tasks-only	Run only task phase, skip all reviews	false
-b, --base-ref	Override default branch for review diffs (branch name or commit hash)	auto-detect
--skip-finalize	Skip finalize step even if enabled in config	false
--plan-model	Model for plan creation as model[:effort] (falls back to --task-model). Same syntax and wrapper behavior as --task-model. Under --codex, selects the codex plan-creation model/effort	empty
--task-model	Model for task execution as model[:effort] (e.g., opus, opus:high, :medium). Effort values: low, medium, high, xhigh, max. Appended as --model <m> and/or --effort <e> to claude_command; custom wrappers may ignore or implement the flags. Under --codex, selects the codex task-phase model/effort instead (see Model selection under --codex)	empty
--review-model	Model for review phases as model[:effort] (falls back to --task-model). Same syntax and wrapper behavior as --task-model. Under --codex, selects the codex review-phase model/effort	empty
--claude-command	Override the Claude-compatible command for this run	config/default
--claude-args	Override Claude-compatible command arguments for this run. Use --claude-args= to clear configured/default args	config/default
--external-review-tool	Override external review tool for this run (codex, custom, or none)	config/default
--custom-review-script	Override custom external review script for this run	config/default
--wait	Wait duration before retrying on rate limit (e.g., 1h, 30m)	disabled
--session-timeout	Per-session timeout for task/review executor (e.g., 30m, 1h). Applies to Claude calls in default executor mode and every executor call under --codex; external codex/custom review in Claude mode is not affected	disabled
--idle-timeout	Kill executor session when no output for specified duration (e.g., 5m). Resets on each output line. Applies to the claude executor in default mode and to every executor call under --codex; external codex review in default-claude mode is NOT affected (preserves master behavior). Custom review is also not affected	disabled
--worktree	Run in isolated git worktree (full and tasks-only modes only)	false
--preserve-anthropic-api-key	Pass ANTHROPIC_API_KEY through to claude (for users authenticating Claude Code via API key rather than OAuth/keychain)	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
`--n