# 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-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

# 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"

# 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
```

## Requirements

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

## 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`, `custom_review.txt`, `custom_eval.txt`, `make_plan.txt`, `finalize.txt`

**Agent files** (`~/.config/ralphex/agents/`): Custom review agents referenced via `{{agent:name}}` in prompts

**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 custom_review.txt)

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

**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.sh`. Set `claude_command = /path/to/wrapper` in config. Wrappers should ignore unknown flags gracefully. See `docs/custom-providers.md` for details on writing wrappers for other tools (Gemini CLI, local LLMs, etc.).

**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 --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, Node.js, Python, git, make, gcc, bash, fzf, ripgrep |
| `ghcr.io/umputun/ralphex-go:latest` | Go development: base + Go 1.25, 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
```

**Environment variables:**
- `RALPHEX_IMAGE` - Docker image (default: `ghcr.io/umputun/ralphex-go:latest`)
- `RALPHEX_PORT` - Web dashboard port with `--serve` (default: `8080`)
- `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`)

**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 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

---

## 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@umputun-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` launches execution, "check ralphex" views progress

7. **Key point**: The CLI is primary - skills are optional convenience wrappers