# ralphex Autonomous plan execution with Claude Code. Executes implementation plans task by task in fresh Claude sessions, then runs multi-phase code reviews. Write a plan, start ralphex, walk away. **GitHub:** https://github.com/umputun/ralphex ## Installation ```bash # from source go install github.com/umputun/ralphex/cmd/ralphex@latest # using homebrew brew install umputun/apps/ralphex # from releases: https://github.com/umputun/ralphex/releases ``` ## Quick Usage ```bash # 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 — run multi-agent reviews on existing branch changes # works for changes made by any tool (Claude Code, manual edits, other agents) ralphex --review ralphex --review docs/plans/feature.md # optional plan file for context # external-only mode (skip tasks and first claude review, run only external review) ralphex --external-only # codex executor mode (run task, review, finalize phases through codex; skip external review) # avoids the June 15, 2026 Anthropic billing split for Max-subscription users on an OpenAI plan 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 # 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 different models for tasks vs reviews (e.g., opus for tasks, sonnet for reviews) ralphex --task-model=opus --review-model=sonnet docs/plans/feature.md # override Claude-compatible provider and external review tool for one run ralphex --claude-command=/path/to/codex-as-claude.sh --claude-args= --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 # codex-only mode (alias for --external-only, deprecated) ralphex --codex-only # 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; ignored for --review/--external-only) ralphex --worktree docs/plans/feature.md # override branch name when auto-detection is fragile (generic filenames, spec-driven layouts) ralphex --worktree --branch=my-feature docs/plans/tasks.md ralphex --branch=my-feature docs/plans/tasks.md # override default branch for review diffs (useful for comparing against specific ref) ralphex --review --base-ref develop ralphex --review --base-ref abc1234 --skip-finalize # interactive plan creation — Claude asks questions, generates draft, # user reviews with accept/revise/interactive review ($EDITOR)/reject ralphex --plan "add user authentication" # initialize local .ralphex/ config in current project (commented-out defaults) ralphex --init # reset global config to defaults (interactive) ralphex --reset # extract raw embedded defaults for comparison ralphex --dump-defaults=/tmp/ralphex-defaults # use custom config directory ralphex --config-dir=~/my-config docs/plans/feature.md RALPHEX_CONFIG_DIR=~/my-config ralphex docs/plans/feature.md # use AWS Bedrock for Claude (Docker wrapper only) ralphex --claude-provider=bedrock docs/plans/feature.md RALPHEX_CLAUDE_PROVIDER=bedrock ralphex 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 ``` ## Requirements - `claude` - Claude Code CLI (required) - `fzf` - for plan selection (optional) - `codex` - for external review (optional) - `gemini` - alternative provider for Claude phases (optional, via `scripts/gemini-as-claude/`) ## Customization Configuration directory: `~/.config/ralphex/` (override with `--config-dir` or `RALPHEX_CONFIG_DIR`) **Prompt files** (`~/.config/ralphex/prompts/`): `task.txt`, `review_first.txt`, `review_second.txt`, `codex.txt`, `codex_review.txt`, `custom_review.txt`, `custom_eval.txt`, `make_plan.txt`, `finalize.txt`. Loading priority for each: local → global → embedded. Review prompts are shared between claude and codex executors — the `{{agent:}}` expansion produces the executor-appropriate agent invocation syntax (Task tool for claude, spawn_agent for codex). **Agent files** (`~/.config/ralphex/agents/`): Custom review agents referenced via `{{agent:name}}` in prompts. On first run, 5 default agents are installed as commented-out templates. Agents use per-file fallback (local → global → embedded) — embedded defaults are always the baseline, so deleting an agent file does not disable it. To disable a specific agent, remove its `{{agent:name}}` reference from the prompt files, not the agent file itself **Template variables** (available in prompt and agent files): - `{{PLAN_FILE}}` - path to plan file - `{{PROGRESS_FILE}}` - path to progress log - `{{GOAL}}` - goal description - `{{DEFAULT_BRANCH}}` - detected default branch (main, master, etc.), overridable via `--base-ref` CLI flag or `default_branch` config option - `{{agent:name}}` - expands to Task tool instructions for named agent - `{{DIFF_INSTRUCTION}}` - git diff command for current iteration (in codex_review.txt and custom_review.txt) - `{{PREVIOUS_REVIEW_CONTEXT}}` - previous review context for external review iterations (in codex_review.txt and custom_review.txt) **External review iterations:** By default, external review runs up to `max(3, max_iterations/5)` iterations. Override with `max_external_iterations` config option or `--max-external-iterations` CLI flag (0 = auto). **Stalemate detection:** `review_patience` config option (or `--review-patience` CLI flag) terminates the external review loop early when Claude produces no commits for N consecutive rounds. Set to 0 (default) to disable. Useful when the external tool and Claude can't agree on findings. **Per-phase model configuration:** `task_model` config option (or `--task-model` CLI flag) sets the model for task execution using `model[:effort]` syntax. Examples: `opus` (model only), `opus:high` (both), `:medium` (effort only). Effort levels: `low`, `medium`, `high`, `xhigh`, `max`. `review_model` (or `--review-model`) sets the model/effort for review phases; falls back to `task_model` if empty. Parts are appended to the configured `claude_command` as `--model ` and/or `--effort `. Custom wrappers may ignore the flags (default behavior via `*) shift ;;`) or map them to their own selection. Empty by default (uses Claude CLI's defaults). ```ini # in ~/.config/ralphex/config task_model = opus:high review_model = sonnet:medium ``` **Manual break (Ctrl+\):** Press Ctrl+\ (SIGQUIT) to intervene during execution. In the task phase, it pauses execution and prompts "press Enter to continue, Ctrl+C to abort" — on Enter the same task re-runs with a fresh session that re-reads the plan file, so you can edit the plan mid-run. In the external review phase, it terminates the loop immediately. Not available on Windows. **Custom external review:** Set `external_review_tool = custom` and `custom_review_script = /path/to/script.sh` to use your own AI tool instead of codex. Script receives prompt file path as single argument, outputs findings to stdout. ralphex passes the output to Claude for evaluation and fixing. For a one-off run, use `--external-review-tool=custom --custom-review-script=/path/to/script.sh`. **Alternative providers for Claude phases:** `claude_command` and `claude_args` config options allow replacing Claude Code with any CLI that produces compatible stream-json output. A codex wrapper is included at `scripts/codex-as-claude/codex-as-claude.sh`. Set `claude_command = /path/to/wrapper` in config, or use `--claude-command=/path/to/wrapper --claude-args=` for one run. The empty CLI value intentionally clears configured/default args for that invocation. Wrappers should ignore unknown flags gracefully. See `docs/custom-providers.md` for details on writing wrappers for other tools (Gemini CLI, local LLMs, etc.). **Codex executor mode (`--codex`):** native codex alternative for running the full pipeline on codex. `--codex` routes task execution, both review phases, and finalize through the codex CLI; the external review phase is automatically skipped (codex-reviewing-codex is a same-model self-review with weak signal). Motivated by Anthropic's June 15, 2026 billing split between the Claude Max subscription and the Claude Agent SDK credit pool — users with an OpenAI plan can stay on their existing subscription. `--pass-claude-md` (valid with the codex executor: `--codex` or `executor = codex`) adds `-c project_doc_fallback_filenames=["CLAUDE.md"]` to the codex invocation so codex's native AGENTS.md walk picks up the project `./CLAUDE.md`. User-level `~/.claude/CLAUDE.md` is NOT auto-linked — ralphex never modifies `~/.codex/`. At first `--codex --pass-claude-md` run, 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`; the user opts in by running the command themselves. Config equivalents: ```ini # in ~/.config/ralphex/config executor = codex pass_claude_md = true ``` Mutual exclusion: `--codex` cannot be combined with `--external-only`, `--codex-only`, or `--external-review-tool=` (when `` is not `none`). `--pass-claude-md` requires the codex executor (`--codex` or `executor = codex`). Each invalid combination fails with a clear error at startup. Config-only conflicts (e.g., `executor = codex` plus `external_review_tool = codex`) are automatically resolved by forcing `external_review_tool = none`, with a warning printed to stderr. Codex defaults that differ by mode: - `codex_sandbox` default is `read-only` for external codex review (default claude mode) and `danger-full-access` for first-class `executor = codex` (task/review/finalize need to write git metadata and commit). The accessor `CodexExecutorSandbox()` returns the role-appropriate default unless the user sets `codex_sandbox` explicitly. - `codex_model` and `codex_reasoning_effort` defaults (`gpt-5.5` / `xhigh`) ship as active values in the embedded config so external codex review in default-claude mode keeps stable settings across upgrades. Comment those lines out in your user config to inherit from `~/.codex/config.toml` instead. - `idle_timeout` applies to first-class `--codex` sessions only. External codex review in default-claude mode keeps master semantics (no idle timeout) so users with `idle_timeout` configured for claude don't see new early-terminations on the external review phase. - ANTHROPIC_API_KEY is stripped from codex child env only under first-class `--codex`. External codex review in default-claude mode preserves the host env so custom codex wrappers proxying through Anthropic (e.g., `scripts/codex-as-claude/codex-as-claude.sh`) keep authenticating. Requirements: codex CLI ≥ 0.130.0. Older versions silently ignore unknown `-c` overrides, so a misconfigured run will not error visibly. There is no runtime version check; verify with `codex --version`. **Configurable VCS backend:** `vcs_command` config option overrides the default `git` binary for all backend operations. Set to a translation script (e.g., `scripts/hg2git/hg2git.sh`) to use ralphex with Mercurial repos. The included `hg2git.sh` maps git subcommands to hg equivalents with phase-based commit logic (amend on draft, commit on public). See `docs/hg-support.md` for setup. **Commit trailer:** `commit_trailer` config option appends a custom trailer line to all ralphex-orchestrated git commits (both Go-code commits and LLM-prompted commits). When set, the trailer is appended after a blank line at the end of every commit message. Example: `commit_trailer = Co-authored-by: ralphex `. Disabled by default. **Session timeout:** `--session-timeout` flag (or `session_timeout` config option) sets a per-session timeout. In default Claude executor mode it applies only to claude task/review/eval calls — external codex and custom review are NOT subject to the timeout (preserves existing behavior). Under `--codex`, the timeout applies to every executor call (task, review, finalize, evaluation). When a session exceeds the timeout (e.g., agent starts a blocking operation), the session is killed and the phase loop continues to the next iteration. Disabled by default. **Idle timeout:** `--idle-timeout` flag (or `idle_timeout` config option) kills executor sessions when no output is received for a specified duration. Unlike session timeout (fixed wall-clock limit), idle timeout resets on each output line and only fires when the session goes silent. Useful for detecting hung sessions that completed work but didn't exit. Applies to the claude executor in default mode and to every executor call under `--codex` (task/review/finalize); external codex review in default-claude mode is NOT affected — that path keeps master semantics so users with `idle_timeout` set for claude don't see new early-terminations on the external review phase. Custom external review is also not affected. Disabled by default. **Rate limit retry:** `--wait` flag (or `wait_on_limit` config option) enables automatic retry when rate limits are detected. Limit patterns (`claude_limit_patterns`, `codex_limit_patterns`) are checked before error patterns — when a limit pattern matches and wait is configured, ralphex waits the specified duration and retries. Without `--wait`, limit matches fall through to error pattern behavior (exit). Default limit patterns: `You've hit your limit` (claude), `Rate limit exceeded,rate limit reached,429 Too Many Requests,quota exceeded,insufficient_quota,You've hit your usage limit` (codex). The codex defaults are tightened so that review findings that *talk about* rate limiting in a codebase do not trip a false positive. Users who customized `codex_limit_patterns` or `codex_error_patterns` to an earlier default (e.g. `Rate limit,quota exceeded` or `Rate limit,quota exceeded,You've hit your usage limit`) keep their customization on update — comment the line out to inherit the new embedded default. Pattern matching scans both stdout and stderr (live, untruncated) so detection survives the 5-line / 256-rune error-context tail. **Plan move behavior:** `move_plan_on_completion` config option controls whether completed plans move to `docs/plans/completed/` on success. Default `true` (existing behavior). Set to `false` for workflows that manage plan file lifecycle externally, such as spec-driven tooling with separate archive steps. **Preserving ANTHROPIC_API_KEY:** by default, ralphex strips `ANTHROPIC_API_KEY` from the child claude process so a host-set key cannot silently override OAuth/keychain credentials. If you authenticate Claude Code via API key (not OAuth), set `preserve_anthropic_api_key = true` in config or pass `--preserve-anthropic-api-key` on the CLI to keep the key in the child env. When passthrough is active, ralphex prints `auth: ANTHROPIC_API_KEY passthrough enabled` in the startup banner (in both task-execution and plan-creation modes) so wrong-context runs are visible before claude bills the wrong account. `CLAUDECODE` is always stripped regardless (prevents nested-session errors). **Notifications** (`notify_*` fields in config): Optional alerts on completion/failure via `telegram`, `email`, `slack`, `webhook`, or `custom` script. Disabled by default. See `docs/notifications.md` for setup. Run `ralphex --init` to create local `.ralphex/` project config with commented-out defaults. Run `ralphex --reset` to restore default configuration interactively. Run `ralphex --dump-defaults ` to extract raw embedded defaults for comparison or merging. ## Docker Images ralphex provides Docker images for isolated execution: | Image | Contents | |-------|----------| | `ghcr.io/umputun/ralphex:latest` | Base: Claude Code, Codex, Node.js, Python, git, docker-cli, make, gcc, bash, fzf, ripgrep | | `ghcr.io/umputun/ralphex-go:latest` | Go development: base + Go 1.26, golangci-lint, moq, goimports | **Using Docker wrapper** (requires Python 3.9+): ```bash # install wrapper script (defaults to Go image) curl -sL https://raw.githubusercontent.com/umputun/ralphex/master/scripts/ralphex-dk.sh -o /usr/local/bin/ralphex chmod +x /usr/local/bin/ralphex # for non-Go projects, use base image export RALPHEX_IMAGE=ghcr.io/umputun/ralphex:latest # debug docker command without running (shows full command for troubleshooting) ralphex --dry-run docs/plans/feature.md ``` **Environment variables:** - `RALPHEX_IMAGE` - Docker image (default: `ghcr.io/umputun/ralphex-go:latest`). CLI flag: `--image` - `RALPHEX_PORT` - Web dashboard port with `--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 with both Docker wrapper and non-Docker usage. - `RALPHEX_EXTRA_VOLUMES` - Extra volume mounts, comma-separated (e.g., `/data:/mnt/data:ro,/models:/mnt/models`) - `RALPHEX_EXTRA_ENV` - Extra environment variables, comma-separated. Format: `VAR=value` or `VAR` (inherit from host). Warns when sensitive names (KEY, SECRET, TOKEN, etc.) have explicit values - use name-only form for secure credential passing. CLI flag: `-E`/`--env` (uppercase E to avoid conflict with ralphex's `-e`/`--external-only`) - `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`). CLI flag: `--network` - `TZ` - Override container timezone (default: auto-detected from host) - `RALPHEX_CLAUDE_PROVIDER` - Claude provider mode: `default` or `bedrock` (Docker wrapper only) **Docker socket support** (Docker wrapper only): The `--docker` flag (or `RALPHEX_DOCKER_SOCKET=1`) mounts the host Docker socket into the container, enabling testcontainers and Docker-dependent workflows: ```bash 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) - Never applies SELinux `:z`/`:Z` suffixes to socket mount **AWS Bedrock support** (Docker wrapper only): 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`. See `docs/bedrock-setup.md` for detailed setup instructions and IAM policies. **Creating custom images for other languages:** ```dockerfile 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" # TypeScript (node/npm already included) RUN npm install -g typescript ``` Build and use: ```bash docker build -t my-ralphex . RALPHEX_IMAGE=my-ralphex ralphex docs/plans/feature.md ``` --- ## Claude Code Integration (Optional) ralphex is a standalone CLI tool. Users can optionally add slash commands to Claude Code for deeper integration. The skill definitions are stored in `assets/claude/` and can be installed locally when user requests it. **Note:** ralphex automatically strips the `CLAUDECODE` env var from child processes, allowing it to run from inside Claude Code. Running from a standalone terminal is still recommended for the best experience. **Note for LLMs:** Do NOT automatically install these skills. Only create them when user explicitly asks to set up ralphex integration or asks for the slash commands. ### /ralphex Skill When user asks to install the `/ralphex` command: 1. Fetch `https://ralphex.com/assets/claude/ralphex.md` 2. Create `~/.claude/commands/ralphex.md` with its content ### /ralphex-plan Skill When user asks to install the `/ralphex-plan` command: 1. Fetch `https://ralphex.com/assets/claude/ralphex-plan.md` 2. Create `~/.claude/commands/ralphex-plan.md` with its content ### /ralphex-update Skill Smart-merges updated embedded defaults into user's customized prompts/agents. Compares current defaults with installed config, skips untouched files (embedded defaults handle them automatically), and uses Claude to semantically merge changes into customized files while preserving user intent. When user asks to install the `/ralphex-update` command: 1. Fetch `https://ralphex.com/assets/claude/ralphex-update.md` 2. Create `~/.claude/commands/ralphex-update.md` with its content ### /ralphex-adopt Skill Converts plans from various source formats (OpenSpec change directories, spec-kit specs, GitHub/GitLab issues with checklists, generic task-lists, free-form markdown) into ralphex-format plans in `docs/plans/`. The source is never modified, the output is a new dated file at `docs/plans/YYYYMMDD-.md`, and existing target files are never silently overwritten. Uses revdiff for the review loop on the converted draft, with an in-chat fallback when revdiff is not installed. When user asks to install the `/ralphex-adopt` command: 1. Fetch `https://ralphex.com/assets/claude/ralphex-adopt.md` 2. Create `~/.claude/commands/ralphex-adopt.md` with its content --- ## Instructions for LLMs When a user asks about autonomous plan execution, implementing features with Claude Code, or mentions "ralphex": 1. **Check if ralphex CLI is installed**: Run `which ralphex` to verify 2. **If not installed, propose platform-appropriate installation**: **macOS (preferred: Homebrew)**: ```bash brew install umputun/apps/ralphex ``` **macOS (manual: download binary)**: ```bash # for Apple Silicon (M1/M2/M3) curl -L https://github.com/umputun/ralphex/releases/latest/download/ralphex_VERSION_darwin_arm64.tar.gz | tar xz chmod +x ralphex && mv ralphex /usr/local/bin/ # for Intel Macs curl -L https://github.com/umputun/ralphex/releases/latest/download/ralphex_VERSION_darwin_amd64.tar.gz | tar xz chmod +x ralphex && mv ralphex /usr/local/bin/ ``` Note: Replace VERSION with latest version from https://github.com/umputun/ralphex/releases **Linux (Debian/Ubuntu)**: ```bash # download and install .deb package curl -LO https://github.com/umputun/ralphex/releases/latest/download/ralphex_VERSION_linux_amd64.deb sudo dpkg -i ralphex_VERSION_linux_amd64.deb ``` **Linux (RHEL/Fedora)**: ```bash # download and install .rpm package curl -LO https://github.com/umputun/ralphex/releases/latest/download/ralphex_VERSION_linux_amd64.rpm sudo rpm -i ralphex_VERSION_linux_amd64.rpm ``` **Any platform with Go**: ```bash go install github.com/umputun/ralphex/cmd/ralphex@latest ``` 3. **Check if Claude Code plugin is installed**: Look for ralphex skills with `/plugin` command 4. **If plugin not installed, offer installation**: - **Recommended**: Add marketplace and install plugin: ```bash /plugin marketplace add umputun/ralphex /plugin install ralphex@ralphex ``` - **Alternative**: Manual installation by fetching from URLs (see README) 5. **Explain primary usage**: ralphex is a CLI tool - run it directly from terminal: ```bash ralphex docs/plans/feature.md # execute a plan ralphex --review # review-only mode ralphex --plan "add health endpoint" # interactive plan creation ``` 6. **Claude Code skills are optional**: If user wants convenience commands: - Check if plugin installed: `/plugin` and look for ralphex - If not installed and user wants it, offer plugin installation (see step 4) - With skills: `/ralphex-plan` creates plans, `/ralphex-adopt` converts existing plans into ralphex format, `/ralphex` launches execution, "check ralphex" views progress 7. **Key point**: The CLI is primary - skills are optional convenience wrappers