Skip to content
Back to search

ralphex

MarketplaceWorks with Claude CodeGitHub

Extended Ralph loop for autonomous AI-driven plan execution

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/umputun/ralphex with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/umputun/ralphex'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/umputun--ralphex/badge.svg)](/listings/umputun--ralphex)

HTML

<a href="/listings/umputun--ralphex"><img src="/api/listings/umputun--ralphex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Make sure ralphex is [installed](#installation) and your project is a git repository. You need a [plan file](#plan-creation) in `docs/plans/`, for example:

# Plan: My Feature

## Validation Commands
- `go test ./...`

### Task 1: Implement feature
- [ ] Add the new functionality
- [ ] Add tests

Then run:

ralphex docs/plans/my-feature.md

ralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to `completed/` when done (on the feature branch under `--worktree`).

> [!WARNING] > **Anthropic Agent SDK billing change on June 15, 2026** > > Anthropic is moving `claude -p` / `claude --print`, Claude Agent SDK, and Claude Code GitHub Actions usage to a separate monthly Agent SDK credit pool for Claude subscription users. The default Claude mode in ralphex uses `claude --print` internally, so unattended ralphex runs are part of that pool. See Anthropic's [Agent SDK credit article](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for the current billing rules. > > Practical options: > > 1. Do nothing. Light use may fit inside the included monthly credit. This should also be transparent for users who already run Claude Code through API-key billing, Bedrock, Vertex, Foundry, or another non-subscription provider path. > 2. Use a skill-based flow in an interactive Claude Code session. The author's [`umputun/cc-thingz`](https://github.com/umputun/cc-thingz) plugin collection includes the `planning` family (`/planning:make` and `/planning:exec`). That keeps work inside the normal interactive Claude Code flow instead of `claude --print`. > 3. Switch the ralphex executor to codex. First-class [`--codex`](#codex-executor-mode) support routes plan creation, task execution, both review phases, and finalize through the codex CLI and skips the external codex review phase. > 4. Use a `claude -p` compatible wrapper that drives an interactive Claude Code session and emits Claude-compatible `stream-json`. Examples that match ralphex's invocation shape include [`umputun/fya`](https://github.com/umputun/fya), [`melonamin/agentrun`](https://github.com/melonamin/agentrun), [`Equality-Machine/claude-p`](https://github.com/Equality-Machine/claude-p), and [`kcosr/claude-pty-wrapper`](https://github.com/kcosr/claude-pty-wrapper). These wrappers are unofficial and may break if Anthropic changes or blocks this pattern.

<details markdown> <summary>Wrapper configuration examples</summary>

Install `fya` with Homebrew:

brew install umputun/apps/fya
command -v fya

Use the absolute path printed by `command -v fya` in ralphex config. On Apple Silicon Homebrew this is normally `/opt/homebrew/bin/fya`:

# in ~/.config/ralphex/config or .ralphex/config
claude_command = /opt/homebrew/bin/fya
claude_args = --dangerously-skip-permissions --output-format stream-json --verbose

On Intel Homebrew the path is normally `/usr/local/bin/fya`. If `command -v fya` prints another path, use that exact path instead.

For `agentrun`, use its tmux-backed path if the goal is avoiding direct `claude --print`:

claude_command = /absolute/path/to/agentrun
claude_args = --persist-session --no-session-persistence --dangerously-skip-permissions --output-format stream-json --verbose

These tools depend on interactive Claude Code behavior and local transcript files staying usable. Anthropic may detect or block wrapper-style automation later, so test the exact tool before relying on it.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "ralphex",
  3. "owner": {
  4. "name": "umputun",
  5. "email": "umputun@gmail.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "ralphex",
  10. "source": "./",
  11. "description": "Autonomous plan execution with Claude Code - task execution, monitoring, and plan creation",
  12. "version": "0.20.0",
  13. "author": {
  14. "name": "umputun"
  15. }
  16. }
  17. ]
  18. }
