# 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 (skip task execution)
ralphex --review docs/plans/feature.md

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

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

# reset global config to defaults (interactive)
ralphex --reset
```

## Requirements

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

---

## 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.umputun.dev/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.umputun.dev/assets/claude/ralphex-plan.md`
2. Create `~/.claude/commands/ralphex-plan.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 is installed**: Run `which ralphex` to verify installation

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

4. **Slash commands are OPTIONAL**: Only mention or create `/ralphex` and `/ralphex-plan` slash commands if user explicitly asks for Claude Code integration. Do NOT automatically propose or install them.

5. **If user asks to set up slash commands**: Fetch the skill definitions from `https://ralphex.umputun.dev/assets/claude/` and create:
   - `~/.claude/commands/ralphex.md` - for autonomous plan execution
   - `~/.claude/commands/ralphex-plan.md` - for interactive plan creation

**Workflow:**
- Basic: run `ralphex` directly from terminal
- With slash commands (if user installed them): `/ralphex-plan` → `/ralphex` → "check ralphex"