llms.txt

# 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

# codex plan creation with a specific plan model/effort
ralphex --codex --plan-model=gpt-5.6-sol:xhigh --plan="add user authentication"

# codex executor mode with task/review model/effort (resolved against codex_model/codex_reasoning_effort)
ralphex --codex --task-model=gpt-5.6-sol:high --review-model=gpt-5.6-sol:low 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

# override Claude-compatible provider and external review tool for one run
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

# 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/`)
- `agy` - Antigravity CLI, alternative provider for Claude phases (optional, via `scripts/agy-as-claude/`)
- `pi` - alternative provider for Claude phases (optional, via `scripts/pi-as-claude/`)

## Platform Support

Linux and macOS are the supported platforms. Windows works on a best-effort basis: it builds and runs, but no Windows binaries are released, so it has to be installed from source, and the maintainer has no Windows machine and does not test there. The Ctrl+\ break, file-lock-based active session detection, and cleanup of descendant processes on cancellation are unavailable on Windows. Windows-only issues and pull requests can rarely be acted on, since the maintainer has no Windows machine to reproduce a report or verify a fix. A patch may still be merged when the cause is clear-cut, the change is small and self-contained, and it cannot affect Linux or macOS. Reports and patches that do not meet that bar are closed.

## 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:<name>}}` 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:** `plan_model`, `task_model`, and `review_model` config options (or `--plan-model`, `--task-model`, `--review-model` CLI flags) set phase model/effort using `model[:effort]` syntax. Examples: `opus` (model only), `opus:high` (both), `:medium` (effort only). Effort levels: `low`, `medium`, `high`, `xhigh`, `max`. `plan_model` sets plan creation and falls back to `task_model` if empty. `task_model` sets task execution. `review_model` sets review phases and falls back to `task_model` if empty. Parts are appended to the configured `claude_command` as `--model <m>` and/or `--effort <e>`. 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).

Under the codex executor (`--codex` or `executor = codex`), `plan_model`/`task_model`/`review_model` (CLI flag or config) select the model/effort per phase, resolved against `codex_model`/`codex_reasoning_effort` as the codex defaults. `--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 review model/effort differs from task, so tasks and reviews can run on different codex models. An unset spec inherits the codex defaults, and each populated half of a `model[:effort]` spec overrides its default (`--task-model=:low` changes effort only). The `max` effort level does not exist in codex — passing it under `--codex` prints a warning and is ignored.

```ini
# in ~/.config/ralphex/config
plan_model = fable:high
task_model = sonnet:medium
review_model = sonnet:low
```

**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. Included wrappers: `scripts/codex-as-claude/codex-as-claude.sh`, `scripts/copilot-as-claude/copilot-as-claude.sh`, `scripts/gemini-as-claude/gemini-as-claude.sh`, `scripts/agy-as-claude/agy-as-claude.sh`, `scripts/opencode/opencode-as-claude.sh`, `scripts/pi-as-claude/pi-as-claude.sh`. Set `claude_command = /path/to/wrapper` in config, or use `--claude-command=/path/to/wrapper` for one run. Wrappers should ignore unknown flags gracefully. Use `--claude-args=` only when a wrapper cannot tolerate configured/default Claude flags and they must be cleared for a single run. 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=<X>` (when `<X>` 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.6-sol` / `high`) ship as active values in the embedded config so external codex review in default-claude mode does not follow the model your `~/.codex/config.toml` selects; the pinned pair moves with ralphex releases as codex models change. Set either to an empty value (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.
- `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 <noreply@ralphex.com>`. 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.

**Transient retry:** `claude_retry_patterns` config option detects transient claude/fya markers and retries them through the existing timeout-style phase path. Default: `FYA_TRANSIENT_TIMEOUT,API Error: 529,API Error: 502,API Error: 503,API Error: 504`. The transient HTTP errors (529 Overloaded and the 502/503/504 gateway errors) are auto-retried here rather than gated behind `--wait`, since they are short-lived server hiccups, not account-quota limits. Retry patterns are checked before limit and error patterns and do not use `wait_on_limit`. The task and review retry loops wait a short fixed backoff (5s) before re-running a timed-out or transiently-failed iteration.

**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,You've hit your session limit,You've hit your weekly limit,API Error: 429,Your usage allocation has been disabled by your admin,You've hit your org's monthly usage limit,You've hit your individual spend limit` (claude), `Rate limit exceeded,rate limit reached,429 Too Many Requests,quota exceeded,insufficient_quota,You've hit your usage limit,Selected model is at capacity` (codex). The transient HTTP errors `API Error: 529/502/503/504` are no longer in the claude limit set — they moved to `claude_retry_patterns` so they auto-retry without `--wait`. 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. For codex and custom executors, pattern matching scans both stdout and stderr (live, untruncated) so detection survives the 5-line / 256-rune error-context tail. For claude, patterns are matched by source: a bounded window of structured CLI diagnostics (result/error records, assistant API-error messages, relevant system events) plus non-JSON CLI lines is always authority, while ordinary assistant text and successful result summaries are excluded — so a clean run that quotes a configured phrase is not treated as a fresh CLI failure. A `result` record is diagnostic only when it authenticates itself as an error (`is_error:true`, `terminal_reason:"api_error"`, or a non-zero `api_error_status`); `subtype` is not consulted, since a genuine rate-limit result has been observed carrying `subtype:"success"`. Bounded recent surfaced output is added as pattern input only when the process exits non-zero or the stream fails, which preserves limit classification for the bundled wrapper scripts.

**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. Under `--worktree` the archive is committed on the feature branch beside the ticked plan; the copy in the main checkout is left untouched, and for a plan that was never committed it remains there even after the branch merges.

**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. Claude Code's per-session markers (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_CODE_MESSAGING_SOCKET` and the rest of the set) are always stripped regardless of this setting, which prevents nested-session errors. Marker names are matched exactly, so configuration variables such as `CLAUDE_CODE_USE_BEDROCK` are preserved.

**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 <dir>` 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, fya, 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`
- `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)
- `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 fix this here, since npm installs it root-owned and the container runs as the `app` user.

When `RALPHEX_CLI_UPDATE` is set (case-insensitive `1`/`true`/`yes`), `/srv/init.sh` refreshes both CLIs to their current npm releases at container start, as root, before dropping privileges. It usually costs 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 reports it. The base `ralphex` image leaves it off so downstream images get no surprise npm install, network call, or version drift at start; the `ralphex-go` image (the wrapper's default) bakes it on so the common path stays current. Enable it per run with `RALPHEX_CLI_UPDATE=1 ralphex ...`, or bake `ENV RALPHEX_CLI_UPDATE=1` into a custom image.

**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 Claude Code's per-session env vars (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_CODE_MESSAGING_SOCKET` and the rest of the set) from the Claude and Codex child processes, allowing it to run from inside Claude Code. Marker names are matched exactly, so configuration variables such as `CLAUDE_CODE_USE_BEDROCK` are preserved. 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-<slug>.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