README.md · README · 1,477 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/ralphex-wordmark-split.png" alt="ralphex" width="400">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/umputun/ralphex/actions/workflows/ci.yml"><img src="https://github.com/umputun/ralphex/actions/workflows/ci.yml/badge.svg" alt="build"></a>
  6. <a href="https://coveralls.io/github/umputun/ralphex?branch=master"><img src="https://coveralls.io/repos/github/umputun/ralphex/badge.svg?branch=master" alt="Coverage Status"></a>
  7. <a href="https://goreportcard.com/report/github.com/umputun/ralphex"><img src="https://goreportcard.com/badge/github.com/umputun/ralphex?v=2" alt="Go Report Card"></a>
  8. </p>
  9. <h2 align="center">Autonomous plan execution with Claude Code and codex</h2>
  10. *ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates Claude Code or codex to execute implementation plans autonomously - no IDE plugins or cloud services required, just a coding agent and a single binary.*
  11. Claude 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.
  12. ralphex 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.
  13. <details markdown>
  14. <summary>Task Execution Screenshot</summary>
  15. ![ralphex tasks](assets/ralphex-tasks.png)
  16. </details>
  17. <details markdown>
  18. <summary>Review Mode Screenshot</summary>
  19. ![ralphex review](assets/ralphex-review.png)
  20. </details>
  21. <details markdown>
  22. <summary>Web Dashboard Screenshot</summary>
  23. ![ralphex web dashboard](assets/ralphex-web.png)
  24. </details>
  25. ## Features
  26. - **Zero setup** - works out of the box with sensible defaults, no configuration required
  27. - **Autonomous task execution** - executes plan tasks one at a time with automatic retry
  28. - **Interactive plan creation** - create plans through dialogue with Claude via `--plan` flag
  29. - **Multi-phase code review** - 5 agents → codex → 2 agents review pipeline
  30. - **Custom review agents** - configurable agents with `{{agent:name}}` template system and user defined prompts
  31. - **Automatic branch creation** - creates git branch from plan filename
  32. - **Plan completion tracking** - moves completed plans to `completed/` folder
  33. - **Automatic commits** - commits after each task and review fix
  34. - **Real-time monitoring** - streaming output with timestamps, colors, and detailed logs
  35. - **Web dashboard** - browser-based real-time view with `--serve` flag
  36. - **Docker support** - run in isolated container for safer autonomous execution
  37. - **Notifications** - optional alerts on completion/failure via Telegram, Email, Slack, Webhook, or custom script
  38. - **Worktree isolation** - run multiple plans in parallel via `--worktree` flag
  39. - **Multiple modes** - full execution, tasks-only, review-only, external-only, or plan creation
  40. ## Quick Start
  41. Make sure ralphex is [installed](#installation) and your project is a git repository. You need a [plan file](#plan-creation) in `docs/plans/`, for example:
  42. ```markdown
  43. # Plan: My Feature
  44. ## Validation Commands
  45. - `go test ./...`
  46. ### Task 1: Implement feature
  47. - [ ] Add the new functionality
  48. - [ ] Add tests
  49. ```
  50. Then run:
  51. ```bash
  52. ralphex docs/plans/my-feature.md
  53. ```
  54. ralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to `completed/` when done (on the feature branch under `--worktree`).
  55. > [!WARNING]
  56. > **Anthropic Agent SDK billing change on June 15, 2026**
  57. >
  58. > Anthropic is moving `claude -p` / `claude --print`, Claude Agent SDK, and Claude Code GitHub Actions usage to a separate monthly Agent SDK credit pool for Claude subscription users. The default Claude mode in ralphex uses `claude --print` internally, so unattended ralphex runs are part of that pool. See Anthropic's [Agent SDK credit article](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for the current billing rules.
  59. >
  60. > Practical options:
  61. >
  62. > 1. Do nothing. Light use may fit inside the included monthly credit. This should also be transparent for users who already run Claude Code through API-key billing, Bedrock, Vertex, Foundry, or another non-subscription provider path.
  63. > 2. Use a skill-based flow in an interactive Claude Code session. The author's [`umputun/cc-thingz`](https://github.com/umputun/cc-thingz) plugin collection includes the `planning` family (`/planning:make` and `/planning:exec`). That keeps work inside the normal interactive Claude Code flow instead of `claude --print`.
  64. > 3. Switch the ralphex executor to codex. First-class [`--codex`](#codex-executor-mode) support routes plan creation, task execution, both review phases, and finalize through the codex CLI and skips the external codex review phase.
  65. > 4. Use a `claude -p` compatible wrapper that drives an interactive Claude Code session and emits Claude-compatible `stream-json`. Examples that match ralphex's invocation shape include [`umputun/fya`](https://github.com/umputun/fya), [`melonamin/agentrun`](https://github.com/melonamin/agentrun), [`Equality-Machine/claude-p`](https://github.com/Equality-Machine/claude-p), and [`kcosr/claude-pty-wrapper`](https://github.com/kcosr/claude-pty-wrapper). These wrappers are unofficial and may break if Anthropic changes or blocks this pattern.
  66. <details markdown>
  67. <summary>Wrapper configuration examples</summary>
  68. Install `fya` with Homebrew:
  69. ```bash
  70. brew install umputun/apps/fya
  71. command -v fya
  72. ```
  73. Use the absolute path printed by `command -v fya` in ralphex config. On Apple Silicon Homebrew this is normally `/opt/homebrew/bin/fya`:
  74. ```ini
  75. # in ~/.config/ralphex/config or .ralphex/config
  76. claude_command = /opt/homebrew/bin/fya
  77. claude_args = --dangerously-skip-permissions --output-format stream-json --verbose
  78. ```
  79. On Intel Homebrew the path is normally `/usr/local/bin/fya`. If `command -v fya` prints another path, use that exact path instead.
  80. For `agentrun`, use its tmux-backed path if the goal is avoiding direct `claude --print`:
  81. ```ini
  82. claude_command = /absolute/path/to/agentrun
  83. claude_args = --persist-session --no-session-persistence --dangerously-skip-permissions --output-format stream-json --verbose
  84. ```
  85. These tools depend on interactive Claude Code behavior and local transcript files staying usable. Anthropic may detect or block wrapper-style automation later, so test the exact tool before relying on it.
  86. </details>
  87. ## How It Works
  88. ralphex executes plans in four phases with automated code reviews, plus an optional finalize step.
  89. <details markdown>
  90. <summary>Execution Flow Diagram</summary>
  91. ![ralphex flow](assets/ralphex-flow.png)
  92. </details>
  93. ### Phase 1: Task Execution
  94. 1. Reads plan file and finds first incomplete task (`### Task N:` with `- [ ]` checkboxes)
  95. 2. Sends task to Claude Code for execution
  96. 3. Runs validation commands (tests, linters) after each task
  97. 4. Marks checkboxes as done `[x]`, commits changes
  98. 5. Repeats until all tasks complete or max iterations reached
  99. **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.
  100. ### Phase 2: First Code Review
  101. Launches 5 review agents **in parallel** via Claude Code Task tool:
  102. | Agent | Purpose |
  103. |-------|---------|
  104. | `quality` | bugs, security issues, race conditions |
  105. | `implementation` | verifies code achieves stated goals |
  106. | `testing` | test coverage and quality |
  107. | `simplification` | detects over-engineering |
  108. | `documentation` | checks if docs need updates |
  109. Claude verifies findings, fixes confirmed issues, and commits.
  110. *[Default agents](https://github.com/umputun/ralphex/tree/master/pkg/config/defaults/agents) provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See [Customization](#customization) for details.*
  111. ### Phase 3: External Review (optional)
  112. 1. Runs external review tool (codex by default, or custom script)
  113. 2. Claude evaluates findings, fixes valid issues
  114. 3. Iterates until no open issues
  115. The loop terminates when: all issues resolved, max iterations reached, stalemate detected (via `--review-patience`), or manual break via Ctrl+\ (SIGQUIT).
  116. **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.
  117. **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.
  118. Supported tools:
  119. - **codex** (default): OpenAI Codex for independent code review
  120. - **custom**: Your own script wrapping any AI (OpenRouter, local LLM, etc.)
  121. - **none**: Skip external review entirely
  122. See [Custom External Review](#custom-external-review) for details on using custom scripts.
  123. ### Phase 4: Second Code Review
  124. 1. Launches 2 agents (`quality` + `implementation`) for final review
  125. 2. Focuses on critical/major issues only
  126. 3. Iterates until no issues found
  127. 4. Moves plan to `completed/` folder on success (on the feature branch under `--worktree`)
  128. *Second review agents are configurable via `prompts/review_second.txt`.*
  129. ### Finalize Step (optional)
  130. After all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.
  131. **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.
  132. **How to enable:**
  133. Set `finalize_enabled = true` in `~/.config/ralphex/config` or `.ralphex/config`.
  134. **Behavior:**
  135. - Runs once (no iteration loop)
  136. - Best-effort — failures are logged but don't block success
  137. - Triggers on modes with review pipeline: full, review-only, external-only
  138. - Uses task color (green) for output
  139. **Customization:**
  140. Edit `~/.config/ralphex/prompts/finalize.txt` (or `.ralphex/prompts/finalize.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.
  141. ### Plan Move Behavior (optional)
  142. After successful execution, ralphex moves the plan file into `docs/plans/completed/`. Enabled by default.
  143. Under `--worktree` the archive is committed on the feature branch, alongside the ticked plan. The copy in your main checkout is left exactly as it was — for a plan you never committed, it stays there unticked even after the branch merges. Delete it yourself if you don't want it.
  144. **How to disable:**
  145. Set `move_plan_on_completion = false` in `~/.config/ralphex/config` or `.ralphex/config`. Default is `true`.
  146. **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.
  147. ### Review-Only Mode
  148. Review-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.
  149. **Workflow:**
  150. 1. Make changes on a feature branch (using any tool or workflow)
  151. 2. Commit the changes
  152. 3. Run `ralphex --review`
  153. ralphex compares the branch against the default branch (`git diff master...HEAD`), launches multi-agent reviews, and iterates fixes until all agents report clean, an iteration makes no commit, or the review iteration limit is reached. No plan file is required — if provided, it gives reviewers additional context about the intended changes.
  154. ```bash
  155. # switch to feature branch with existing changes
  156. git checkout feature-auth
  157. # run review pipeline on those changes
  158. ralphex --review
  159. # optionally pass a plan file for context
  160. ralphex --review docs/plans/add-auth.md
  161. ```
  162. ### External-Only Mode
  163. External-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/major review (Phase 4) runs to catch regressions from fixes applied during the loop.
  164. If the external review loop finds no issues on its first pass, Phase 4 is skipped automatically because there is nothing to regress.
  165. ```bash
  166. # run external review pipeline on current branch changes
  167. ralphex --external-only
  168. # optionally pass a plan file for context
  169. ralphex --external-only docs/plans/feature.md
  170. ```
  171. ### Codex Executor Mode
  172. The `--codex` flag routes interactive plan creation (`--plan`), task execution, both review phases, and the optional finalize step through the codex CLI instead of Claude Code. The external review phase is automatically skipped because codex-reviewing-codex is a same-model self-review with weak signal; the cross-model independence between Claude and codex was the original reason that phase existed.
  173. **Why this exists:** in June 2026 Anthropic split the Claude Max subscription from the Claude Agent SDK, putting unattended ralphex runs on a separate $200 credit pool rather than the Max plan. Users with an OpenAI/codex plan can switch the entire ralphex pipeline to codex with one flag and stay on their existing OpenAI subscription instead.
  174. ```bash
  175. # create a plan through codex
  176. ralphex --codex --plan "add user authentication"
  177. # run the full pipeline (task, first review, second review, finalize) through codex
  178. ralphex --codex docs/plans/feature.md
  179. # additionally let codex read project CLAUDE.md as AGENTS.md
  180. ralphex --codex --pass-claude-md docs/plans/feature.md
  181. ```
  182. **How it differs from `codex-as-claude.sh`:** the `--codex` flag is the native codex path. It calls the codex CLI directly and configures multi-agent reviews through additive `-c` flag overrides on the codex command line. Review prompts are shared with claude. The `{{agent:<name>}}` expansion produces `spawn_agent` calls for codex and Task-tool calls for claude at runtime. The `scripts/codex-as-claude/codex-as-claude.sh` wrapper still exists for backwards compatibility. It translates codex JSONL output into Claude stream-json events, which adds overhead and keeps Claude-flavored prompt vocabulary in front of a codex model.
  183. **Project CLAUDE.md passthrough (`--pass-claude-md`):** adds `-c project_doc_fallback_filenames=["CLAUDE.md"]` to the codex invocation so codex's native AGENTS.md walk picks up the project-level `./CLAUDE.md` file. This works for project-level CLAUDE.md only. For user-level `~/.claude/CLAUDE.md`, ralphex never modifies the user's `~/.codex/` directory. 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` and continues; the user opts in by running the command themselves.
  184. **Configuration alternative:** instead of passing `--codex` every run, set it in `~/.config/ralphex/config` or `.ralphex/config`:
  185. ```ini
  186. executor = codex
  187. pass_claude_md = true
  188. ```
  189. When `executor = codex` is set in config and the user has also set `external_review_tool = codex` (or `custom`), ralphex automatically overrides `external_review_tool` to `none` and prints a warning to stderr that the config-file value was overridden. Only CLI-flag conflicts are hard errors; config-only conflicts resolve with a warning.
  190. **Mutual exclusion:** the codex executor (whether enabled via `--codex` or `executor = codex` in config) cannot be combined with `--external-only` (alias `-e`), `--codex-only` (alias `-c`), or `--external-review-tool=<X>` where `<X>` is not `none`. `--pass-claude-md` requires the codex executor (CLI `--codex` or config `executor = codex`). Each combination fails with a clear error message at startup.
  191. **Requirements:** `--codex` requires the codex CLI version 0.130.0 or newer. The mode relies on `[features] multi_agent`, `[agents.<name>]` agent registration, and (with `--pass-claude-md`) `project_doc_fallback_filenames`, all supported in 0.130.0. Older codex versions silently ignore unknown `-c` overrides, so a misconfigured run will not error visibly. It will simply behave as if the overrides were absent. There is no runtime version check; verify your codex version with `codex --version` if behavior is unexpected.
  192. **Model selection under `--codex`:** under `--codex` the `--plan-model` / `--task-model` / `--review-model` flags (and their config equivalents `plan_model` / `task_model` / `review_model`) select the model and effort per phase. `--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 resolved review model/effort differs from task, so tasks and reviews can run on different codex models. Each `model[:effort]` spec is resolved against `codex_model` / `codex_reasoning_effort` (default `gpt-5.6-sol` / `high`): an unset spec inherits those defaults, and each populated half overrides its default (`--task-model=:low` changes effort only). The `max` effort level is claude-only. A spec requesting it under `--codex` is warned about and ignored. So codex model selection is: `--plan-model` / `--task-model` / `--review-model` (CLI or config), then `codex_model` / `codex_reasoning_effort` in ralphex config, applied as `-c` overrides to the codex CLI; set either codex value to empty (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. The startup banner under `--codex` shows the resolved plan/task model/effort for the current mode, plus a separate `review model` / `review reasoning effort` line when the review phase resolves differently.
  193. ### Worktree Isolation
  194. The `--worktree` flag runs plan execution in an isolated git worktree at `.ralphex/worktrees/<branch>`, enabling parallel execution of multiple plans on the same repo without branch conflicts.
  195. **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.
  196. **Source checkout state:** Uncommitted files in the source checkout do not have to be stashed first. Ralphex lists them in a warning and does not copy them into the generated worktree. An uncommitted selected plan is copied so it can be committed on the feature branch. A new feature branch starts at the current `HEAD`; an existing feature branch keeps its own tip. Local `.ralphex` configuration is loaded before worktree creation and still applies to the run. Commit any repository changes the plan needs before starting. An unfinished Git operation remains a hard error because completion archives the plan in the source checkout. In-place branch mode also requires a clean checkout because it creates the feature branch in that same working tree.
  197. **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:
  198. ```bash
  199. # find the worktree
  200. ls .ralphex/worktrees/
  201. # run review from inside it
  202. cd .ralphex/worktrees/my-feature-branch
  203. ralphex --review
  204. # or
  205. ralphex --external-only
  206. ```
  207. Worktrees are automatically removed on successful completion. Two cases leave one behind: an interrupted run, and a run whose plan archive did not complete — the worktree is kept so anything the archive staged can be recovered. The run still reports success and names the retained worktree; inspect it with `git -C <path> status` and run `git worktree remove <path>` before running that plan again, or the next run refuses with `worktree already exists`.
  208. ### Plan Creation
  209. Plans can be created in several ways:
  210. - **[Claude Code](#claude-code-integration-optional)** - use slash commands like `/ralphex-plan` or your own planning workflows
  211. - **Manually** - write markdown files directly in `docs/plans/`
  212. - **`--plan` flag** - integrated option that handles the entire flow
  213. - **Auto-detection** - running `ralphex` without arguments on master/main prompts for plan creation if no plans exist
  214. The `--plan` flag provides a simpler integrated experience:
  215. ```bash
  216. ralphex --plan "add health check endpoint"
  217. ```
  218. Claude explores your codebase, asks clarifying questions via a terminal picker (fzf or numbered fallback), and generates a complete plan file in `docs/plans/`. When reviewing the draft, you can accept, revise with text feedback, open it in `$EDITOR` for interactive annotation, or reject it.
  219. **Example session:**
  220. ```
  221. $ ralphex --plan "add caching for API responses"
  222. [10:30:05] analyzing codebase structure...
  223. [10:30:12] found existing store layer in pkg/store/
  224. QUESTION: Which cache backend?
  225. > Redis
  226. In-memory
  227. File-based
  228. Other (type your own answer)
  229. [10:30:45] ANSWER: Redis
  230. [10:31:00] continuing plan creation...
  231. [10:32:05] plan written to docs/plans/add-api-caching.md
  232. Continue with plan implementation?
  233. > Yes, execute plan
  234. No, exit
  235. ```
  236. After plan creation, you can choose to continue with immediate execution or exit to run ralphex later. Progress is logged to `.ralphex/progress/progress-plan-<name>.txt`.
  237. ## Installation
  238. ### From source
  239. ```bash
  240. go install github.com/umputun/ralphex/cmd/ralphex@latest
  241. ```
  242. ### Using Homebrew
  243. ```bash
  244. brew install umputun/apps/ralphex
  245. ```
  246. ### From releases
  247. Download the appropriate binary from [releases](https://github.com/umputun/ralphex/releases).
  248. ### Using Docker
  249. Download the wrapper script and install to PATH:
  250. ```bash
  251. curl -sL https://raw.githubusercontent.com/umputun/ralphex/master/scripts/ralphex-dk.sh -o /usr/local/bin/ralphex
  252. chmod +x /usr/local/bin/ralphex
  253. ```
  254. The 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:
  255. ```bash
  256. export RALPHEX_IMAGE=my-ralphex
  257. ```
  258. Then 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.
  259. **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.
  260. <details markdown>
  261. <summary>Isolation details</summary>
  262. **Container CAN access (read-write):**
  263. - Project directory mounted at `/workspace` - full access to create, modify, delete files
  264. - Git operations within the project (branch, commit, etc.)
  265. - `~/.claude/.credentials.json` and `~/.codex/auth.json` - bind-mounted individually into the container's home so OAuth token refreshes persist back to the host instead of being lost when the container exits. Claude credentials kept only in the macOS keychain are copied instead, see "Claude login in the macOS keychain" below
  266. **Container CAN access (read-only):**
  267. - `~/.claude/` - settings, commands, skills, and agents (copied into the container at startup)
  268. - `~/.codex/` - codex config if present
  269. - `~/.config/ralphex/` - user-level ralphex configuration
  270. - `~/.gitconfig` - git identity for commits
  271. - Global gitignore (`core.excludesFile`) - auto-detected and mounted
  272. - `.ralphex/` - project-level configuration if present
  273. **Container CANNOT access:**
  274. - Host filesystem outside mounted directories
  275. - Other projects or repositories
  276. - SSH keys, AWS credentials, or other secrets in `~/.ssh`, `~/.aws`, etc.
  277. - System files, binaries, or configurations
  278. - Other running processes or containers
  279. **Network:** Full network access (required for Claude API calls)
  280. **Privileges:** Runs as non-root user with no elevated capabilities
  281. </details>
  282. **Volume mounts:**
  283. - **Read-only**: `~/.claude` and `~/.codex` mounted to `/mnt/`, copied at startup to preserve isolation (the two credential files below are bind-mounted separately instead of copied)
  284. - **Read-write (single-file)**: `~/.claude/.credentials.json` and `~/.codex/auth.json` bind-mounted to the matching paths under the container's home, so refreshed OAuth tokens are written back to the host. Only when the file exists on the host; macOS keychain credentials are mounted read-only and copied
  285. - **Read-write**: project directory (`/workspace`) - where ralphex creates branches, edits code, and commits
  286. - **Extra mounts**: user-defined volumes via `-v`/`--volume` flags or `RALPHEX_EXTRA_VOLUMES` env var
  287. **Requirements:**
  288. - Python 3.9+ (for the wrapper script)
  289. - Docker installed and running
  290. - Claude Code credentials in `~/.claude/` (or in `$CLAUDE_CONFIG_DIR` when set)
  291. - Codex credentials in `~/.codex/` (optional, for codex review phase)
  292. - Git config in `~/.gitconfig` (for commits)
  293. **Environment variables:**
  294. - `RALPHEX_IMAGE` - Docker image to use (default: `ghcr.io/umputun/ralphex-go:latest`). CLI flag: `--image`
  295. - `RALPHEX_PORT` - Port for web dashboard when using `--serve` (default: `8080`). CLI flag: `--port`
  296. - `RALPHEX_CONFIG_DIR` - Custom config directory (default: `~/.config/ralphex`). Overrides global config location for prompts, agents, and settings
  297. - `CLAUDE_CONFIG_DIR` - Claude config directory (default: `~/.claude`). Use for alternate Claude installations (e.g., `~/.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.
  298. - `RALPHEX_EXTRA_VOLUMES` - Extra volume mounts, comma-separated (e.g., `/data:/mnt/data:ro,/models:/mnt/models`). Entries without `:` are silently skipped
  299. - `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
  300. - `RALPHEX_DOCKER_SOCKET` - Enable Docker socket mount: `1`, `true`, or `yes` (Docker wrapper only). CLI flag: `--docker`
  301. - `RALPHEX_DOCKER_NETWORK` - Docker network mode (e.g., `host`, `my-network`). Useful for reaching docker-compose services. CLI flag: `--network`
  302. - `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`
  303. - `TZ` - Override container timezone (default: auto-detected from host via `/etc/localtime`). Example: `TZ=Europe/Berlin ralphex docs/plans/feature.md`
  304. - `RALPHEX_CLAUDE_PROVIDER` - Claude provider mode: `default` or `bedrock` (Docker wrapper only)
  305. **CLI freshness in the container:**
  306. 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 help here, since npm installs it root-owned and the container runs as the `app` user.
  307. Setting `RALPHEX_CLI_UPDATE=1` refreshes both CLIs to their current npm releases on start, before dropping privileges. It usually adds 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 says so rather than failing later without explanation.
  308. The base `ralphex` image leaves this **off** so anyone building on it gets no surprise npm install, network call, or version drift at container start. The `ralphex-go` image (the wrapper's default) bakes it **on**, so the common path stays current. Enable it yourself for a single run:
  309. ```bash
  310. RALPHEX_CLI_UPDATE=1 ralphex docs/plans/feature.md
  311. ```
  312. Or bake it into a custom image so every run refreshes:
  313. ```dockerfile
  314. FROM ghcr.io/umputun/ralphex:latest
  315. ENV RALPHEX_CLI_UPDATE=1
  316. ```
  317. **Claude login in the macOS keychain:**
  318. On macOS, Claude Code often keeps its login in the keychain rather than in `~/.claude/.credentials.json`. The wrapper mounts an extracted keychain entry read-only, then copies it into the container's writable home. Refreshed credentials stay inside the container and are not written back to the keychain. Refresh tokens rotate, so the next run, or Claude Code on the host, can find the stored refresh token already used and require signing in again. Codex is not affected: `~/.codex/auth.json` is a file on disk and refreshes are written through to it.
  319. To use a long-lived token instead of the copied login credentials, generate one on the host and pass it by name:
  320. ```bash
  321. claude setup-token # prints a one-year OAuth token (Pro, Max, Team or Enterprise plan)
  322. export CLAUDE_CODE_OAUTH_TOKEN=<token>
  323. ralphex -E CLAUDE_CODE_OAUTH_TOKEN docs/plans/feature.md
  324. ```
  325. Claude Code prefers this token over stored login credentials. The name-only `-E` form (or `RALPHEX_EXTRA_ENV=CLAUDE_CODE_OAUTH_TOKEN`) inherits the value from the host environment, so it never appears on the docker command line. The wrapper still requires a regular Claude login on the host (keychain or `~/.claude/.credentials.json`) before it starts, so the token adds to that login and does not replace it.
  326. **Docker socket support:**
  327. The `--docker` flag (or `RALPHEX_DOCKER_SOCKET=1`) mounts the host Docker socket into the container, enabling testcontainers and Docker-dependent workflows:
  328. ```bash
  329. ralphex --docker docs/plans/feature.md
  330. ralphex --docker --dry-run # verify socket mount in command
  331. ```
  332. - Auto-detects socket GID and passes `DOCKER_GID` env var for baseimage group setup
  333. - Emits security warning on Linux (macOS has VM isolation, no warning needed)
  334. - Exits with error if socket file doesn't exist (fail-fast, no silent degradation)
  335. **AWS Bedrock support:**
  336. When `--claude-provider=bedrock` or `RALPHEX_CLAUDE_PROVIDER=bedrock` is set:
  337. - Keychain credential extraction is skipped (not needed for Bedrock auth)
  338. - AWS credentials are automatically exported from `AWS_PROFILE` via `aws configure export-credentials`
  339. - Required Bedrock env vars are passed to container: `CLAUDE_CODE_USE_BEDROCK`, `AWS_REGION`, credentials
  340. Required environment for Bedrock:
  341. - `AWS_REGION` - AWS region where Bedrock is enabled
  342. - `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` - authentication
  343. Note: `CLAUDE_CODE_USE_BEDROCK=1` is automatically set when using `--claude-provider=bedrock`.
  344. ```bash
  345. # with AWS profile (credentials exported automatically)
  346. export AWS_PROFILE=my-bedrock-profile
  347. export AWS_REGION=us-east-1
  348. ralphex --claude-provider=bedrock docs/plans/feature.md
  349. # or use env var for session-wide setting
  350. export RALPHEX_CLAUDE_PROVIDER=bedrock
  351. ralphex docs/plans/feature.md
  352. ```
  353. See [Bedrock setup documentation](docs/bedrock-setup.md) for detailed IAM policies and setup instructions.
  354. **Extra volume mounts:**
  355. ```bash
  356. # via CLI flags (can use multiple -v)
  357. ralphex -v /data:/mnt/data:ro -v /models:/mnt/models docs/plans/feature.md
  358. # via environment variable (comma-separated)
  359. RALPHEX_EXTRA_VOLUMES="/data:/mnt/data:ro,/models:/mnt/models" ralphex docs/plans/feature.md
  360. ```
  361. **Extra environment variables:**
  362. ```bash
  363. # via CLI flags (can use multiple -E)
  364. ralphex -E DEBUG=1 -E API_KEY docs/plans/feature.md
  365. # via environment variable (comma-separated)
  366. RALPHEX_EXTRA_ENV="DEBUG=1,LOG_LEVEL=verbose" ralphex docs/plans/feature.md
  367. # name-only form inherits value from host (recommended for secrets)
  368. export API_KEY=secret123
  369. ralphex -E API_KEY docs/plans/feature.md
  370. # values containing commas require -E flag (env var splits on commas)
  371. ralphex -E "TAGS=foo,bar,baz" docs/plans/feature.md
  372. ```
  373. **Debugging:**
  374. ```bash
  375. ralphex --dry-run docs/plans/feature.md # show docker command without executing
  376. ```
  377. The `--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.
  378. Note: inherited env vars (`-E FOO` without `=value`) won't work when copying the command to a different shell. Use explicit values for portability.
  379. **Updating:**
  380. ```bash
  381. ralphex --update # pull latest docker image
  382. ralphex --update-script # update the wrapper script itself
  383. ```
  384. <a id="available-images"></a>
  385. <details markdown>
  386. <summary>Available images</summary>
  387. Two images are published:
  388. | Image | Description |
  389. |-------|-------------|
  390. | `ghcr.io/umputun/ralphex:latest` | Base image with Claude Code, Codex, and core tools |
  391. | `ghcr.io/umputun/ralphex-go:latest` | Go development (extends base with Go toolchain) |
  392. **Base image includes:**
  393. | Tool | Version | Purpose |
  394. |------|---------|---------|
  395. | Claude Code | latest | AI coding assistant |
  396. | Codex | latest | External code review |
  397. | fya | latest | Optional claude print-mode wrapper (PTY-backed) |
  398. | Node.js/npm | 24.x | Required for Claude Code |
  399. | Python/pip | 3.x | Scripts and automation |
  400. | git | 2.x | Version control |
  401. | docker-cli | - | Docker client for container workflows |
  402. | make | 4.x | Build automation |
  403. | gcc, musl-dev | - | C compiler for native extensions |
  404. | bash | 5.x | Shell |
  405. | fzf | - | Fuzzy finder for plan selection |
  406. | ripgrep | - | Fast search (used by Claude Code) |
  407. **Go image adds:**
  408. | Tool | Version | Purpose |
  409. |------|---------|---------|
  410. | Go | 1.26.0 | Go compiler and runtime |
  411. | golangci-lint | latest | Go linter |
  412. | moq | latest | Mock generator |
  413. | goimports | latest | Import formatter |
  414. **For Go projects**, use the `-go` image:
  415. ```bash
  416. RALPHEX_IMAGE=ghcr.io/umputun/ralphex-go:latest ralphex docs/plans/feature.md
  417. ```
  418. **For other languages**, create a custom image by extending the base with your language toolchain. The Go image (`Dockerfile-go`) shows the pattern:
  419. ```dockerfile
  420. FROM ghcr.io/umputun/ralphex:latest
  421. # install go from official distribution
  422. ARG GO_VERSION=1.26.0
  423. RUN ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') && \
  424. wget -qO- "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" | tar -xz -C /usr/local
  425. ENV GOROOT=/usr/local/go
  426. ENV GOPATH=/home/app/go
  427. ENV PATH="${PATH}:${GOROOT}/bin:${GOPATH}/bin"
  428. # install go tools
  429. RUN wget -qO- https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin && \
  430. GOBIN=/usr/local/bin go install github.com/matryer/moq@latest && \
  431. GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest
  432. ```
  433. Same approach for Rust, Java, or any other language:
  434. ```dockerfile
  435. FROM ghcr.io/umputun/ralphex:latest
  436. # rust
  437. RUN apk add --no-cache rust cargo
  438. ENV CARGO_HOME=/home/app/.cargo PATH="${PATH}:${CARGO_HOME}/bin"
  439. # java
  440. RUN apk add --no-cache openjdk21-jdk
  441. ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk PATH="${PATH}:${JAVA_HOME}/bin"
  442. ```
  443. Add `ENV RALPHEX_CLI_UPDATE=1` to your image if you want it to refresh claude/codex to the latest npm release on every container start, the way `ralphex-go` does. The base image leaves it off.
  444. Build and use:
  445. ```bash
  446. docker build -t my-ralphex -f Dockerfile.python .
  447. RALPHEX_IMAGE=my-ralphex ralphex docs/plans/feature.md
  448. ```
  449. </details>
  450. Example with custom port:
  451. ```bash
  452. RALPHEX_PORT=3000 ralphex --serve --port=3000 docs/plans/feature.md
  453. ```
  454. ## Usage
  455. **Note:** ralphex must be run from the repository root directory (where `.git` is located).
  456. ```bash
  457. # execute plan with task loop + reviews
  458. ralphex docs/plans/feature.md
  459. # select plan with fzf, or create one interactively if none exist
  460. ralphex
  461. # review-only mode (skip task execution)
  462. ralphex --review docs/plans/feature.md
  463. # external-only mode (skip tasks and first review, run only external review loop)
  464. ralphex --external-only
  465. # codex executor mode (run task, review, and finalize phases through codex; skip external review)
  466. ralphex --codex docs/plans/feature.md
  467. # codex executor mode with project CLAUDE.md passthrough (codex reads CLAUDE.md as AGENTS.md)
  468. ralphex --codex --pass-claude-md docs/plans/feature.md
  469. # tasks-only mode (run only task phase, skip all reviews)
  470. ralphex --tasks-only docs/plans/feature.md
  471. # run in isolated git worktree (full and tasks-only modes only)
  472. ralphex --worktree docs/plans/feature.md
  473. # override default branch for review diffs
  474. ralphex --review --base-ref develop
  475. ralphex --review --base-ref abc1234 --skip-finalize
  476. # initialize local .ralphex/ config in current project (commented-out defaults)
  477. ralphex --init
  478. # interactive plan creation
  479. ralphex --plan "add user authentication"
  480. # with custom max iterations
  481. ralphex --max-iterations=100 docs/plans/feature.md
  482. # limit external review iterations (0 = auto, derived from max-iterations)
  483. ralphex --max-external-iterations=5 docs/plans/feature.md
  484. # terminate external review after 3 unchanged rounds (stalemate detection)
  485. ralphex --review-patience=3 docs/plans/feature.md
  486. # wait and retry on rate limit (instead of exiting)
  487. ralphex --wait=1h docs/plans/feature.md
  488. # use a stronger model for plan creation
  489. ralphex --plan-model=fable:high --plan="add caching"
  490. # use different models for tasks and reviews
  491. ralphex --task-model=opus --review-model=sonnet:low docs/plans/feature.md
  492. # use provider overrides for one run without editing config
  493. ralphex --claude-command=/path/to/codex-as-claude.sh --external-review-tool=custom --custom-review-script=/path/to/review.sh docs/plans/feature.md
  494. # set per-session timeout to kill hanging sessions (external review in Claude mode excluded)
  495. ralphex --session-timeout=30m docs/plans/feature.md
  496. # kill claude/codex executor session when no output for 5 minutes
  497. ralphex --idle-timeout=5m docs/plans/feature.md
  498. # preserve ANTHROPIC_API_KEY in the claude child env (for API-key auth users)
  499. ralphex --preserve-anthropic-api-key docs/plans/feature.md
  500. # with web dashboard
  501. ralphex --serve docs/plans/feature.md
  502. # web dashboard on custom port
  503. ralphex --serve --port=3000 docs/plans/feature.md
  504. ```
  505. ### Options
  506. | Flag | Description | Default |
  507. |------|-------------|---------|
  508. | `-m, --max-iterations` | Maximum task iterations | 50 |
  509. | `--max-external-iterations` | Override external review iteration limit (0 = auto) | 0 |
  510. | `--review-patience` | Terminate external review after N unchanged rounds (0 = disabled) | 0 |
  511. | `-r, --review` | Skip task execution, run full review pipeline | false |
  512. | `-e, --external-only` | Skip tasks and first review, run only external review loop | false |
  513. | `-c, --codex-only` | Alias for `--external-only` (deprecated) | false |
  514. | `--codex` | Use codex CLI as the executor for plan creation, task, review, and finalize phases. Skips the external review phase (codex-reviewing-codex is a same-model self-review with weak signal). Requires codex CLI ≥ 0.130.0 | false |
  515. | `--pass-claude-md` | Pass project `CLAUDE.md` to codex via `-c project_doc_fallback_filenames=["CLAUDE.md"]`. User-level `~/.claude/CLAUDE.md` is NOT auto-passed (a one-time setup hint is shown). Requires the codex executor (`--codex` or `executor = codex`) | false |
  516. | `-t, --tasks-only` | Run only task phase, skip all reviews | false |
  517. | `-b, --base-ref` | Override default branch for review diffs (branch name or commit hash) | auto-detect |
  518. | `--skip-finalize` | Skip finalize step even if enabled in config | false |
  519. | `--plan-model` | Model for plan creation as `model[:effort]` (falls back to `--task-model`). Same syntax and wrapper behavior as `--task-model`. Under `--codex`, selects the codex plan-creation model/effort | empty |
  520. | `--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 <m>` and/or `--effort <e>` to `claude_command`; custom wrappers may ignore or implement the flags. Under `--codex`, selects the codex task-phase model/effort instead (see *Model selection under `--codex`*) | empty |
  521. | `--review-model` | Model for review phases as `model[:effort]` (falls back to `--task-model`). Same syntax and wrapper behavior as `--task-model`. Under `--codex`, selects the codex review-phase model/effort | empty |
  522. | `--claude-command` | Override the Claude-compatible command for this run | config/default |
  523. | `--claude-args` | Override Claude-compatible command arguments for this run. Use `--claude-args=` to clear configured/default args | config/default |
  524. | `--external-review-tool` | Override external review tool for this run (`codex`, `custom`, or `none`) | config/default |
  525. | `--custom-review-script` | Override custom external review script for this run | config/default |
  526. | `--wait` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |
  527. | `--session-timeout` | Per-session timeout for task/review executor (e.g., `30m`, `1h`). Applies to Claude calls in default executor mode and every executor call under `--codex`; external codex/custom review in Claude mode is not affected | disabled |
  528. | `--idle-timeout` | Kill executor session when no output for specified duration (e.g., `5m`). Resets on each output line. Applies to the claude executor in default mode and to every executor call under `--codex`; external codex review in default-claude mode is NOT affected (preserves master behavior). Custom review is also not affected | disabled |
  529. | `--worktree` | Run in isolated git worktree (full and tasks-only modes only) | false |
  530. | `--preserve-anthropic-api-key` | Pass `ANTHROPIC_API_KEY` through to claude (for users authenticating Claude Code via API key rather than OAuth/keychain) | false |
  531. | `--plan` | Create plan interactively (provide description) | - |
  532. | `-s, --serve` | Start web dashboard for real-time streaming | false |
  533. | `-p, --port` | Web dashboard port (used with `--serve`) | 8080 |
  534. | `-w, --watch` | Directories to watch for progress files (repeatable) | - |
  535. | `-d, --debug` | Enable debug logging | false |
  536. | `--no-color` | Disable color output | false |
  537. | `--init` | Initialize local `.ralphex/` config in current project | - |
  538. | `--reset` | Interactively reset global config to embedded defaults | - |
  539. | `--dump-defaults` | Extract raw embedded defaults to specified directory | - |
  540. | `--config-dir` | Custom config directory (env: `RALPHEX_CONFIG_DIR`) | `~/.config/ralphex` |
  541. ## Plan File Format
  542. Plans are markdown files with task sections. Each task has checkboxes that claude marks complete.
  543. ```markdown
  544. # Plan: Add User Authentication
  545. ## Overview
  546. Add JWT-based authentication to the API.
  547. ## Validation Commands
  548. - `go test ./...`
  549. - `golangci-lint run`
  550. ### Task 1: Add auth middleware
  551. - [ ] Create JWT validation middleware
  552. - [ ] Add to router for protected routes
  553. - [ ] Add tests
  554. - [ ] Mark completed
  555. ### Task 2: Add login endpoint
  556. - [ ] Create /api/login handler
  557. - [ ] Return JWT on successful auth
  558. - [ ] Add tests
  559. - [ ] Mark completed
  560. ```
  561. **Requirements:**
  562. - Task headers must use `### Task N:` or `### Iteration N:` format (N can be integer or non-integer like `2.5`, `2a`)
  563. - Checkboxes: `- [ ]` (incomplete) or `- [x]` (completed)
  564. - 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.
  565. - Include `## Validation Commands` section with test/lint commands
  566. - Place plans in `docs/plans/` directory (configurable via `plans_dir`)
  567. ## Review Agents
  568. The 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.
  569. ### Default Agents
  570. These 5 agents cover common review concerns and work well out of the box. Customize or replace them based on your needs:
  571. | Agent | Phase | Purpose |
  572. |-------|-------|---------|
  573. | `quality` | 1st & 2nd | bugs, security issues, race conditions |
  574. | `implementation` | 1st & 2nd | verifies code achieves stated goals |
  575. | `testing` | 1st only | test coverage and quality |
  576. | `simplification` | 1st only | detects over-engineering |
  577. | `documentation` | 1st only | checks if docs need updates |
  578. ### Agent Options (Frontmatter)
  579. Agent files support optional YAML frontmatter for per-agent configuration:
  580. ```txt
  581. ---
  582. model: haiku
  583. agent: code-reviewer
  584. ---
  585. Review the code for quality issues...
  586. ```
  587. | Option | Values | Description |
  588. |--------|--------|-------------|
  589. | `model` | `haiku`, `sonnet`, `opus`, `fable` | Claude model for this agent |
  590. | `agent` | any string | Claude Code Task tool subagent type |
  591. Both 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`, `fable`. Invalid model values are dropped with a warning.
  592. ### Template Syntax
  593. Custom prompt files support variable expansion. All variables use the `{{VARIABLE}}` syntax.
  594. **Available variables:**
  595. | Variable | Description | Example value |
  596. |----------|-------------|---------------|
  597. | `{{PLAN_FILE}}` | Path to the plan file being executed | `docs/plans/feature.md` |
  598. | `{{PROGRESS_FILE}}` | Path to the progress log file | `.ralphex/progress/progress-feature.txt` |
  599. | `{{GOAL}}` | Human-readable goal description | `implementation of plan at docs/plans/feature.md` |
  600. | `{{DEFAULT_BRANCH}}` | Default branch name (overridable via `--base-ref` or `default_branch` config) | `main`, `master`, `origin/main` |
  601. | `{{agent:name}}` | Expands to Task tool instructions for the named agent | (see below) |
  602. **Agent references:**
  603. Reference agents in prompt files using `{{agent:name}}` syntax:
  604. ```
  605. Launch the following review agents in parallel:
  606. {{agent:quality}}
  607. {{agent:implementation}}
  608. {{agent:testing}}
  609. ```
  610. Each `{{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.
  611. ### Customization
  612. The entire system is designed for customization - both task execution and reviews:
  613. **Agent files** (`~/.config/ralphex/agents/`):
  614. - 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
  615. - Per-file fallback: for each agent, ralphex checks local `.ralphex/agents/` → global `~/.config/ralphex/agents/` → 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
  616. - 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
  617. - Add new `.txt` files to create custom agents (reference them in prompts with `{{agent:name}}`)
  618. - Run `ralphex --init` to create local `.ralphex/` project config with commented-out defaults
  619. - Run `ralphex --reset` to interactively restore defaults, or delete all files manually
  620. - Run `ralphex --dump-defaults <dir>` to extract raw defaults for comparison
  621. - Use the `/ralphex-update` Claude Code skill to smart-merge updated defaults into customized files
  622. - Alternatively, reference agents already installed in your Claude Code directly in prompt files (see example below)
  623. **Prompt files** (`~/.config/ralphex/prompts/`):
  624. - `task.txt` - task execution prompt
  625. - `review_first.txt` - comprehensive review (default: 5 language-agnostic agents - quality, implementation, testing, simplification, documentation; customizable)
  626. - `codex.txt` - codex evaluation prompt (Claude evaluates codex output)
  627. - `codex_review.txt` - codex review prompt (sent to codex external review tool)
  628. - `custom_review.txt` - custom external review prompt (sent to custom review script)
  629. - `custom_eval.txt` - custom evaluation prompt (Claude evaluates custom tool output)
  630. - `review_second.txt` - final review, critical/major issues only (default: 2 agents - quality, implementation; customizable)
  631. - `make_plan.txt` - interactive plan creation prompt
  632. - `finalize.txt` - optional finalize step prompt (disabled by default)
  633. **Comment lines and markdown headers:**
  634. A 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:
  635. ```txt
  636. # This single title line is preserved as a markdown header
  637. check for SQL injection
  638. # this mid-body comment is also preserved
  639. check for XSS
  640. ```
  641. Files 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.
  642. Note: Inline comments are not supported (`text # comment` keeps the entire line).
  643. **Examples:**
  644. - Add a security-focused agent for fintech projects
  645. - Remove `{{agent:simplification}}` from prompt files if over-engineering isn't a concern
  646. - Create language-specific agents (Python linting, TypeScript types)
  647. - Modify prompts to change how many agents run per phase
  648. **Using Claude Code agents directly:**
  649. Instead of creating agent files, you can reference agents installed in your Claude Code directly in prompt files:
  650. ```txt
  651. # in review_first.txt - just list agent names with their prompts
  652. Agents to launch:
  653. 1. qa-expert - "Review for bugs and security issues"
  654. 2. go-test-expert - "Review test coverage and quality"
  655. 3. go-smells-expert - "Review for code smells"
  656. ```
  657. ## Requirements
  658. - `claude` - Claude Code CLI
  659. - `fzf` - for plan selection (optional)
  660. - `codex` - for external review (optional)
  661. - `gemini` - alternative provider for Claude phases (optional, via `scripts/gemini-as-claude/`)
  662. - `agy` - Antigravity CLI, alternative provider for Claude phases (optional, via `scripts/agy-as-claude/`)
  663. - `pi` - alternative provider for Claude phases (optional, via `scripts/pi-as-claude/`)
  664. ## Platform Support
  665. 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.
  666. Features missing on Windows:
  667. - the Ctrl+\ break (SIGQUIT) for pausing a task phase or terminating external review
  668. - file-lock-based active session detection, used by the web dashboard
  669. - cleanup of descendant processes on cancellation, since process group signals are unavailable
  670. 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.
  671. ## Configuration
  672. ralphex uses a configuration directory at `~/.config/ralphex/` (override with `--config-dir` or `RALPHEX_CONFIG_DIR`) with the following structure:
  673. ```
  674. ~/.config/ralphex/
  675. ├── config # main configuration file (INI format)
  676. ├── prompts/ # custom prompt templates
  677. │ ├── task.txt
  678. │ ├── review_first.txt
  679. │ ├── review_second.txt
  680. │ ├── codex.txt
  681. │ ├── codex_review.txt
  682. │ ├── custom_review.txt
  683. │ ├── custom_eval.txt
  684. │ ├── make_plan.txt
  685. │ └── finalize.txt
  686. └── agents/ # custom review agents (*.txt files)
  687. ```
  688. On first run, ralphex creates this directory with default configuration.
  689. **Commented templates:**
  690. - Config files are installed with all content commented out (`# ` prefix)
  691. - Uncomment only the settings you want to customize
  692. - Files that remain all-commented receive automatic updates with new defaults
  693. - Once you uncomment any setting, the file is preserved and won't be overwritten
  694. ### Local Project Config
  695. Projects can override global settings with a `.ralphex/` directory in the project root. Run `ralphex --init` to create it with commented-out defaults:
  696. ```
  697. project/
  698. ├── .ralphex/ # optional, project-local config
  699. │ ├── config # overrides specific settings
  700. │ ├── prompts/ # custom prompts for this project
  701. │ └── agents/ # custom agents for this project
  702. ```
  703. **Priority:** CLI flags > local `.ralphex/` > global `~/.config/ralphex/` > embedded defaults
  704. Use `--config-dir` or `RALPHEX_CONFIG_DIR` to override the global config location. This is useful for maintaining separate agent/prompt sets for different workflows.
  705. Provider-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.
  706. **Merge behavior:**
  707. - **Config file**: per-field override (local values override global, missing fields fall back)
  708. - **Prompts**: per-file fallback (local → global → embedded for each prompt file)
  709. - **Agents**: per-file fallback (local → global → embedded for each agent file, same as prompts)
  710. ### Configuration options
  711. | Option | Description | Default |
  712. |--------|-------------|---------|
  713. | `claude_command` | Claude CLI command | `claude` |
  714. | `claude_args` | Claude CLI arguments | `--dangerously-skip-permissions --output-format stream-json --verbose` |
  715. | `executor` | Executor for plan creation, task, review, and finalize phases. `""` (default) uses Claude Code; `codex` routes the full pipeline through the codex CLI and skips the external review phase. CLI flag `--codex` takes precedence | empty |
  716. | `pass_claude_md` | When `executor = codex`, pass project `CLAUDE.md` to codex as `AGENTS.md` via `-c project_doc_fallback_filenames=["CLAUDE.md"]`. CLI flag `--pass-claude-md` takes precedence | `false` |
  717. | `plan_model` | Model for plan creation as `model[:effort]` (e.g., `opus`, `opus:high`, `:medium`). Falls back to `task_model` if empty. Same syntax and wrapper behavior as `task_model`. Under `--codex`, selects the codex plan-creation model/effort instead (see *Model selection under `--codex`*) | empty |
  718. | `task_model` | Model for task execution as `model[:effort]` (e.g., `opus`, `opus:high`, `:medium`). Effort: `low`, `medium`, `high`, `xhigh`, `max`. Appended as `--model <m>` and/or `--effort <e>` to `claude_command`; custom wrappers may ignore or implement the flags. Under `--codex`, selects the codex task-phase model/effort instead (see *Model selection under `--codex`*) | empty |
  719. | `review_model` | Model for review phases as `model[:effort]`. Falls back to `task_model` if empty. Same syntax and wrapper behavior as `task_model`. Under `--codex`, selects the codex review-phase model/effort | empty |
  720. | `codex_enabled` | Enable codex review phase | `true` |
  721. | `codex_command` | Codex CLI command | `codex` |
  722. | `codex_model` | Codex model ID. Set to an empty value (`codex_model =`) in user config to inherit from `~/.codex/config.toml` instead | `gpt-5.6-sol` |
  723. | `codex_reasoning_effort` | Reasoning effort level. Set to an empty value (`codex_reasoning_effort =`) in user config to inherit from `~/.codex/config.toml` instead | `high` |
  724. | `codex_timeout_ms` | Codex timeout in ms | `3600000` |
  725. | `codex_sandbox` | Sandbox mode. External codex review defaults to `read-only`; first-class `executor = codex` uses `danger-full-access` (task/review/finalize need to write git metadata and commit) unless explicitly overridden | `read-only` (claude mode) / `danger-full-access` (codex mode) |
  726. | `external_review_tool` | External review tool (`codex`, `custom`, `none`) | `codex` |
  727. | `custom_review_script` | Path to custom review script (when `external_review_tool = custom`) | - |
  728. | `max_external_iterations` | Override external review iteration limit (0 = auto, derived from `max_iterations`) | `0` |
  729. | `review_patience` | Terminate external review after N consecutive unchanged rounds (0 = disabled) | `0` |
  730. | `iteration_delay_ms` | Delay between iterations | `2000` |
  731. | `task_retry_count` | Task retry attempts | `1` |
  732. | `finalize_enabled` | Enable finalize step after reviews | `false` |
  733. | `move_plan_on_completion` | Move completed plan file into `docs/plans/completed/` on success (disable for external plan-lifecycle workflows) | `true` |
  734. | `use_worktree` | Run each plan in an isolated git worktree (full and tasks-only modes only) | `false` |
  735. | `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/keychain). Default `false` strips the key so a host-set value cannot silently override OAuth credentials | `false` |
  736. | `plans_dir` | Plans directory | `docs/plans` |
  737. | `default_branch` | Override auto-detected default branch for review diffs | auto-detect |
  738. | `vcs_command` | VCS command for the git backend (set to a translation script for hg repos) | `git` |
  739. | `commit_trailer` | Trailer line appended to all ralphex-orchestrated git commits | disabled |
  740. | `color_task` | Task execution phase color (hex) | `#00ff00` |
  741. | `color_review` | Review phase color (hex) | `#00ffff` |
  742. | `color_codex` | Codex review color (hex) | `#ff00ff` |
  743. | `color_claude_eval` | Claude evaluation color (hex) | `#64c8ff` |
  744. | `color_warn` | Warning messages color (hex) | `#ffff00` |
  745. | `color_error` | Error messages color (hex) | `#ff0000` |
  746. | `color_signal` | Completion/failure signals color (hex) | `#ff6464` |
  747. | `color_timestamp` | Timestamp prefix color (hex) | `#8a8a8a` |
  748. | `color_info` | Informational messages color (hex) | `#b4b4b4` |
  749. | `claude_error_patterns` | Error patterns to detect in Claude diagnostics or failed-run output (comma-separated) | `You've hit your limit,You've hit your session limit,You've hit your weekly limit,API Error: 400,API Error: 401,API Error: 403,API Error: 404,API Error: 413,API Error: 429,API Error: 500,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,You've hit your individual spend limit` |
  750. | `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,Selected model is at capacity` |
  751. | `claude_limit_patterns` | Limit patterns in Claude diagnostics or failed-run output that trigger wait+retry (comma-separated) | `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` |
  752. | `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,Selected model is at capacity` |
  753. | `claude_retry_patterns` | Transient Claude/fya diagnostic or failed-run markers retried like executor timeouts (comma-separated) | `FYA_TRANSIENT_TIMEOUT,API Error: 529,API Error: 502,API Error: 503,API Error: 504` |
  754. | `wait_on_limit` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |
  755. | `session_timeout` | Per-session timeout for task/review executor (e.g., `30m`, `1h`). Applies to Claude calls in default executor mode and every executor call under `executor = codex`; external codex/custom review in Claude mode is not affected | disabled |
  756. | `idle_timeout` | Kill executor session when no output for specified duration (e.g., `5m`). Resets on each output line. Applies to the claude executor in default mode and to every executor call under `--codex`; external codex review in default-claude mode is NOT affected (preserves master behavior). Custom review is also not affected | disabled |
  757. Colors 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.
  758. Patterns use case-insensitive substring matching, and multiple patterns are separated by commas with whitespace trimmed from each pattern. For Claude, successful assistant messages and successful result summaries are not pattern input: ralphex checks a bounded window of structured CLI diagnostics and non-JSON CLI lines. If the process exits non-zero or the stream fails (an idle timeout cancels the stream, so it counts), it also checks bounded recent surfaced output, which is what keeps limit detection working for wrapper scripts that report failures as ordinary text. A clean assistant response can therefore discuss or quote a configured phrase without being treated as a fresh CLI failure. Codex and custom executors keep their existing failed-exit checks. When an error pattern is detected, ralphex exits gracefully with an informative message suggesting how to check usage/status.
  759. **Transient retry:** Claude retry patterns (`claude_retry_patterns`) are checked before limit and error patterns. They cover wrapper-level stalls such as fya's `FYA_TRANSIENT_TIMEOUT` and transient server-side HTTP errors (`API Error: 529` Overloaded and the `502`/`503`/`504` gateway errors); matches are retried through the existing timeout-style phase path and do not use `wait_on_limit`, so they recover automatically without `--wait`. The task and review retry loops wait a short fixed backoff (5s) before re-running the failed iteration. `API Error: 500` is intentionally excluded — it can be a deterministic server failure and is caught by the enumerated `API Error: 500` error pattern instead.
  760. **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.
  761. **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.
  762. ### Custom prompts
  763. Place custom prompt files in `~/.config/ralphex/prompts/` to override the built-in prompts. Missing files fall back to embedded defaults. See [Review Agents](#review-agents) section for agent customization.
  764. ### Custom External Review
  765. Use your own AI tool for external code review instead of codex. This allows integration with OpenRouter, local LLMs, or any custom pipeline.
  766. **Configuration:**
  767. ```ini
  768. # in ~/.config/ralphex/config
  769. external_review_tool = custom
  770. custom_review_script = ~/.config/ralphex/scripts/my-review.sh
  771. ```
  772. For a one-off run without editing config, use `--external-review-tool=custom --custom-review-script=/path/to/script.sh`.
  773. **Script interface:**
  774. Your 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.
  775. ```bash
  776. #!/bin/bash
  777. # example: ~/.config/ralphex/scripts/my-review.sh
  778. prompt_file="$1"
  779. # read the prompt (contains diff instructions, goal, review focus)
  780. prompt=$(cat "$prompt_file")
  781. # call your AI tool (OpenRouter, local LLM, etc.)
  782. # example with curl to OpenRouter:
  783. curl -s https://openrouter.ai/api/v1/chat/completions \
  784. -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  785. -H "Content-Type: application/json" \
  786. -d "{
  787. \"model\": \"anthropic/claude-3.5-sonnet\",
  788. \"messages\": [{\"role\": \"user\", \"content\": $(echo "$prompt" | jq -Rs .)}]
  789. }" | jq -r '.choices[0].message.content'
  790. ```
  791. **Expected output format:**
  792. - Write findings to stdout as a structured list
  793. - Use format: `file:line - description of issue`
  794. - Output `NO ISSUES FOUND` when there are no problems
  795. **Iteration behavior:**
  796. The external review loop runs up to `max(3, max_iterations/5)` iterations by default. Override with `max_external_iterations` config option or `--max-external-iterations` CLI flag (0 = auto).
  797. The prompt's `{{DIFF_INSTRUCTION}}` variable adapts per iteration:
  798. - **First iteration**: `git diff main...HEAD` (all changes in feature branch)
  799. - **Subsequent iterations**: `git diff` (only uncommitted changes from previous fixes)
  800. This lets the review tool focus on remaining issues after fixes.
  801. ### Notifications
  802. ralphex 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.
  803. ```ini
  804. # in ~/.config/ralphex/config or .ralphex/config
  805. notify_channels = telegram, webhook
  806. notify_telegram_token = 123456:ABC-DEF
  807. notify_telegram_chat = -1001234567890
  808. notify_webhook_urls = https://hooks.example.com/notify
  809. ```
  810. Supported channels: `telegram`, `email`, `slack`, `webhook`, `custom` (script). Misconfigured channels are detected at startup.
  811. See [notifications documentation](https://github.com/umputun/ralphex/blob/master/docs/notifications.md) for setup guides, message format examples, and custom script integration.
  812. **Prompt customization:**
  813. Customize `~/.config/ralphex/prompts/custom_review.txt` to modify the prompt sent to your script. Available variables:
  814. - `{{DIFF_INSTRUCTION}}` - git diff command appropriate for current iteration
  815. - `{{GOAL}}` - human-readable description of what's being implemented
  816. - `{{PLAN_FILE}}` - path to the plan file
  817. - `{{PROGRESS_FILE}}` - path to progress log with previous review iterations
  818. - `{{DEFAULT_BRANCH}}` - detected default branch (main, master, etc.)
  819. - `{{PREVIOUS_REVIEW_CONTEXT}}` - previous review context (empty on first iteration, populated on subsequent)
  820. Customize `~/.config/ralphex/prompts/custom_eval.txt` to modify how Claude evaluates your tool's output.
  821. **Docker considerations:**
  822. When running ralphex in Docker, your script must be accessible inside the container:
  823. - Mount your scripts directory: `-v ~/.config/ralphex/scripts:/home/app/.config/ralphex/scripts:ro`
  824. - Ensure script dependencies are available (curl, jq, etc. are included in base image)
  825. - Environment variables (API keys) must be passed to container: `-e OPENROUTER_API_KEY`
  826. ### Using Alternative Providers for Claude Phases
  827. The `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.
  828. Working examples are included:
  829. - [`scripts/codex-as-claude/codex-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/codex-as-claude/codex-as-claude.sh) wraps codex to produce Claude-compatible events
  830. - [`scripts/copilot-as-claude/copilot-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/copilot-as-claude/copilot-as-claude.sh) wraps GitHub Copilot CLI and translates its native JSONL stream into Claude-compatible events
  831. - [`scripts/gemini-as-claude/gemini-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/gemini-as-claude/gemini-as-claude.sh) wraps Gemini CLI for the implementation slot
  832. - [`scripts/agy-as-claude/agy-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/agy-as-claude/agy-as-claude.sh) wraps the Antigravity (`agy`) CLI — Google's successor to Gemini CLI — for the implementation slot
  833. - [`scripts/opencode/opencode-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/opencode/opencode-as-claude.sh) wraps OpenCode CLI for the implementation slot, and `scripts/opencode/opencode-review.sh` is shipped alongside as a turn-key custom review script
  834. - [`scripts/pi-as-claude/pi-as-claude.sh`](https://github.com/umputun/ralphex/blob/master/scripts/pi-as-claude/pi-as-claude.sh) wraps the pi CLI, translating its `--mode json` JSONL events into Claude-compatible events
  835. To use the included Copilot wrapper:
  836. ```ini
  837. # in ~/.config/ralphex/config or .ralphex/config
  838. claude_command = /path/to/scripts/copilot-as-claude/copilot-as-claude.sh
  839. ```
  840. Authenticate with `copilot login` or set one of `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`. Set `COPILOT_MODEL` to choose the model.
  841. The 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.
  842. For ralphex plan creation, it switches to `--autopilot --allow-all` so clarification can surface through `<<<RALPHEX:QUESTION>>>` signals instead of being suppressed by the unattended question path.
  843. To use the included codex wrapper:
  844. ```ini
  845. # in ~/.config/ralphex/config or .ralphex/config
  846. claude_command = /path/to/scripts/codex-as-claude/codex-as-claude.sh
  847. ```
  848. Or choose it for one invocation:
  849. ```bash
  850. ralphex --claude-command=/path/to/scripts/codex-as-claude/codex-as-claude.sh docs/plans/feature.md
  851. ```
  852. Wrapper scripts should ignore unknown flags gracefully — the included script does this via its `*) shift ;;` catch-all. If a wrapper cannot tolerate the default Claude flags (`--dangerously-skip-permissions`, `--output-format stream-json`, `--verbose`), use `--claude-args=` to explicitly clear configured/default args for that single run.
  853. The included Codex, Copilot, and pi wrappers require `jq` on `PATH` for JSON translation.
  854. Provider-specific environment variables:
  855. - `COPILOT_MODEL`, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` - Copilot model selection and headless authentication
  856. - `CODEX_MODEL` - codex model to use (default: codex default)
  857. - `CODEX_SANDBOX` - sandbox mode (default: `danger-full-access`)
  858. - `CODEX_VERBOSE` - set to `1` to include command execution output in the stream (default: `0`, only agent messages are shown)
  859. - `PI_PROVIDER`, `PI_MODEL`, `PI_THINKING` - pi provider, model, and thinking-level selection (used when ralphex does not append `--model`/`--effort`)
  860. - `PI_VERBOSE` - set to `1` to include tool execution events in the stream (default: `0`, only assistant text is shown)
  861. - `PI_EXTRA_ARGS` - extra flags appended verbatim to the pi invocation (word-split on whitespace); e.g. `--nolo-mode full` to auto-approve tools in non-interactive runs
  862. See [custom providers documentation](https://github.com/umputun/ralphex/blob/master/docs/custom-providers.md) for a detailed guide on writing wrappers for other providers.
  863. ### Swapping Implementation and Review Roles
  864. The 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`:
  865. ```ini
  866. # in ~/.config/ralphex/config or .ralphex/config
  867. claude_command = /path/to/scripts/codex-as-claude/codex-as-claude.sh
  868. external_review_tool = custom
  869. custom_review_script = /path/to/scripts/opencode/opencode-review.sh
  870. ```
  871. The `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).
  872. The repository ships a working custom review script at [`scripts/opencode/opencode-review.sh`](https://github.com/umputun/ralphex/blob/master/scripts/opencode/opencode-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).
  873. The wrappers under `scripts/codex-as-claude/`, `scripts/copilot-as-claude/`, `scripts/gemini-as-claude/`, `scripts/agy-as-claude/`, `scripts/opencode/`, and `scripts/pi-as-claude/` ship in the source tree but are not bundled with the binary. Vendor the one you need into your project (`.ralphex/scripts/`) or reference it from a checkout.
  874. **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.
  875. **Per-project config on feature branches.** If tool-swap configuration lives inside the project (`.ralphex/config`, scripts under `.ralphex/scripts/`), 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/`. Keeping the configuration in `~/.config/ralphex/` instead avoids that case entirely.
  876. ### Configurable VCS Backend
  877. ralphex can work with Mercurial repositories through the `vcs_command` config option and custom prompt files.
  878. ```ini
  879. # in ~/.config/ralphex/config or .ralphex/config
  880. vcs_command = ~/.config/ralphex/scripts/hg2git.sh
  881. ```
  882. A reference translation script is included at [`scripts/hg2git/hg2git.sh`](https://github.com/umputun/ralphex/blob/master/scripts/hg2git/hg2git.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).
  883. You will also need to customise prompt files to replace git commands that Claude executes as bash commands during reviews. See [Mercurial support documentation](https://github.com/umputun/ralphex/blob/master/docs/hg-support.md) for full setup instructions, prompt replacement examples, `.hgignore` setup, and known limitations.
  884. <details markdown>
  885. <summary><b>FAQ</b></summary>
  886. **I installed ralphex, what do I do next?**
  887. Create a plan file in `docs/plans/` (see [Quick Start](#quick-start) for format), then run `ralphex docs/plans/your-plan.md`. ralphex will create a branch, execute tasks, and run reviews automatically.
  888. **Why are there two review phases?**
  889. First review is comprehensive (5 agents by default), second is a final check focusing on critical/major issues only (2 agents). See [How It Works](#how-it-works).
  890. **How do I use my own Claude Code agents?**
  891. Reference them directly in prompt files by name, e.g., `qa-expert - "Review for bugs"`. See [Customization](#customization).
  892. **What if codex isn't installed?**
  893. Codex is optional. If not installed, the codex review phase is skipped automatically.
  894. **Can I run just reviews without task execution?**
  895. Yes, 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.
  896. **Can I run ralphex in a non-git directory?**
  897. Not 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.
  898. **What if my repository has no commits?**
  899. ralphex 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"`.
  900. **Should I run ralphex on master or a feature branch?**
  901. For 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`.
  902. **How do I restore default agents after customizing?**
  903. Run `ralphex --reset` to interactively reset global config. Select which components to reset (config, prompts, agents). Alternatively, delete all `.txt` files from `~/.config/ralphex/agents/` manually. To smart-merge updated defaults into customized files (preserving your changes), use the `/ralphex-update` Claude Code skill or `ralphex --dump-defaults <dir>` to extract defaults for manual comparison.
  904. **How do I disable a default agent?**
  905. Deleting an agent file from `~/.config/ralphex/agents/` 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.
  906. **How does local .ralphex/ config interact with global config?**
  907. Priority: CLI flags > local `.ralphex/config` > global `~/.config/ralphex/config` > 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.
  908. **What happens to uncommitted changes if ralphex fails?**
  909. Ralphex 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.
  910. **What if ralphex is interrupted mid-execution?**
  911. Completed tasks are already committed to the feature branch. To resume, re-run `ralphex docs/plans/<plan>.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. Before reusing a completed progress log, ralphex archives it under `.ralphex/progress/history/<stem>/`; the current log plus its nine newest completed archives are retained. Failed or interrupted runs keep appending to the canonical log with a restart separator.
  912. **Can I adjust the plan or change direction while ralphex is running?**
  913. Yes, two approaches depending on the situation:
  914. 1. **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.
  915. 2. **Stop, edit plan, re-run** — for structural changes (reorder tasks, add/remove 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/plans/<plan>.md`. Ralphex picks up from the first incomplete task and adapts to the updated plan.
  916. **What's the difference between progress file and plan file?**
  917. Progress file (`.ralphex/progress/progress-*.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.
  918. **Do I need to commit changes before running ralphex?**
  919. It depends on the mode. If the plan file is the only uncommitted change, ralphex auto-commits it after creating the feature branch and continues execution.
  920. In the default in-place branch mode, other uncommitted files stop the run with a helpful error and options: stash temporarily (`git stash`), commit first (`git commit -am "wip"`), or use review-only mode (`ralphex --review`). The feature branch is created in that same working tree, so unrelated changes would be mixed into the plan's work.
  921. With `--worktree`, they do not stop the run — ralphex lists them in a warning and leaves them alone. The catch is the other way round: the worktree is built from committed content, so those edits are not in it. Commit anything the plan depends on before starting. See [Worktree Isolation](#worktree-isolation).
  922. **What's the difference between agents/ and prompts/?**
  923. Agents define *what* to check (review instructions). Prompts define *how* the workflow runs (execution steps, signal handling).
  924. **Can I run a custom step before or after all tasks complete?**
  925. Yes. Customize `prompts/task.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:
  926. ```txt
  927. STEP 3 - COMPLETE (after validation passes):
  928. - ...existing steps...
  929. - If NO more [ ] checkboxes in the entire plan, proceed to STEP 4
  930. STEP 4 - STYLE CHECK (only when all tasks are done):
  931. - Use /smells skill to analyze all files changed on this branch
  932. - Fix all reported style and code quality issues
  933. - Run tests and linter again to verify fixes
  934. - Commit fixes if any: fix: address code smell findings
  935. - Output exactly: <<<RALPHEX:ALL_TASKS_DONE>>>
  936. ```
  937. This 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 `~/.config/ralphex/prompts/task.txt` for global use or `.ralphex/prompts/task.txt` for a specific project.
  938. **Can I use ralphex with Claude Pro plan?**
  939. Yes. Pro plans hit rate limits more frequently. Use `--wait` to pause and retry automatically instead of exiting:
  940. ```bash
  941. ralphex --wait=1h docs/plans/feature.md
  942. ```
  943. When 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.
  944. **Can I use Cursor CLI instead of Claude Code?**
  945. Yes. [Cursor CLI](https://cursor.com/cli) is community-tested as a drop-in alternative. Configure in `~/.config/ralphex/config`:
  946. ```ini
  947. claude_command = agent
  948. claude_args = --force --output-format stream-json
  949. ```
  950. Key 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.*
  951. **Can I use codex, GitHub Copilot CLI, or another model for task execution instead of Claude?**
  952. Yes. Use one of the included wrapper scripts that translate provider output to Claude's stream-json format:
  953. ```ini
  954. claude_command = /path/to/scripts/copilot-as-claude/copilot-as-claude.sh
  955. ```
  956. For 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.
  957. The included Copilot wrapper runs Copilot in native autopilot mode with `--autopilot --no-ask-user --allow-all` for unattended task and review execution.
  958. For ralphex plan creation, it switches to `--autopilot --allow-all` so clarification can surface through `<<<RALPHEX:QUESTION>>>` signals instead of being suppressed by the unattended question path.
  959. Codex works the same way through its wrapper:
  960. ```ini
  961. claude_command = /path/to/scripts/codex-as-claude/codex-as-claude.sh
  962. ```
  963. Set `CODEX_MODEL` env var to choose the model. See [Using Alternative Providers](#using-alternative-providers-for-claude-phases) and [custom providers documentation](https://github.com/umputun/ralphex/blob/master/docs/custom-providers.md) for the included Copilot example and for writing wrappers for other tools.
  964. **How do I use multiple Claude accounts?**
  965. Set the `CLAUDE_CONFIG_DIR` environment variable to point to the alternate Claude config directory:
  966. ```bash
  967. CLAUDE_CONFIG_DIR=~/.claude2 ralphex docs/plans/feature.md
  968. ```
  969. This 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.
  970. **Can I run something after all phases complete (notifications, rebase commits, etc.)?**
  971. Yes. 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 `~/.config/ralphex/prompts/finalize.txt` for other actions like sending notifications, pushing to remote, or running custom scripts.
  972. </details>
  973. ## Web Dashboard
  974. The `--serve` flag starts a browser-based dashboard for real-time monitoring of plan execution.
  975. ```bash
  976. ralphex --serve docs/plans/feature.md
  977. # web dashboard: http://localhost:8080
  978. ```
  979. ### Features
  980. - **Real-time streaming** - SSE connection for live output updates
  981. - **Phase navigation** - filter by All/Task/Review/Codex phases
  982. - **Collapsible sections** - organized output with expand/collapse
  983. - **Text search** - find text with highlighting (keyboard: `/` to focus, `Escape` to clear)
  984. - **Auto-scroll** - follows output, click to disable
  985. - **Late-join support** - new clients receive full history
  986. The dashboard uses a dark theme with phase-specific colors matching terminal output. All file and stdout logging continues unchanged when using `--serve`.
  987. ### Multi-Session Mode
  988. The `--watch` flag enables monitoring multiple ralphex sessions simultaneously:
  989. ```bash
  990. # watch specific directories for progress files
  991. ralphex --serve --watch ~/projects/frontend --watch ~/projects/backend
  992. # configure watch directories in config file
  993. # watch_dirs = /home/user/projects, /var/log/ralphex
  994. ```
  995. Multi-session features:
  996. - **Session sidebar** - lists all discovered sessions, click to switch (keyboard: `S` to toggle)
  997. - **Active detection** - pulsing indicator for running sessions via file locking
  998. - **Auto-discovery** - new sessions appear automatically as they start
  999. ## Claude Code Integration (Optional)
  1000. ralphex works standalone from the terminal. Optionally, you can add slash commands to Claude Code for a more integrated experience.
  1001. ### Available Commands
  1002. | Command | Description |
  1003. |---------|-------------|
  1004. | `/ralphex` | Launch and monitor ralphex execution with interactive mode/plan selection |
  1005. | `/ralphex-plan` | Create structured implementation plans with guided context gathering |
  1006. | `/ralphex-adopt` | Convert plans from various source formats (OpenSpec, spec-kit, GitHub/GitLab issues, generic task-lists, free-form markdown) into ralphex-format plans |
  1007. | `/ralphex-update` | Smart-merge updated embedded defaults into customized prompts/agents |
  1008. ### Installation
  1009. The ralphex CLI is the primary interface. Claude Code skills (`/ralphex`, `/ralphex-plan`, `/ralphex-adopt`, and `/ralphex-update`) are optional convenience commands.
  1010. **Via Plugin Marketplace (Recommended)**
  1011. ```bash
  1012. # Add ralphex marketplace
  1013. /plugin marketplace add umputun/ralphex
  1014. # Install the plugin
  1015. /plugin install ralphex@ralphex
  1016. ```
  1017. Benefits: Auto-updates when marketplace refreshes (at Claude Code startup).
  1018. **Manual Installation (Alternative)**
  1019. The slash command definitions are hosted at:
  1020. - [`/ralphex`](https://ralphex.com/assets/claude/ralphex.md)
  1021. - [`/ralphex-plan`](https://ralphex.com/assets/claude/ralphex-plan.md)
  1022. - [`/ralphex-adopt`](https://ralphex.com/assets/claude/ralphex-adopt.md)
  1023. - [`/ralphex-update`](https://ralphex.com/assets/claude/ralphex-update.md)
  1024. To install, ask Claude Code to "install ralphex slash commands" or manually copy the files to `~/.claude/commands/`.
  1025. ### Usage
  1026. Once installed:
  1027. ```
  1028. # in Claude Code conversation
  1029. /ralphex-plan add user authentication # creates plan interactively
  1030. /ralphex docs/plans/auth.md # launches execution
  1031. "check ralphex" # gets status update
  1032. ```
  1033. The `/ralphex` command runs ralphex in the background and provides status updates on request. The `/ralphex-plan` command guides you through creating well-structured plans with context discovery and approach selection.
  1034. > **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. However, running from a standalone terminal is still recommended for the best experience. If the nested session error is somehow encountered, ralphex detects it via error pattern matching and exits gracefully.
  1035. ## For LLMs
  1036. See [llms.txt](llms.txt) for LLM-optimized documentation.
  1037. ## License
  1038. MIT License - see [LICENSE](LICENSE) file.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.