[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74650":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":18,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":34,"lastSyncTime":35,"discoverSource":36},74650,"ralphex","umputun\u002Fralphex","umputun","Extended Ralph loop for autonomous AI-driven plan execution","https:\u002F\u002Fralphex.com",null,"Go",1253,100,29,4,0,16,48,119,19.01,"MIT License",false,"master",[25,26,27,28,29,30],"automation","claude-code","codex","ralph-loop","ralph-wiggum","review","2026-06-12 02:03:26","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fralphex-wordmark-split.png\" alt=\"ralphex\" width=\"400\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"build\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fcoveralls.io\u002Fgithub\u002Fumputun\u002Fralphex?branch=master\">\u003Cimg src=\"https:\u002F\u002Fcoveralls.io\u002Frepos\u002Fgithub\u002Fumputun\u002Fralphex\u002Fbadge.svg?branch=master\" alt=\"Coverage Status\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fumputun\u002Fralphex\">\u003Cimg src=\"https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fumputun\u002Fralphex?v=2\" alt=\"Go Report Card\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Ch2 align=\"center\">Autonomous plan execution with Claude Code\u003C\u002Fh2>\n\n*ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates Claude Code to execute implementation plans autonomously - no IDE plugins or cloud services required, just Claude Code and a single binary.*\n\nClaude Code is powerful but interactive - it requires you to watch, approve, and guide each step. For complex features spanning multiple tasks, this means hours of babysitting. Worse, as context fills up during long sessions, the model's quality degrades - it starts making mistakes, forgetting earlier decisions, and producing worse code.\n\nralphex solves both problems. Each task executes in a fresh Claude Code session with minimal context, keeping the model sharp throughout the entire plan. Write a plan with tasks and validation commands, start ralphex, and walk away. Come back to find your feature implemented, reviewed, and committed - or check the progress log to see what it's doing.\n\n\u003Cdetails markdown>\n\u003Csummary>Task Execution Screenshot\u003C\u002Fsummary>\n\n![ralphex tasks](assets\u002Fralphex-tasks.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary>Review Mode Screenshot\u003C\u002Fsummary>\n\n![ralphex review](assets\u002Fralphex-review.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary>Web Dashboard Screenshot\u003C\u002Fsummary>\n\n![ralphex web dashboard](assets\u002Fralphex-web.png)\n\n\u003C\u002Fdetails>\n\n## Features\n\n- **Zero setup** - works out of the box with sensible defaults, no configuration required\n- **Autonomous task execution** - executes plan tasks one at a time with automatic retry\n- **Interactive plan creation** - create plans through dialogue with Claude via `--plan` flag\n- **Multi-phase code review** - 5 agents → codex → 2 agents review pipeline\n- **Custom review agents** - configurable agents with `{{agent:name}}` template system and user defined prompts\n- **Automatic branch creation** - creates git branch from plan filename\n- **Plan completion tracking** - moves completed plans to `completed\u002F` folder\n- **Automatic commits** - commits after each task and review fix\n- **Real-time monitoring** - streaming output with timestamps, colors, and detailed logs\n- **Web dashboard** - browser-based real-time view with `--serve` flag\n- **Docker support** - run in isolated container for safer autonomous execution\n- **Notifications** - optional alerts on completion\u002Ffailure via Telegram, Email, Slack, Webhook, or custom script\n- **Worktree isolation** - run multiple plans in parallel via `--worktree` flag\n- **Multiple modes** - full execution, tasks-only, review-only, external-only, or plan creation\n\n## Quick Start\n\nMake sure ralphex is [installed](#installation) and your project is a git repository. You need a  [plan file](#plan-creation) in `docs\u002Fplans\u002F`, for example:\n\n```markdown\n# Plan: My Feature\n\n## Validation Commands\n- `go test .\u002F...`\n\n### Task 1: Implement feature\n- [ ] Add the new functionality\n- [ ] Add tests\n```\n\nThen run:\n\n```bash\nralphex docs\u002Fplans\u002Fmy-feature.md\n```\n\nralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to `completed\u002F` when done.\n\n## How It Works\n\nralphex executes plans in four phases with automated code reviews, plus an optional finalize step.\n\n\u003Cdetails markdown>\n\u003Csummary>Execution Flow Diagram\u003C\u002Fsummary>\n\n![ralphex flow](assets\u002Fralphex-flow.png)\n\n\u003C\u002Fdetails>\n\n### Phase 1: Task Execution\n\n1. Reads plan file and finds first incomplete task (`### Task N:` with `- [ ]` checkboxes)\n2. Sends task to Claude Code for execution\n3. Runs validation commands (tests, linters) after each task\n4. Marks checkboxes as done `[x]`, commits changes\n5. Repeats until all tasks complete or max iterations reached\n\n**Steering mid-run:** Press Ctrl+\\ (SIGQUIT) during a task iteration to pause execution. ralphex cancels the current Claude session and prompts \"press Enter to continue, Ctrl+C to abort\". While paused, you can edit the plan file — on Enter, the same task re-runs with a fresh session that re-reads the plan. Press Ctrl+C to abort cleanly. Not available on Windows.\n\n### Phase 2: First Code Review\n\nLaunches 5 review agents **in parallel** via Claude Code Task tool:\n\n| Agent | Purpose |\n|-------|---------|\n| `quality` | bugs, security issues, race conditions |\n| `implementation` | verifies code achieves stated goals |\n| `testing` | test coverage and quality |\n| `simplification` | detects over-engineering |\n| `documentation` | checks if docs need updates |\n\nClaude verifies findings, fixes confirmed issues, and commits.\n\n*[Default agents](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Ftree\u002Fmaster\u002Fpkg\u002Fconfig\u002Fdefaults\u002Fagents) provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See [Customization](#customization) for details.*\n\n### Phase 3: External Review (optional)\n\n1. Runs external review tool (codex by default, or custom script)\n2. Claude evaluates findings, fixes valid issues\n3. Iterates until no open issues\n\nThe loop terminates when: all issues resolved, max iterations reached, stalemate detected (via `--review-patience`), or manual break via Ctrl+\\ (SIGQUIT).\n\n**Stalemate detection:** When the external tool and Claude can't agree on findings, the loop can waste tokens iterating to the max. Set `--review-patience=N` (or `review_patience` in config) to terminate after N consecutive rounds with no commits or working tree changes.\n\n**Manual break:** Press Ctrl+\\ (SIGQUIT) during the external review loop to terminate it immediately. The current executor run is cancelled via context cancellation. During the task phase, Ctrl+\\ pauses instead — see [Phase 1: Task Execution](#phase-1-task-execution). Not available on Windows.\n\nSupported tools:\n- **codex** (default): OpenAI Codex for independent code review\n- **custom**: Your own script wrapping any AI (OpenRouter, local LLM, etc.)\n- **none**: Skip external review entirely\n\nSee [Custom External Review](#custom-external-review) for details on using custom scripts.\n\n### Phase 4: Second Code Review\n\n1. Launches 2 agents (`quality` + `implementation`) for final review\n2. Focuses on critical\u002Fmajor issues only\n3. Iterates until no issues found\n4. Moves plan to `completed\u002F` folder on success\n\n*Second review agents are configurable via `prompts\u002Freview_second.txt`.*\n\n### Finalize Step (optional)\n\nAfter all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.\n\n**What it does:** runs a single Claude Code session with a customizable prompt. The default `finalize.txt` prompt rebases commits onto the default branch and optionally squashes related commits into logical groups.\n\n**How to enable:**\n\nSet `finalize_enabled = true` in `~\u002F.config\u002Fralphex\u002Fconfig` or `.ralphex\u002Fconfig`.\n\n**Behavior:**\n- Runs once (no iteration loop)\n- Best-effort — failures are logged but don't block success\n- Triggers on modes with review pipeline: full, review-only, external-only\n- Uses task color (green) for output\n\n**Customization:**\n\nEdit `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt` (or `.ralphex\u002Fprompts\u002Ffinalize.txt`) to change what happens after reviews. Examples: push to remote, send notifications, run deployment scripts, or any post-completion automation. Template variables like `{{DEFAULT_BRANCH}}` are available.\n\n### Plan Move Behavior (optional)\n\nAfter successful execution, ralphex moves the plan file into `docs\u002Fplans\u002Fcompleted\u002F`. Enabled by default.\n\n**How to disable:**\n\nSet `move_plan_on_completion = false` in `~\u002F.config\u002Fralphex\u002Fconfig` or `.ralphex\u002Fconfig`. Default is `true`.\n\n**When to disable:** workflows that manage plan file lifecycle externally (e.g. spec-driven tooling where the plan lives inside a bundle that a separate archive step consumes) should opt out so ralphex doesn't fight the external tool's file layout.\n\n### Review-Only Mode\n\nReview-only mode (`--review`) runs the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already present on the current branch. This is useful when changes were made outside ralphex — via Claude Code's built-in plan mode, manual edits, other AI agents, or any other workflow.\n\n**Workflow:**\n\n1. Make changes on a feature branch (using any tool or workflow)\n2. Commit the changes\n3. Run `ralphex --review`\n\nralphex compares the branch against the default branch (`git diff master...HEAD`), launches multi-agent reviews, and iterates fixes until all agents report clean. No plan file is required — if provided, it gives reviewers additional context about the intended changes.\n\n```bash\n# switch to feature branch with existing changes\ngit checkout feature-auth\n\n# run review pipeline on those changes\nralphex --review\n\n# optionally pass a plan file for context\nralphex --review docs\u002Fplans\u002Fadd-auth.md\n```\n\n### External-Only Mode\n\nExternal-only mode (`--external-only`, alias `-e`) skips the task and first review phases and runs the external review pipeline (Phase 3 → Phase 4) on changes already present on the current branch. The flag name follows the same cutoff convention as `--review`: it marks where execution starts, not which single phase runs. After the external review loop converges (or hits its iteration limit), the post-external critical\u002Fmajor review (Phase 4) runs to catch regressions from fixes applied during the loop.\n\nIf the external review loop finds no issues on its first pass, Phase 4 is skipped automatically because there is nothing to regress.\n\n```bash\n# run external review pipeline on current branch changes\nralphex --external-only\n\n# optionally pass a plan file for context\nralphex --external-only docs\u002Fplans\u002Ffeature.md\n```\n\n### Worktree Isolation\n\nThe `--worktree` flag runs plan execution in an isolated git worktree at `.ralphex\u002Fworktrees\u002F\u003Cbranch>`, enabling parallel execution of multiple plans on the same repo without branch conflicts.\n\n**Supported modes:** `--worktree` only applies to full mode and `--tasks-only`. It is silently ignored for `--review`, `--external-only`, and `--plan` — these modes operate from the current directory.\n\n**Re-running reviews on a worktree branch:** if the task phase completed in a worktree but the review phase needs to be re-run, `cd` into the worktree directory and run the review from there:\n\n```bash\n# find the worktree\nls .ralphex\u002Fworktrees\u002F\n\n# run review from inside it\ncd .ralphex\u002Fworktrees\u002Fmy-feature-branch\nralphex --review\n# or\nralphex --external-only\n```\n\nWorktrees are automatically removed on successful completion. If a run is interrupted, the worktree directory may remain and can be reused or removed manually.\n\n### Plan Creation\n\nPlans can be created in several ways:\n- **[Claude Code](#claude-code-integration-optional)** - use slash commands like `\u002Fralphex-plan` or your own planning workflows\n- **Manually** - write markdown files directly in `docs\u002Fplans\u002F`\n- **`--plan` flag** - integrated option that handles the entire flow\n- **Auto-detection** - running `ralphex` without arguments on master\u002Fmain prompts for plan creation if no plans exist\n\nThe `--plan` flag provides a simpler integrated experience:\n\n```bash\nralphex --plan \"add health check endpoint\"\n```\n\nClaude explores your codebase, asks clarifying questions via a terminal picker (fzf or numbered fallback), and generates a complete plan file in `docs\u002Fplans\u002F`. When reviewing the draft, you can accept, revise with text feedback, open it in `$EDITOR` for interactive annotation, or reject it.\n\n**Example session:**\n```\n$ ralphex --plan \"add caching for API responses\"\n[10:30:05] analyzing codebase structure...\n[10:30:12] found existing store layer in pkg\u002Fstore\u002F\n\nQUESTION: Which cache backend?\n  > Redis\n    In-memory\n    File-based\n    Other (type your own answer)\n\n[10:30:45] ANSWER: Redis\n[10:31:00] continuing plan creation...\n[10:32:05] plan written to docs\u002Fplans\u002Fadd-api-caching.md\n\nContinue with plan implementation?\n  > Yes, execute plan\n    No, exit\n```\n\nAfter plan creation, you can choose to continue with immediate execution or exit to run ralphex later. Progress is logged to `.ralphex\u002Fprogress\u002Fprogress-plan-\u003Cname>.txt`.\n\n## Installation\n\n### From source\n\n```bash\ngo install github.com\u002Fumputun\u002Fralphex\u002Fcmd\u002Fralphex@latest\n```\n\n### Using Homebrew\n\n```bash\nbrew install umputun\u002Fapps\u002Fralphex\n```\n\n### From releases\n\nDownload the appropriate binary from [releases](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Freleases).\n\n### Using Docker\n\nDownload the wrapper script and install to PATH:\n\n```bash\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Fumputun\u002Fralphex\u002Fmaster\u002Fscripts\u002Fralphex-dk.sh -o \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\n```\n\nThe script defaults to the Go image (`ralphex-go`). For other languages, build a custom image from the base with your toolchain installed (see [Available images](#available-images) for examples), then point the wrapper at it:\n```bash\nexport RALPHEX_IMAGE=my-ralphex\n```\n\nThen use `ralphex` as usual - it runs in a container with Claude Code and Codex pre-installed. The script shows which image it's using at startup.\n\n**Why use Docker?** ralphex runs Claude Code with `--dangerously-skip-permissions`, giving it full access to execute commands and modify files. Running in a container provides isolation - Claude can only access the mounted project directory, not your entire system. This makes autonomous execution significantly safer.\n\n\u003Cdetails markdown>\n\u003Csummary>Isolation details\u003C\u002Fsummary>\n\n**Container CAN access (read-write):**\n- Project directory mounted at `\u002Fworkspace` - full access to create, modify, delete files\n- Git operations within the project (branch, commit, etc.)\n\n**Container CAN access (read-only):**\n- `~\u002F.claude\u002F` - credentials and settings (copied at startup, not modified)\n- `~\u002F.codex\u002F` - codex credentials if present\n- `~\u002F.config\u002Fralphex\u002F` - user-level ralphex configuration\n- `~\u002F.gitconfig` - git identity for commits\n- Global gitignore (`core.excludesFile`) - auto-detected and mounted\n- `.ralphex\u002F` - project-level configuration if present\n\n**Container CANNOT access:**\n- Host filesystem outside mounted directories\n- Other projects or repositories\n- SSH keys, AWS credentials, or other secrets in `~\u002F.ssh`, `~\u002F.aws`, etc.\n- System files, binaries, or configurations\n- Other running processes or containers\n\n**Network:** Full network access (required for Claude API calls)\n\n**Privileges:** Runs as non-root user with no elevated capabilities\n\n\u003C\u002Fdetails>\n\n**Volume mounts:**\n- **Read-only**: `~\u002F.claude` and `~\u002F.codex` mounted to `\u002Fmnt\u002F`, copied at startup to preserve isolation\n- **Read-write**: project directory (`\u002Fworkspace`) - where ralphex creates branches, edits code, and commits\n- **Extra mounts**: user-defined volumes via `-v`\u002F`--volume` flags or `RALPHEX_EXTRA_VOLUMES` env var\n\n**Requirements:**\n- Python 3.9+ (for the wrapper script)\n- Docker installed and running\n- Claude Code credentials in `~\u002F.claude\u002F` (or in `$CLAUDE_CONFIG_DIR` when set)\n- Codex credentials in `~\u002F.codex\u002F` (optional, for codex review phase)\n- Git config in `~\u002F.gitconfig` (for commits)\n\n**Environment variables:**\n- `RALPHEX_IMAGE` - Docker image to use (default: `ghcr.io\u002Fumputun\u002Fralphex-go:latest`). CLI flag: `--image`\n- `RALPHEX_PORT` - Port for web dashboard when using `--serve` (default: `8080`). CLI flag: `--port`\n- `RALPHEX_CONFIG_DIR` - Custom config directory (default: `~\u002F.config\u002Fralphex`). Overrides global config location for prompts, agents, and settings\n- `CLAUDE_CONFIG_DIR` - Claude config directory (default: `~\u002F.claude`). Use for alternate Claude installations (e.g., `~\u002F.claude2`). Works both with Docker wrapper (volume mounts and keychain derivation) and non-Docker usage (passed through to Claude Code directly). Keychain service name is derived automatically from the path.\n- `RALPHEX_EXTRA_VOLUMES` - Extra volume mounts, comma-separated (e.g., `\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels`). Entries without `:` are silently skipped\n- `RALPHEX_EXTRA_ENV` - Extra environment variables, comma-separated (e.g., `DEBUG=1,API_KEY`). Format: `VAR=value` or `VAR` (inherit from host). Security warning emitted for sensitive names (KEY, SECRET, TOKEN, etc.) with explicit values - use name-only form for secure credential passing\n- `RALPHEX_DOCKER_SOCKET` - Enable Docker socket mount: `1`, `true`, or `yes` (Docker wrapper only). CLI flag: `--docker`\n- `RALPHEX_DOCKER_NETWORK` - Docker network mode (e.g., `host`, `my-network`). Useful for reaching docker-compose services. CLI flag: `--network`\n- `TZ` - Override container timezone (default: auto-detected from host via `\u002Fetc\u002Flocaltime`). Example: `TZ=Europe\u002FBerlin ralphex docs\u002Fplans\u002Ffeature.md`\n- `RALPHEX_CLAUDE_PROVIDER` - Claude provider mode: `default` or `bedrock` (Docker wrapper only)\n\n**Docker socket support:**\n\nThe `--docker` flag (or `RALPHEX_DOCKER_SOCKET=1`) mounts the host Docker socket into the container, enabling testcontainers and Docker-dependent workflows:\n\n```bash\nralphex --docker docs\u002Fplans\u002Ffeature.md\nralphex --docker --dry-run   # verify socket mount in command\n```\n\n- Auto-detects socket GID and passes `DOCKER_GID` env var for baseimage group setup\n- Emits security warning on Linux (macOS has VM isolation, no warning needed)\n- Exits with error if socket file doesn't exist (fail-fast, no silent degradation)\n\n**AWS Bedrock support:**\n\nWhen `--claude-provider=bedrock` or `RALPHEX_CLAUDE_PROVIDER=bedrock` is set:\n- Keychain credential extraction is skipped (not needed for Bedrock auth)\n- AWS credentials are automatically exported from `AWS_PROFILE` via `aws configure export-credentials`\n- Required Bedrock env vars are passed to container: `CLAUDE_CODE_USE_BEDROCK`, `AWS_REGION`, credentials\n\nRequired environment for Bedrock:\n- `AWS_REGION` - AWS region where Bedrock is enabled\n- `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`\u002F`AWS_SECRET_ACCESS_KEY` - authentication\n\nNote: `CLAUDE_CODE_USE_BEDROCK=1` is automatically set when using `--claude-provider=bedrock`.\n\n```bash\n# with AWS profile (credentials exported automatically)\nexport AWS_PROFILE=my-bedrock-profile\nexport AWS_REGION=us-east-1\nralphex --claude-provider=bedrock docs\u002Fplans\u002Ffeature.md\n\n# or use env var for session-wide setting\nexport RALPHEX_CLAUDE_PROVIDER=bedrock\nralphex docs\u002Fplans\u002Ffeature.md\n```\n\nSee [Bedrock setup documentation](docs\u002Fbedrock-setup.md) for detailed IAM policies and setup instructions.\n\n**Extra volume mounts:**\n```bash\n# via CLI flags (can use multiple -v)\nralphex -v \u002Fdata:\u002Fmnt\u002Fdata:ro -v \u002Fmodels:\u002Fmnt\u002Fmodels docs\u002Fplans\u002Ffeature.md\n\n# via environment variable (comma-separated)\nRALPHEX_EXTRA_VOLUMES=\"\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels\" ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**Extra environment variables:**\n```bash\n# via CLI flags (can use multiple -E)\nralphex -E DEBUG=1 -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# via environment variable (comma-separated)\nRALPHEX_EXTRA_ENV=\"DEBUG=1,LOG_LEVEL=verbose\" ralphex docs\u002Fplans\u002Ffeature.md\n\n# name-only form inherits value from host (recommended for secrets)\nexport API_KEY=secret123\nralphex -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# values containing commas require -E flag (env var splits on commas)\nralphex -E \"TAGS=foo,bar,baz\" docs\u002Fplans\u002Ffeature.md\n```\n\n**Debugging:**\n```bash\nralphex --dry-run docs\u002Fplans\u002Ffeature.md  # show docker command without executing\n```\n\nThe `--dry-run` flag prints the full `docker run` command that would be executed. Useful for debugging container configuration or copying the command for manual execution.\n\nNote: inherited env vars (`-E FOO` without `=value`) won't work when copying the command to a different shell. Use explicit values for portability.\n\n**Updating:**\n```bash\nralphex --update         # pull latest docker image\nralphex --update-script  # update the wrapper script itself\n```\n\n\u003Ca id=\"available-images\">\u003C\u002Fa>\n\u003Cdetails markdown>\n\u003Csummary>Available images\u003C\u002Fsummary>\n\nTwo images are published:\n\n| Image | Description |\n|-------|-------------|\n| `ghcr.io\u002Fumputun\u002Fralphex:latest` | Base image with Claude Code, Codex, and core tools |\n| `ghcr.io\u002Fumputun\u002Fralphex-go:latest` | Go development (extends base with Go toolchain) |\n\n**Base image includes:**\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| Claude Code | latest | AI coding assistant |\n| Codex | latest | External code review |\n| Node.js\u002Fnpm | 24.x | Required for Claude Code |\n| Python\u002Fpip | 3.x | Scripts and automation |\n| git | 2.x | Version control |\n| docker-cli | - | Docker client for container workflows |\n| make | 4.x | Build automation |\n| gcc, musl-dev | - | C compiler for native extensions |\n| bash | 5.x | Shell |\n| fzf | - | Fuzzy finder for plan selection |\n| ripgrep | - | Fast search (used by Claude Code) |\n\n**Go image adds:**\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| Go | 1.26.0 | Go compiler and runtime |\n| golangci-lint | latest | Go linter |\n| moq | latest | Mock generator |\n| goimports | latest | Import formatter |\n\n**For Go projects**, use the `-go` image:\n```bash\nRALPHEX_IMAGE=ghcr.io\u002Fumputun\u002Fralphex-go:latest ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**For other languages**, create a custom image by extending the base with your language toolchain. The Go image (`Dockerfile-go`) shows the pattern:\n\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# install go from official distribution\nARG GO_VERSION=1.26.0\nRUN ARCH=$(uname -m | sed 's\u002Fx86_64\u002Famd64\u002F;s\u002Faarch64\u002Farm64\u002F') && \\\n    wget -qO- \"https:\u002F\u002Fgo.dev\u002Fdl\u002Fgo${GO_VERSION}.linux-${ARCH}.tar.gz\" | tar -xz -C \u002Fusr\u002Flocal\n\nENV GOROOT=\u002Fusr\u002Flocal\u002Fgo\nENV GOPATH=\u002Fhome\u002Fapp\u002Fgo\nENV PATH=\"${PATH}:${GOROOT}\u002Fbin:${GOPATH}\u002Fbin\"\n\n# install go tools\nRUN wget -qO- https:\u002F\u002Fraw.githubusercontent.com\u002Fgolangci\u002Fgolangci-lint\u002FHEAD\u002Finstall.sh | sh -s -- -b \u002Fusr\u002Flocal\u002Fbin && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install github.com\u002Fmatryer\u002Fmoq@latest && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install golang.org\u002Fx\u002Ftools\u002Fcmd\u002Fgoimports@latest\n```\n\nSame approach for Rust, Java, or any other language:\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# rust\nRUN apk add --no-cache rust cargo\nENV CARGO_HOME=\u002Fhome\u002Fapp\u002F.cargo PATH=\"${PATH}:${CARGO_HOME}\u002Fbin\"\n\n# java\nRUN apk add --no-cache openjdk21-jdk\nENV JAVA_HOME=\u002Fusr\u002Flib\u002Fjvm\u002Fjava-21-openjdk PATH=\"${PATH}:${JAVA_HOME}\u002Fbin\"\n```\n\nBuild and use:\n```bash\ndocker build -t my-ralphex -f Dockerfile.python .\nRALPHEX_IMAGE=my-ralphex ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n\u003C\u002Fdetails>\n\nExample with custom port:\n```bash\nRALPHEX_PORT=3000 ralphex --serve --port=3000 docs\u002Fplans\u002Ffeature.md\n```\n\n## Usage\n\n**Note:** ralphex must be run from the repository root directory (where `.git` is located).\n\n```bash\n# execute plan with task loop + reviews\nralphex docs\u002Fplans\u002Ffeature.md\n\n# select plan with fzf, or create one interactively if none exist\nralphex\n\n# review-only mode (skip task execution)\nralphex --review docs\u002Fplans\u002Ffeature.md\n\n# external-only mode (skip tasks and first review, run only external review loop)\nralphex --external-only\n\n# tasks-only mode (run only task phase, skip all reviews)\nralphex --tasks-only docs\u002Fplans\u002Ffeature.md\n\n# run in isolated git worktree (full and tasks-only modes only)\nralphex --worktree docs\u002Fplans\u002Ffeature.md\n\n# override default branch for review diffs\nralphex --review --base-ref develop\nralphex --review --base-ref abc1234 --skip-finalize\n\n# initialize local .ralphex\u002F config in current project (commented-out defaults)\nralphex --init\n\n# interactive plan creation\nralphex --plan \"add user authentication\"\n\n# with custom max iterations\nralphex --max-iterations=100 docs\u002Fplans\u002Ffeature.md\n\n# limit external review iterations (0 = auto, derived from max-iterations)\nralphex --max-external-iterations=5 docs\u002Fplans\u002Ffeature.md\n\n# terminate external review after 3 unchanged rounds (stalemate detection)\nralphex --review-patience=3 docs\u002Fplans\u002Ffeature.md\n\n# wait and retry on rate limit (instead of exiting)\nralphex --wait=1h docs\u002Fplans\u002Ffeature.md\n\n# use different models for tasks vs reviews (e.g., opus for tasks, sonnet for reviews)\nralphex --task-model=opus --review-model=sonnet docs\u002Fplans\u002Ffeature.md\n\n# use provider overrides for one run without editing config\nralphex --claude-command=\u002Fpath\u002Fto\u002Fcodex-as-claude.sh --claude-args= --external-review-tool=custom --custom-review-script=\u002Fpath\u002Fto\u002Freview.sh docs\u002Fplans\u002Ffeature.md\n\n# set per-session timeout to kill hanging claude sessions\nralphex --session-timeout=30m docs\u002Fplans\u002Ffeature.md\n\n# kill claude session when no output for 5 minutes (idle detection)\nralphex --idle-timeout=5m docs\u002Fplans\u002Ffeature.md\n\n# preserve ANTHROPIC_API_KEY in the claude child env (for API-key auth users)\nralphex --preserve-anthropic-api-key docs\u002Fplans\u002Ffeature.md\n\n# with web dashboard\nralphex --serve docs\u002Fplans\u002Ffeature.md\n\n# web dashboard on custom port\nralphex --serve --port=3000 docs\u002Fplans\u002Ffeature.md\n```\n\n### Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-m, --max-iterations` | Maximum task iterations | 50 |\n| `--max-external-iterations` | Override external review iteration limit (0 = auto) | 0 |\n| `--review-patience` | Terminate external review after N unchanged rounds (0 = disabled) | 0 |\n| `-r, --review` | Skip task execution, run full review pipeline | false |\n| `-e, --external-only` | Skip tasks and first review, run only external review loop | false |\n| `-c, --codex-only` | Alias for `--external-only` (deprecated) | false |\n| `-t, --tasks-only` | Run only task phase, skip all reviews | false |\n| `-b, --base-ref` | Override default branch for review diffs (branch name or commit hash) | auto-detect |\n| `--skip-finalize` | Skip finalize step even if enabled in config | false |\n| `--task-model` | Model for task execution as `model[:effort]` (e.g., `opus`, `opus:high`, `:medium`). Effort values: `low`, `medium`, `high`, `xhigh`, `max`. Appended as `--model \u003Cm>` and\u002For `--effort \u003Ce>` to `claude_command`; custom wrappers may ignore or implement the flags | empty |\n| `--review-model` | Model for review phases as `model[:effort]` (falls back to `--task-model`). Same syntax and wrapper behavior as `--task-model` | empty |\n| `--claude-command` | Override the Claude-compatible command for this run | config\u002Fdefault |\n| `--claude-args` | Override Claude-compatible command arguments for this run. Use `--claude-args=` to clear configured\u002Fdefault args | config\u002Fdefault |\n| `--external-review-tool` | Override external review tool for this run (`codex`, `custom`, or `none`) | config\u002Fdefault |\n| `--custom-review-script` | Override custom external review script for this run | config\u002Fdefault |\n| `--wait` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |\n| `--session-timeout` | Per-session timeout for claude (e.g., `30m`, `1h`). Kills hanging sessions | disabled |\n| `--idle-timeout` | Kill claude session when no output for specified duration (e.g., `5m`). Resets on each output line | disabled |\n| `--worktree` | Run in isolated git worktree (full and tasks-only modes only) | false |\n| `--preserve-anthropic-api-key` | Pass `ANTHROPIC_API_KEY` through to claude (for users authenticating Claude Code via API key rather than OAuth\u002Fkeychain) | false |\n| `--plan` | Create plan interactively (provide description) | - |\n| `-s, --serve` | Start web dashboard for real-time streaming | false |\n| `-p, --port` | Web dashboard port (used with `--serve`) | 8080 |\n| `-w, --watch` | Directories to watch for progress files (repeatable) | - |\n| `-d, --debug` | Enable debug logging | false |\n| `--no-color` | Disable color output | false |\n| `--init` | Initialize local `.ralphex\u002F` config in current project | - |\n| `--reset` | Interactively reset global config to embedded defaults | - |\n| `--dump-defaults` | Extract raw embedded defaults to specified directory | - |\n| `--config-dir` | Custom config directory (env: `RALPHEX_CONFIG_DIR`) | `~\u002F.config\u002Fralphex` |\n\n## Plan File Format\n\nPlans are markdown files with task sections. Each task has checkboxes that claude marks complete.\n\n```markdown\n# Plan: Add User Authentication\n\n## Overview\nAdd JWT-based authentication to the API.\n\n## Validation Commands\n- `go test .\u002F...`\n- `golangci-lint run`\n\n### Task 1: Add auth middleware\n- [ ] Create JWT validation middleware\n- [ ] Add to router for protected routes\n- [ ] Add tests\n- [ ] Mark completed\n\n### Task 2: Add login endpoint\n- [ ] Create \u002Fapi\u002Flogin handler\n- [ ] Return JWT on successful auth\n- [ ] Add tests\n- [ ] Mark completed\n```\n\n**Requirements:**\n- Task headers must use `### Task N:` or `### Iteration N:` format (N can be integer or non-integer like `2.5`, `2a`)\n- Checkboxes: `- [ ]` (incomplete) or `- [x]` (completed)\n- Checkboxes belong only in Task sections (`### Task N:` or `### Iteration N:`). Do not put checkboxes in Success criteria, Overview, or Context — they cause extra loop iterations. The agent handles them gracefully when present, but plan authors should avoid them for best behavior.\n- Include `## Validation Commands` section with test\u002Flint commands\n- Place plans in `docs\u002Fplans\u002F` directory (configurable via `plans_dir`)\n\n## Review Agents\n\nThe review pipeline is fully customizable. ralphex ships with sensible defaults that work for any language, but you can modify agents, add new ones, or replace prompts entirely to match your specific workflow.\n\n### Default Agents\n\nThese 5 agents cover common review concerns and work well out of the box. Customize or replace them based on your needs:\n\n| Agent | Phase | Purpose |\n|-------|-------|---------|\n| `quality` | 1st & 2nd | bugs, security issues, race conditions |\n| `implementation` | 1st & 2nd | verifies code achieves stated goals |\n| `testing` | 1st only | test coverage and quality |\n| `simplification` | 1st only | detects over-engineering |\n| `documentation` | 1st only | checks if docs need updates |\n\n### Agent Options (Frontmatter)\n\nAgent files support optional YAML frontmatter for per-agent configuration:\n\n```txt\n---\nmodel: haiku\nagent: code-reviewer\n---\nReview the code for quality issues...\n```\n\n| Option | Values | Description |\n|--------|--------|-------------|\n| `model` | `haiku`, `sonnet`, `opus` | Claude model for this agent |\n| `agent` | any string | Claude Code Task tool subagent type |\n\nBoth options are optional. Without frontmatter, agents use default model and `general-purpose` subagent type. Full model IDs (e.g. `claude-sonnet-4-5-20250929`) are normalized to short keywords (`sonnet`) since Claude Code only accepts `haiku`, `sonnet`, `opus`. Invalid model values are dropped with a warning.\n\n### Template Syntax\n\nCustom prompt files support variable expansion. All variables use the `{{VARIABLE}}` syntax.\n\n**Available variables:**\n\n| Variable | Description | Example value |\n|----------|-------------|---------------|\n| `{{PLAN_FILE}}` | Path to the plan file being executed | `docs\u002Fplans\u002Ffeature.md` |\n| `{{PROGRESS_FILE}}` | Path to the progress log file | `.ralphex\u002Fprogress\u002Fprogress-feature.txt` |\n| `{{GOAL}}` | Human-readable goal description | `implementation of plan at docs\u002Fplans\u002Ffeature.md` |\n| `{{DEFAULT_BRANCH}}` | Default branch name (overridable via `--base-ref` or `default_branch` config) | `main`, `master`, `origin\u002Fmain` |\n| `{{agent:name}}` | Expands to Task tool instructions for the named agent | (see below) |\n\n**Agent references:**\n\nReference agents in prompt files using `{{agent:name}}` syntax:\n\n```\nLaunch the following review agents in parallel:\n{{agent:quality}}\n{{agent:implementation}}\n{{agent:testing}}\n```\n\nEach `{{agent:name}}` expands to Task tool instructions that tell Claude Code to run that agent. Variables inside agent content are also expanded, so agents can use `{{DEFAULT_BRANCH}}` or other variables.\n\n### Customization\n\nThe entire system is designed for customization - both task execution and reviews:\n\n**Agent files** (`~\u002F.config\u002Fralphex\u002Fagents\u002F`):\n- On first run, ralphex installs 5 default agent files as commented-out templates. These serve as examples — while fully commented out, they are inactive and the embedded defaults are used instead. Uncomment and edit to customize\n- Per-file fallback: for each agent, ralphex checks local `.ralphex\u002Fagents\u002F` → global `~\u002F.config\u002Fralphex\u002Fagents\u002F` → embedded default. The 5 embedded agents are always the baseline — deleting an agent file from disk does not disable it, the embedded version is used as fallback\n- To disable a specific agent, remove its `{{agent:name}}` reference from the prompt files (`review_first.txt`, `review_second.txt`), not the agent file itself\n- Add new `.txt` files to create custom agents (reference them in prompts with `{{agent:name}}`)\n- Run `ralphex --init` to create local `.ralphex\u002F` project config with commented-out defaults\n- Run `ralphex --reset` to interactively restore defaults, or delete all files manually\n- Run `ralphex --dump-defaults \u003Cdir>` to extract raw defaults for comparison\n- Use the `\u002Fralphex-update` Claude Code skill to smart-merge updated defaults into customized files\n- Alternatively, reference agents already installed in your Claude Code directly in prompt files (see example below)\n\n**Prompt files** (`~\u002F.config\u002Fralphex\u002Fprompts\u002F`):\n- `task.txt` - task execution prompt\n- `review_first.txt` - comprehensive review (default: 5 language-agnostic agents - quality, implementation, testing, simplification, documentation; customizable)\n- `codex.txt` - codex evaluation prompt (Claude evaluates codex output)\n- `codex_review.txt` - codex review prompt (sent to codex external review tool)\n- `custom_review.txt` - custom external review prompt (sent to custom review script)\n- `custom_eval.txt` - custom evaluation prompt (Claude evaluates custom tool output)\n- `review_second.txt` - final review, critical\u002Fmajor issues only (default: 2 agents - quality, implementation; customizable)\n- `make_plan.txt` - interactive plan creation prompt\n- `finalize.txt` - optional finalize step prompt (disabled by default)\n\n**Comment lines and markdown headers:**\nA leading block of 2+ contiguous comment lines (starting with `#`) at the top of a file is treated as a meta-comment and stripped when loading. A single `# Title` at the top is preserved (treated as a markdown header). Comment lines appearing later in the file body are always preserved:\n\n```txt\n# This single title line is preserved as a markdown header\ncheck for SQL injection\n# this mid-body comment is also preserved\ncheck for XSS\n```\n\nFiles containing *only* comment lines (every line starts with `#`) are treated as unmodified templates and fall back to embedded defaults. This is how commented-out default files work — once you add any non-comment content, the file is used as-is.\n\nNote: Inline comments are not supported (`text # comment` keeps the entire line).\n\n**Examples:**\n- Add a security-focused agent for fintech projects\n- Remove `{{agent:simplification}}` from prompt files if over-engineering isn't a concern\n- Create language-specific agents (Python linting, TypeScript types)\n- Modify prompts to change how many agents run per phase\n\n**Using Claude Code agents directly:**\n\nInstead of creating agent files, you can reference agents installed in your Claude Code directly in prompt files:\n\n```txt\n# in review_first.txt - just list agent names with their prompts\nAgents to launch:\n1. qa-expert - \"Review for bugs and security issues\"\n2. go-test-expert - \"Review test coverage and quality\"\n3. go-smells-expert - \"Review for code smells\"\n```\n\n## Requirements\n\n- `claude` - Claude Code CLI\n- `fzf` - for plan selection (optional)\n- `codex` - for external review (optional)\n\n## Configuration\n\nralphex uses a configuration directory at `~\u002F.config\u002Fralphex\u002F` (override with `--config-dir` or `RALPHEX_CONFIG_DIR`) with the following structure:\n\n```\n~\u002F.config\u002Fralphex\u002F\n├── config              # main configuration file (INI format)\n├── prompts\u002F            # custom prompt templates\n│   ├── task.txt\n│   ├── review_first.txt\n│   ├── review_second.txt\n│   ├── codex.txt\n│   ├── codex_review.txt\n│   ├── custom_review.txt\n│   ├── custom_eval.txt\n│   ├── make_plan.txt\n│   └── finalize.txt\n└── agents\u002F             # custom review agents (*.txt files)\n```\n\nOn first run, ralphex creates this directory with default configuration.\n\n**Commented templates:**\n- Config files are installed with all content commented out (`# ` prefix)\n- Uncomment only the settings you want to customize\n- Files that remain all-commented receive automatic updates with new defaults\n- Once you uncomment any setting, the file is preserved and won't be overwritten\n\n### Local Project Config\n\nProjects can override global settings with a `.ralphex\u002F` directory in the project root. Run `ralphex --init` to create it with commented-out defaults:\n\n```\nproject\u002F\n├── .ralphex\u002F           # optional, project-local config\n│   ├── config          # overrides specific settings\n│   ├── prompts\u002F        # custom prompts for this project\n│   └── agents\u002F         # custom agents for this project\n```\n\n**Priority:** CLI flags > local `.ralphex\u002F` > global `~\u002F.config\u002Fralphex\u002F` > embedded defaults\n\nUse `--config-dir` or `RALPHEX_CONFIG_DIR` to override the global config location. This is useful for maintaining separate agent\u002Fprompt sets for different workflows.\n\nProvider-related CLI flags (`--claude-command`, `--claude-args`, `--external-review-tool`, and `--custom-review-script`) follow the same priority and override config only for the current invocation. This is useful for switching wrappers or review tools without maintaining separate config directories.\n\n**Merge behavior:**\n- **Config file**: per-field override (local values override global, missing fields fall back)\n- **Prompts**: per-file fallback (local → global → embedded for each prompt file)\n- **Agents**: per-file fallback (local → global → embedded for each agent file, same as prompts)\n\n### Configuration options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `claude_command` | Claude CLI command | `claude` |\n| `claude_args` | Claude CLI arguments | `--dangerously-skip-permissions --output-format stream-json --verbose` |\n| `task_model` | Model for task execution as `model[:effort]` (e.g., `opus`, `opus:high`, `:medium`). Effort: `low`, `medium`, `high`, `xhigh`, `max`. Appended as `--model \u003Cm>` and\u002For `--effort \u003Ce>` to `claude_command`; custom wrappers may ignore or implement the flags | empty |\n| `review_model` | Model for review phases as `model[:effort]`. Falls back to `task_model` if empty. Same syntax and wrapper behavior as `task_model` | empty |\n| `codex_enabled` | Enable codex review phase | `true` |\n| `codex_command` | Codex CLI command | `codex` |\n| `codex_model` | Codex model ID | `gpt-5.4` |\n| `codex_reasoning_effort` | Reasoning effort level | `xhigh` |\n| `codex_timeout_ms` | Codex timeout in ms | `3600000` |\n| `codex_sandbox` | Sandbox mode | `read-only` |\n| `external_review_tool` | External review tool (`codex`, `custom`, `none`) | `codex` |\n| `custom_review_script` | Path to custom review script (when `external_review_tool = custom`) | - |\n| `max_external_iterations` | Override external review iteration limit (0 = auto, derived from `max_iterations`) | `0` |\n| `review_patience` | Terminate external review after N consecutive unchanged rounds (0 = disabled) | `0` |\n| `iteration_delay_ms` | Delay between iterations | `2000` |\n| `task_retry_count` | Task retry attempts | `1` |\n| `finalize_enabled` | Enable finalize step after reviews | `false` |\n| `move_plan_on_completion` | Move completed plan file into `docs\u002Fplans\u002Fcompleted\u002F` on success (disable for external plan-lifecycle workflows) | `true` |\n| `use_worktree` | Run each plan in an isolated git worktree (full and tasks-only modes only) | `false` |\n| `preserve_anthropic_api_key` | Pass `ANTHROPIC_API_KEY` through to the claude child process (for users authenticating Claude Code via API key rather than OAuth\u002Fkeychain). Default `false` strips the key so a host-set value cannot silently override OAuth credentials | `false` |\n| `plans_dir` | Plans directory | `docs\u002Fplans` |\n| `default_branch` | Override auto-detected default branch for review diffs | auto-detect |\n| `vcs_command` | VCS command for the git backend (set to a translation script for hg repos) | `git` |\n| `commit_trailer` | Trailer line appended to all ralphex-orchestrated git commits | disabled |\n| `color_task` | Task execution phase color (hex) | `#00ff00` |\n| `color_review` | Review phase color (hex) | `#00ffff` |\n| `color_codex` | Codex review color (hex) | `#ff00ff` |\n| `color_claude_eval` | Claude evaluation color (hex) | `#64c8ff` |\n| `color_warn` | Warning messages color (hex) | `#ffff00` |\n| `color_error` | Error messages color (hex) | `#ff0000` |\n| `color_signal` | Completion\u002Ffailure signals color (hex) | `#ff6464` |\n| `color_timestamp` | Timestamp prefix color (hex) | `#8a8a8a` |\n| `color_info` | Informational messages color (hex) | `#b4b4b4` |\n| `claude_error_patterns` | Patterns to detect in claude output (comma-separated) | `You've hit your limit,API Error:,cannot be launched inside another Claude Code session,Not logged in,Your usage allocation has been disabled by your admin,You've hit your org's monthly usage limit` |\n| `codex_error_patterns` | Patterns to detect in codex output (comma-separated) | `Rate limit exceeded,rate limit reached,429 Too Many Requests,quota exceeded,insufficient_quota,You've hit your usage limit` |\n| `claude_limit_patterns` | Limit patterns for claude triggering wait+retry (comma-separated) | `You've hit your limit,Your usage allocation has been disabled by your admin,You've hit your org's monthly usage limit` |\n| `codex_limit_patterns` | Limit patterns for codex triggering wait+retry (comma-separated) | `Rate limit exceeded,rate limit reached,429 Too Many Requests,quota exceeded,insufficient_quota,You've hit your usage limit` |\n| `wait_on_limit` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |\n| `session_timeout` | Per-session timeout for claude (e.g., `30m`, `1h`). Kills hanging sessions | disabled |\n| `idle_timeout` | Kill claude session when no output for specified duration (e.g., `5m`). Resets on each output line | disabled |\n\nColors use 24-bit RGB (true color), supported natively by all modern terminals (iTerm2, Kitty, Terminal.app, Windows Terminal, GNOME Terminal, Alacritty, Zed, VS Code, etc). Older terminals will degrade gracefully. Use `--no-color` to disable colors entirely.\n\nError patterns use case-insensitive substring matching. When a pattern is detected in claude or codex output, ralphex exits gracefully with an informative message suggesting how to check usage\u002Fstatus. Multiple patterns are separated by commas, with whitespace trimmed from each pattern.\n\n**Rate limit retry:** Limit patterns (`claude_limit_patterns`, `codex_limit_patterns`) work similarly but support optional wait+retry behavior. When `--wait` is set (or `wait_on_limit` in config), a limit pattern match triggers a wait followed by automatic retry instead of exiting. Without `--wait`, limit patterns fall through to error pattern behavior. Limit patterns are checked before error patterns — if the same string matches both, the limit pattern takes priority when wait is enabled.\n\n**Note for upgrades:** the codex defaults are tightened so review findings that *talk about* rate limiting in a codebase do not trip a false positive. Earlier defaults (`Rate limit,quota exceeded` or `Rate limit,quota exceeded,You've hit your usage limit`) substring-matched any text containing \"rate limit\", which fired on findings text when codex exited non-zero for an unrelated reason. Users who customized `codex_limit_patterns` or `codex_error_patterns` keep their values on update; comment the line out to inherit the new embedded default. The phrase `You've hit your usage limit` is retained because codex emits it on stderr when the ChatGPT plan quota is exhausted, and it never appears in findings text.\n\n### Custom prompts\n\nPlace custom prompt files in `~\u002F.config\u002Fralphex\u002Fprompts\u002F` to override the built-in prompts. Missing files fall back to embedded defaults. See [Review Agents](#review-agents) section for agent customization.\n\n### Custom External Review\n\nUse your own AI tool for external code review instead of codex. This allows integration with OpenRouter, local LLMs, or any custom pipeline.\n\n**Configuration:**\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig\nexternal_review_tool = custom\ncustom_review_script = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\n```\n\nFor a one-off run without editing config, use `--external-review-tool=custom --custom-review-script=\u002Fpath\u002Fto\u002Fscript.sh`.\n\n**Script interface:**\n\nYour script receives a single argument: path to a prompt file containing review instructions. The script outputs findings to stdout - ralphex passes them to Claude for evaluation and fixing.\n\n```bash\n#!\u002Fbin\u002Fbash\n# example: ~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\nprompt_file=\"$1\"\n\n# read the prompt (contains diff instructions, goal, review focus)\nprompt=$(cat \"$prompt_file\")\n\n# call your AI tool (OpenRouter, local LLM, etc.)\n# example with curl to OpenRouter:\ncurl -s https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $OPENROUTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d \"{\n    \\\"model\\\": \\\"anthropic\u002Fclaude-3.5-sonnet\\\",\n    \\\"messages\\\": [{\\\"role\\\": \\\"user\\\", \\\"content\\\": $(echo \"$prompt\" | jq -Rs .)}]\n  }\" | jq -r '.choices[0].message.content'\n```\n\n**Expected output format:**\n\n- Write findings to stdout as a structured list\n- Use format: `file:line - description of issue`\n- Output `NO ISSUES FOUND` when there are no problems\n\n**Iteration behavior:**\n\nThe external review loop runs up to `max(3, max_iterations\u002F5)` iterations by default. Override with `max_external_iterations` config option or `--max-external-iterations` CLI flag (0 = auto).\n\nThe prompt's `{{DIFF_INSTRUCTION}}` variable adapts per iteration:\n- **First iteration**: `git diff main...HEAD` (all changes in feature branch)\n- **Subsequent iterations**: `git diff` (only uncommitted changes from previous fixes)\n\nThis lets the review tool focus on remaining issues after fixes.\n\n### Notifications\n\nralphex can send notifications when execution completes or fails. Notifications are optional, disabled by default, and best-effort - failures are logged but never affect the exit code.\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nnotify_channels = telegram, webhook\nnotify_telegram_token = 123456:ABC-DEF\nnotify_telegram_chat = -1001234567890\nnotify_webhook_urls = https:\u002F\u002Fhooks.example.com\u002Fnotify\n```\n\nSupported channels: `telegram`, `email`, `slack`, `webhook`, `custom` (script). Misconfigured channels are detected at startup.\n\nSee [notifications documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fnotifications.md) for setup guides, message format examples, and custom script integration.\n\n**Prompt customization:**\n\nCustomize `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_review.txt` to modify the prompt sent to your script. Available variables:\n- `{{DIFF_INSTRUCTION}}` - git diff command appropriate for current iteration\n- `{{GOAL}}` - human-readable description of what's being implemented\n- `{{PLAN_FILE}}` - path to the plan file\n- `{{PROGRESS_FILE}}` - path to progress log with previous review iterations\n- `{{DEFAULT_BRANCH}}` - detected default branch (main, master, etc.)\n- `{{PREVIOUS_REVIEW_CONTEXT}}` - previous review context (empty on first iteration, populated on subsequent)\n\nCustomize `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_eval.txt` to modify how Claude evaluates your tool's output.\n\n**Docker considerations:**\n\nWhen running ralphex in Docker, your script must be accessible inside the container:\n- Mount your scripts directory: `-v ~\u002F.config\u002Fralphex\u002Fscripts:\u002Fhome\u002Fapp\u002F.config\u002Fralphex\u002Fscripts:ro`\n- Ensure script dependencies are available (curl, jq, etc. are included in base image)\n- Environment variables (API keys) must be passed to container: `-e OPENROUTER_API_KEY`\n\n### Using Alternative Providers for Claude Phases\n\nThe `claude_command` and `claude_args` config options let you replace Claude Code with any CLI that produces compatible `stream-json` output. This means codex, GitHub Copilot CLI, Gemini CLI, local LLMs, or any other tool can drive task execution and review phases — you just need a wrapper script that translates the tool's output format. Use `--claude-command` and `--claude-args` to choose a wrapper for a single run without changing config.\n\nWorking examples are included:\n\n- [`scripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh) wraps codex to produce Claude-compatible events\n- [`scripts\u002Fcopilot-as-claude\u002Fcopilot-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fcopilot-as-claude\u002Fcopilot-as-claude.sh) wraps GitHub Copilot CLI and translates its native JSONL stream into Claude-compatible events\n- [`scripts\u002Fgemini-as-claude\u002Fgemini-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fgemini-as-claude\u002Fgemini-as-claude.sh) wraps Gemini CLI for the implementation slot\n- [`scripts\u002Fopencode\u002Fopencode-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fopencode\u002Fopencode-as-claude.sh) wraps OpenCode CLI for the implementation slot, and `scripts\u002Fopencode\u002Fopencode-review.sh` is shipped alongside as a turn-key custom review script\n\nTo use the included Copilot wrapper:\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nclaude_command = \u002Fpath\u002Fto\u002Fscripts\u002Fcopilot-as-claude\u002Fcopilot-as-claude.sh\nclaude_args =\n```\n\nAuthenticate with `copilot login` or set one of `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`. Set `COPILOT_MODEL` to choose the model.\nThe wrapper runs Copilot in native autopilot mode with `--autopilot --no-ask-user --allow-all` so task and review phases can continue across multiple model turns without manual intervention.\nFor ralphex plan creation, it switches to `--autopilot --allow-all` so clarification can surface through `\u003C\u003C\u003CRALPHEX:QUESTION>>>` signals instead of being suppressed by the unattended question path.\n\nTo use the included codex wrapper:\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nclaude_command = \u002Fpath\u002Fto\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\nOr choose it for one invocation:\n\n```bash\nralphex --claude-command=\u002Fpath\u002Fto\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh --claude-args= docs\u002Fplans\u002Ffeature.md\n```\n\nSetting `claude_args` to empty in config is optional. Note that default Claude flags (`--dangerously-skip-permissions`, `--output-format stream-json`, `--verbose`) may still be passed due to config fallback behavior. Use the CLI form `--claude-args=` when you need to explicitly clear configured\u002Fdefault args for a single run. Wrapper scripts should ignore unknown flags gracefully — the included script does this via its `*) shift ;;` catch-all.\n\nThe included Codex and Copilot wrappers require `jq` on `PATH` for JSON translation.\n\nProvider-specific environment variables:\n- `COPILOT_MODEL`, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` - Copilot model selection and headless authentication\n- `CODEX_MODEL` - codex model to use (default: codex default)\n- `CODEX_SANDBOX` - sandbox mode (default: `danger-full-access`)\n- `CODEX_VERBOSE` - set to `1` to include command execution output in the stream (default: `0`, only agent messages are shown)\n\nSee [custom providers documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md) for a detailed guide on writing wrappers for other providers.\n\n### Swapping Implementation and Review Roles\n\nThe default pairing is Claude for implementation and Codex for external review. The same mechanisms that replace Claude with another tool can also flip the roles, putting another tool in the implementation slot and Claude (or anything else) in the review slot. Combine `claude_command` with `external_review_tool = custom` and `custom_review_script`:\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nclaude_command       = \u002Fpath\u002Fto\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh\nexternal_review_tool = custom\ncustom_review_script = \u002Fpath\u002Fto\u002Fscripts\u002Fopencode\u002Fopencode-review.sh\n```\n\nThe `claude_command` slot is documented above. The `custom_review_script` slot, including the script interface and expected output format, is documented in [Custom External Review](#custom-external-review).\n\nThe repository ships a working custom review script at [`scripts\u002Fopencode\u002Fopencode-review.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fopencode\u002Fopencode-review.sh) that uses OpenCode CLI to produce review findings. Use it directly, or read it as a template when writing your own (for example, a `claude-as-review.sh` that calls Claude in the review slot).\n\nThe wrappers under `scripts\u002Fcodex-as-claude\u002F`, `scripts\u002Fcopilot-as-claude\u002F`, `scripts\u002Fgemini-as-claude\u002F`, and `scripts\u002Fopencode\u002F` ship in the source tree but are not bundled with the binary. Vendor the one you need into your project (`.ralphex\u002Fscripts\u002F`) or reference it from a checkout.\n\n**Log labels reflect the slot, not the underlying tool.** Phase output keeps the internal slot names (`claude execution`, `codex execution`) regardless of what `claude_command` and the external review tool resolve to at runtime. With a wrapper in place, \"claude execution\" means whatever `claude_command` points at.\n\n**Per-project config on feature branches.** If tool-swap configuration lives inside the project (`.ralphex\u002Fconfig`, scripts under `.ralphex\u002Fscripts\u002F`), commit those files on the default branch before creating a feature branch. Otherwise the reviewer sees its own infrastructure as new in the feature branch, which can trigger `RALPHEX:TASK_FAILED` when project rules forbid modifying `.ralphex\u002F`. Keeping the configuration in `~\u002F.config\u002Fralphex\u002F` instead avoids that case entirely.\n\n### Configurable VCS Backend\n\nralphex can work with Mercurial repositories through the `vcs_command` config option and custom prompt files.\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nvcs_command = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fhg2git.sh\n```\n\nA reference translation script is included at [`scripts\u002Fhg2git\u002Fhg2git.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fhg2git\u002Fhg2git.sh). It maps the ~15 git subcommands ralphex uses internally to Mercurial equivalents, with phase-based commit logic (amend on draft, commit on public). Requires bash 4.0+ (for associative arrays used in diff stats parsing).\n\nYou will also need to customise prompt files to replace git commands that Claude executes as bash commands during reviews. See [Mercurial support documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fhg-support.md) for full setup instructions, prompt replacement examples, `.hgignore` setup, and known limitations.\n\n\u003Cdetails markdown>\n\u003Csummary>\u003Cb>FAQ\u003C\u002Fb>\u003C\u002Fsummary>\n\n**I installed ralphex, what do I do next?**\n\nCreate a plan file in `docs\u002Fplans\u002F` (see [Quick Start](#quick-start) for format), then run `ralphex docs\u002Fplans\u002Fyour-plan.md`. ralphex will create a branch, execute tasks, and run reviews automatically.\n\n**Why are there two review phases?**\n\nFirst review is comprehensive (5 agents by default), second is a final check focusing on critical\u002Fmajor issues only (2 agents). See [How It Works](#how-it-works).\n\n**How do I use my own Claude Code agents?**\n\nReference them directly in prompt files by name, e.g., `qa-expert - \"Review for bugs\"`. See [Customization](#customization).\n\n**What if codex isn't installed?**\n\nCodex is optional. If not installed, the codex review phase is skipped automatically.\n\n**Can I run just reviews without task execution?**\n\nYes, use `--review` flag to run the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already on the current branch. This works for changes made by any tool — Claude Code's built-in mode, manual edits, other agents, etc. Switch to the feature branch, commit your changes, and run `ralphex --review`. See [Review-Only Mode](#review-only-mode) for details.\n\n**Can I run ralphex in a non-git directory?**\n\nNot directly, but ralphex supports Mercurial repos through the `vcs_command` config option and a translation script. See [Configurable VCS Backend](#configurable-vcs-backend) for setup.\n\n**What if my repository has no commits?**\n\nralphex prompts to create an initial commit when the repository is empty. This is required because ralphex needs branches for feature isolation. Answer \"y\" to let ralphex stage all files and create an initial commit, or create one manually first with `git add . && git commit -m \"initial commit\"`.\n\n**Should I run ralphex on master or a feature branch?**\n\nFor full mode, start on master - ralphex creates a branch automatically from the plan filename. For `--review` mode, switch to your feature branch first - reviews compare against master using `git diff master...HEAD`.\n\n**How do I restore default agents after customizing?**\n\nRun `ralphex --reset` to interactively reset global config. Select which components to reset (config, prompts, agents). Alternatively, delete all `.txt` files from `~\u002F.config\u002Fralphex\u002Fagents\u002F` manually. To smart-merge updated defaults into customized files (preserving your changes), use the `\u002Fralphex-update` Claude Code skill or `ralphex --dump-defaults \u003Cdir>` to extract defaults for manual comparison.\n\n**How do I disable a default agent?**\n\nDeleting an agent file from `~\u002F.config\u002Fralphex\u002Fagents\u002F` does not disable it — the embedded default is used as fallback. To disable a specific agent, edit the prompt files (`review_first.txt`, `review_second.txt`) and remove the `{{agent:name}}` reference for that agent.\n\n**How does local .ralphex\u002F config interact with global config?**\n\nPriority: CLI flags > local `.ralphex\u002Fconfig` > global `~\u002F.config\u002Fralphex\u002Fconfig` > embedded defaults. Each local setting overrides the corresponding global one—no need to duplicate the entire file. For agents: per-file fallback (local → global → embedded), same as prompts. Override one agent without copying all others.\n\n**What happens to uncommitted changes if ralphex fails?**\n\nRalphex commits after each completed task. If execution fails, completed tasks are already committed to the feature branch. Uncommitted changes from the failed task remain in the working directory for manual inspection.\n\n**What if ralphex is interrupted mid-execution?**\n\nCompleted tasks are already committed to the feature branch. To resume, re-run `ralphex docs\u002Fplans\u002F\u003Cplan>.md`. Ralphex detects completed tasks via `[x]` checkboxes in the plan and continues from the first incomplete task. For review sessions, simply restart. Reviews re-run from iteration 1, but fixes from previous iterations remain in the codebase.\n\n**Can I adjust the plan or change direction while ralphex is running?**\n\nYes, two approaches depending on the situation:\n\n1. **Edit CLAUDE.md** — for behavioral changes (coding style, libraries, constraints). Each task runs in a fresh Claude Code session that reads CLAUDE.md at startup, so changes take effect on the next task or iteration automatically. No need to stop ralphex.\n\n2. **Stop, edit plan, re-run** — for structural changes (reorder tasks, add\u002Fremove tasks, change requirements). Press Ctrl+C to stop, edit the plan file (uncheck `[x]` → `[ ]` to redo tasks, add new tasks, modify descriptions), then re-run `ralphex docs\u002Fplans\u002F\u003Cplan>.md`. Ralphex picks up from the first incomplete task and adapts to the updated plan.\n\n**What's the difference between progress file and plan file?**\n\nProgress file (`.ralphex\u002Fprogress\u002Fprogress-*.txt`) is a real-time execution log—tail it to monitor. Plan file tracks task state (`[ ]` vs `[x]`). To resume, re-run ralphex on the plan file; it finds incomplete tasks automatically.\n\n**Do I need to commit changes before running ralphex?**\n\nIt depends. If the plan file is the only uncommitted change, ralphex auto-commits it after creating the feature branch and continues execution. If other files have uncommitted changes, ralphex shows a helpful error with options: stash temporarily (`git stash`), commit first (`git commit -am \"wip\"`), or use review-only mode (`ralphex --review`).\n\n**What's the difference between agents\u002F and prompts\u002F?**\n\nAgents define *what* to check (review instructions). Prompts define *how* the workflow runs (execution steps, signal handling).\n\n**Can I run a custom step before or after all tasks complete?**\n\nYes. Customize `prompts\u002Ftask.txt` to inject extra steps at any point in the task lifecycle. A common pattern is adding a \"gate step\" that runs after all tasks are done but before signaling completion. For example, to run a code smells check after the last task:\n\n```txt\nSTEP 3 - COMPLETE (after validation passes):\n- ...existing steps...\n- If NO more [ ] checkboxes in the entire plan, proceed to STEP 4\n\nSTEP 4 - STYLE CHECK (only when all tasks are done):\n- Use \u002Fsmells skill to analyze all files changed on this branch\n- Fix all reported style and code quality issues\n- Run tests and linter again to verify fixes\n- Commit fixes if any: fix: address code smell findings\n- Output exactly: \u003C\u003C\u003CRALPHEX:ALL_TASKS_DONE>>>\n```\n\nThis works because ralphex only checks for the `ALL_TASKS_DONE` signal — it doesn't care how many steps precede it. The same approach works for any tool or skill: security scanning, formatting, documentation generation, etc. Place it in `~\u002F.config\u002Fralphex\u002Fprompts\u002Ftask.txt` for global use or `.ralphex\u002Fprompts\u002Ftask.txt` for a specific project.\n\n**Can I use ralphex with Claude Pro plan?**\n\nYes. Pro plans hit rate limits more frequently. Use `--wait` to pause and retry automatically instead of exiting:\n\n```bash\nralphex --wait=1h docs\u002Fplans\u002Ffeature.md\n```\n\nWhen a rate limit is detected, ralphex waits the specified duration and retries. Execution takes longer but completes unattended. You can also set `wait_on_limit = 1h` in config to make it the default.\n\n**Can I use Cursor CLI instead of Claude Code?**\n\nYes. [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fcli) is community-tested as a drop-in alternative. Configure in `~\u002F.config\u002Fralphex\u002Fconfig`:\n\n```ini\nclaude_command = agent\nclaude_args = --force --output-format stream-json\n```\n\nKey differences: `agent` command (not `claude`), `--force` flag (not `--dangerously-skip-permissions`). Stream format and signals are compatible. *Note: this is community-tested, not officially supported. Compatibility depends on Cursor maintaining Claude Code compatibility.*\n\n**Can I use codex, GitHub Copilot CLI, or another model for task execution instead of Claude?**\n\nYes. Use one of the included wrapper scripts that translate provider output to Claude's stream-json format:\n\n```ini\nclaude_command = \u002Fpath\u002Fto\u002Fscripts\u002Fcopilot-as-claude\u002Fcopilot-as-claude.sh\nclaude_args =\n```\n\nFor Copilot, authenticate with `copilot login` or one of `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`, and set `COPILOT_MODEL` if you want to override the default model.\nThe included Copilot wrapper runs Copilot in native autopilot mode with `--autopilot --no-ask-user --allow-all` for unattended task and review execution.\nFor ralphex plan creation, it switches to `--autopilot --allow-all` so clarification can surface through `\u003C\u003C\u003CRALPHEX:QUESTION>>>` signals instead of being suppressed by the unattended question path.\n\nCodex works the same way through its wrapper:\n\n```ini\nclaude_command = \u002Fpath\u002Fto\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\nSet `CODEX_MODEL` env var to choose the model. See [Using Alternative Providers](#using-alternative-providers-for-claude-phases) and [custom providers documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md) for the included Copilot example and for writing wrappers for other tools.\n\n**How do I use multiple Claude accounts?**\n\nSet the `CLAUDE_CONFIG_DIR` environment variable to point to the alternate Claude config directory:\n\n```bash\nCLAUDE_CONFIG_DIR=~\u002F.claude2 ralphex docs\u002Fplans\u002Ffeature.md\n```\n\nThis is the same env var Claude Code itself uses. With Docker, the wrapper script mounts the specified directory and derives the correct macOS Keychain service name from the path. Without Docker, the env var passes through to the child Claude Code process directly. Each Claude installation stores credentials under a unique Keychain entry based on its config directory. No additional configuration is needed — just point `CLAUDE_CONFIG_DIR` to the right directory.\n\n**Can I run something after all phases complete (notifications, rebase commits, etc.)?**\n\nYes. Enable the finalize step with `finalize_enabled = true` in config. It runs once after successful review phases (best-effort—failures are logged but don't block success). The default `finalize.txt` prompt rebases onto the default branch and optionally squashes commits into logical groups. Customize `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt` for other actions like sending notifications, pushing to remote, or running custom scripts.\n\n\u003C\u002Fdetails>\n\n## Web Dashboard\n\nThe `--serve` flag starts a browser-based dashboard for real-time monitoring of plan execution.\n\n```bash\nralphex --serve docs\u002Fplans\u002Ffeature.md\n# web dashboard: http:\u002F\u002Flocalhost:8080\n```\n\n### Features\n\n- **Real-time streaming** - SSE","ralphex 是一个用于自主执行代码实现计划的命令行工具。它通过Claude Code在终端中运行，无需IDE插件或云服务，只需一个二进制文件即可自动完成复杂功能的开发任务。项目的核心特点是能够保持模型在整个计划执行过程中的高效性，每个任务都在一个新的会话中执行以减少上下文负担，从而避免了长时间会话导致的质量下降问题。此外，ralphex 提供了多阶段代码审查、自定义审查代理配置、自动分支创建与提交等功能，并支持实时监控和Web仪表板展示进度。适合需要自动化处理软件开发流程、特别是那些涉及多个子任务且耗时较长的场景使用。",2,"2026-06-11 03:50:18","high_star"]