Autonomous plan execution with Claude Code — a CLI tool that orchestrates task-by-task implementation and multi-stage code reviews
ralphex is a standalone Go CLI tool that autonomously orchestrates Claude Code to execute Markdown-based development plans. It decomposes plans into isolated tasks, each running in a fresh Claude Code session to prevent context degradation. The execution pipeline covers automatic branch creation, task implementation, auto-commit, a 5-agent parallel review stage (quality / implementation / testing / simplification / documentation), optional external review (defaulting to OpenAI Codex), a 2-agent focused review stage, and plan archival.
It supports five execution modes: full execution, tasks-only, review-only, external-only, and interactive plan creation. A Web dashboard (SSE + WebSocket) provides real-time execution monitoring, with multi-channel notifications (Telegram / Email / Slack / Webhook). Git worktree isolation via --worktree enables parallel multi-plan execution, and --docker provides containerized secure isolation. Supports AWS Bedrock as an alternative Claude provider and custom review agents via the {{agent:name}} template system. Configuration supports global (~/.config/ralphex/config) and project-level (.ralphex/config) scopes in INI and YAML formats. Runs on macOS and Linux, with limited Windows support.
Installation
- From source:
go install github.com/umputun/ralphex/cmd/ralphex@latest - Homebrew:
brew install umputun/apps/ralphex - Pre-built binaries from GitHub Releases
- Docker wrapper script
Prerequisites: Claude Code (Anthropic CLI, required); optional OpenAI Codex (external review).
Quick Start
- Create a plan file under
docs/plans/(Markdown with Validation Commands and Task list) - Run
ralphex docs/plans/my-feature.md - ralphex automatically handles: branch creation → task execution → auto-commit → multi-stage review → plan archival to
completed/
Key CLI Flags
| Flag | Description |
|---|---|
ralphex <plan> | Full execution mode (default) |
--tasks-only <plan> | Execute tasks only, skip review |
--review [plan] | Review-only mode |
--external-only [plan> | Run external review tool only |
--plan "description" | Interactive plan creation |
--serve | Start Web dashboard (default port 8080) |
--worktree | Execute in isolated git worktree |
--docker | Run in Docker wrapper |
--claude-provider | Claude provider (default / bedrock) |
--effort model[:effort] | Specify model and effort level |
--review-patience N | External review stalemate detection threshold |
Key Environment Variables: RALPHEX_IMAGE (Docker image), RALPHEX_PORT, RALPHEX_CONFIG_DIR, CLAUDE_CONFIG_DIR, RALPHEX_EXTRA_VOLUMES, RALPHEX_EXTRA_ENV.
Architecture: Go single-binary CLI acting as an orchestration layer that invokes Claude Code CLI via subprocess (--dangerously-skip-permissions mode). Core logic in pkg/, CLI entry point in cmd/ralphex/. Includes .claude-plugin/ directory as a Claude Code plugin (supports slash commands like /ralphex-plan). E2E tests use Playwright Go. Docker image published to ghcr.io/umputun/ralphex-go.
Unconfirmed: site/ directory may correspond to a standalone docs site but no URL provided; current version number requires checking Releases page; go.mod specifies Go 1.26, accuracy pending confirmation.