ralphex_cp

README

Autonomous plan execution with GitHub Copilot CLI

ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates GitHub Copilot CLI to execute implementation plans autonomously - no IDE plugins or cloud services required, just Copilot CLI and a single binary.

AI coding assistants are powerful but interactive - they require 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.

ralphex solves both problems. Each task executes in a fresh Copilot CLI 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.

Task Execution Screenshot

Review Mode Screenshot

Web Dashboard Screenshot

Features

• Zero setup - works out of the box with sensible defaults, no configuration required
• Autonomous task execution - executes plan tasks one at a time with automatic retry
• Interactive plan creation - create plans through dialogue with Claude via --plan flag
• Multi-phase code review - 5 agents → Copilot external review → 2 agents review pipeline
• Custom review agents - configurable agents with {{agent:name}} template system and user defined prompts
• Automatic branch creation - creates git branch from plan filename
• Plan completion tracking - moves completed plans to completed/ folder
• Automatic commits - commits after each task and review fix
• Real-time monitoring - streaming output with timestamps, colors, and detailed logs
• Web dashboard - browser-based real-time view with --serve flag
• Docker support - run in isolated container for safer autonomous execution
• Notifications - optional alerts on completion/failure via Telegram, Email, Slack, Webhook, or custom script
• Worktree isolation - run multiple plans in parallel via --worktree flag
• Multiple modes - full execution, tasks-only, review-only, external-only, or plan creation

Quick Start

Make sure ralphex is installed and your project is a git repository. You need a plan file 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.

How It Works

ralphex executes plans in four phases with automated code reviews, plus an optional finalize step.

Execution Flow Diagram

Phase 1: Task Execution

1. Reads plan file and finds first incomplete task (### Task N: with - [ ] checkboxes)
2. Sends task to Copilot CLI for execution
3. Runs validation commands (tests, linters) after each task
4. Marks checkboxes as done [x], commits changes
5. Repeats until all tasks complete or max iterations reached

Phase 2: First Code Review

Launches 5 review agents in parallel via Copilot CLI Task tool:

Agent	Purpose
quality	bugs, security issues, race conditions
implementation	verifies code achieves stated goals
testing	test coverage and quality
simplification	detects over-engineering
documentation	checks if docs need updates

The coding model verifies findings, fixes confirmed issues, and commits.

Default agents provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See Customization for details.

Phase 3: External Review (optional)

1. Runs external review tool (Copilot CLI with review model by default, or custom script)
2. Coding model evaluates findings, fixes valid issues
3. Iterates until no open issues

The loop terminates when: all issues resolved, max iterations reached, stalemate detected (via --review-patience), or manual break via Ctrl+\ (SIGQUIT).

Stalemate detection: When the external tool and the coding model 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.

Manual break: Press Ctrl+\ (SIGQUIT) during the external review loop to terminate it immediately. The current executor run is cancelled via context cancellation. Not available on Windows.

Supported tools:

• copilot (default): Copilot CLI with review model (gpt-5.2-codex) for independent code review
• custom: Your own script wrapping any AI (OpenRouter, local LLM, etc.)
• none: Skip external review entirely

See Custom External Review for details on using custom scripts.

Phase 4: Second Code Review

1. Launches 2 agents (quality + implementation) for final review
2. Focuses on critical/major issues only
3. Iterates until no issues found
4. Moves plan to completed/ folder on success

Second review agents are configurable via prompts/review_second.txt.

Finalize Step (optional)

After all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.

What it does: runs a single Copilot CLI session with a customizable prompt. The default finalize.txt prompt rebases commits onto the default branch and optionally squashes related commits into logical groups.

How to enable:

Set finalize_enabled = true in ~/.config/ralphex/config or .ralphex/config.

Behavior:

• Runs once (no iteration loop)
• Best-effort — failures are logged but don't block success
• Triggers on modes with review pipeline: full, review-only, external-only
• Uses task color (green) for output

Customization:

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.

Review-Only Mode

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 manual edits, other AI agents, or any other workflow.

Workflow:

1. Make changes on a feature branch (using any tool or workflow)
2. Commit the changes
3. Run ralphex --review

ralphex compares the branch against the default branch (git diff master...HEAD), launches multi-agent reviews, and iterates fixes until all agents report clean. No plan file is required — if provided, it gives reviewers additional context about the intended changes.

# switch to feature branch with existing changes
git checkout feature-auth

# run review pipeline on those changes
ralphex --review

# optionally pass a plan file for context
ralphex --review docs/plans/add-auth.md

Plan Creation

Plans can be created in several ways:

• Claude Code skills - use slash commands like /ralphex-plan or your own planning workflows
• Manually - write markdown files directly in docs/plans/
• --plan flag - integrated option that handles the entire flow
• Auto-detection - running ralphex without arguments on master/main prompts for plan creation if no plans exist

The --plan flag provides a simpler integrated experience:

ralphex --plan "add health check endpoint"

The coding model 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.

Example session:

$ ralphex --plan "add caching for API responses"
[10:30:05] analyzing codebase structure...
[10:30:12] found existing store layer in pkg/store/

QUESTION: Which cache backend?
  > Redis
    In-memory
    File-based
    Other (type your own answer)

[10:30:45] ANSWER: Redis
[10:31:00] continuing plan creation...
[10:32:05] plan written to docs/plans/add-api-caching.md

Continue with plan implementation?
  > Yes, execute plan
    No, exit

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.

Installation

From source

go install github.com/kulebyaka/ralphex_cp/cmd/ralphex@latest

Using Homebrew

brew install kulebyaka/apps/ralphex

From releases

Download the appropriate binary from releases.

Windows

Download ralphex_<version>_windows_amd64.zip (or arm64) from releases, extract, and add to PATH:

# PowerShell — download and extract to a directory in PATH
Invoke-WebRequest -Uri "https://github.com/kulebyaka/ralphex_cp/releases/latest/download/ralphex_0.1.0_windows_amd64.zip" -OutFile ralphex.zip
Expand-Archive ralphex.zip -DestinationPath "$env:LOCALAPPDATA\ralphex"
# add to PATH (persistent for current user)
[Environment]::SetEnvironmentVariable("Path", "$env:LOCALAPPDATA\ralphex;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

Or install with Go:

go install github.com/kulebyaka/ralphex_cp/cmd/ralphex@latest

Windows limitations: process group signals not available (child processes won't be cleanly killed), file locking disabled (no active session detection), manual break via Ctrl+\ not available. See Platform Support for details.

Using Docker

Download the wrapper script and install to PATH:

curl -sL https://raw.githubusercontent.com/kulebyaka/ralphex_cp/master/scripts/ralphex-dk.sh -o /usr/local/bin/ralphex
chmod +x /usr/local/bin/ralphex

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 for examples), then point the wrapper at it:

export RALPHEX_IMAGE=my-ralphex

Then use ralphex as usual - it runs in a container with Copilot CLI pre-installed. The script shows which image it's using at startup.

Why use Docker? ralphex runs Copilot CLI with --allow-all --no-ask-user, giving it full access to execute commands and modify files. Running in a container provides isolation - the model can only access the mounted project directory, not your entire system. This makes autonomous execution significantly safer.

Isolation details

Container CAN access (read-write):

• Project directory mounted at /workspace - full access to create, modify, delete files
• Git operations within the project (branch, commit, etc.)

Container CAN access (read-only):

• ~/.copilot/ - Copilot CLI credentials and settings (copied at startup, not modified)
• ~/.config/ralphex/ - user-level ralphex configuration
• ~/.gitconfig - git identity for commits
• Global gitignore (core.excludesFile) - auto-detected and mounted
• .ralphex/ - project-level configuration if present

Container CANNOT access:

• Host filesystem outside mounted directories
• Other projects or repositories
• SSH keys, AWS credentials, or other secrets in ~/.ssh, ~/.aws, etc.
• System files, binaries, or configurations
• Other running processes or containers

Network: Full network access (required for Copilot API calls)

Privileges: Runs as non-root user with no elevated capabilities

Volume mounts:

• Read-only: ~/.copilot mounted to /mnt/, copied at startup to preserve isolation
• Read-write: project directory (/workspace) - where ralphex creates branches, edits code, and commits
• Extra mounts: user-defined volumes via -v/--volume flags or RALPHEX_EXTRA_VOLUMES env var

Requirements:

• Python 3.9+ (for the wrapper script)
• Docker installed and running
• GitHub authentication for Copilot CLI (via GITHUB_TOKEN or ~/.copilot/)
• Git config in ~/.gitconfig (for commits)

Environment variables:

• RALPHEX_IMAGE - Docker image to use (default: ghcr.io/kulebyaka/ralphex_cp-go:latest)
• RALPHEX_PORT - Port for web dashboard when using --serve (default: 8080)
• RALPHEX_CONFIG_DIR - Custom config directory (default: ~/.config/ralphex). Overrides global config location for prompts, agents, and settings
• GITHUB_TOKEN - GitHub token for Copilot CLI authentication (passed through to container)
• RALPHEX_EXTRA_VOLUMES - Extra volume mounts, comma-separated (e.g., /data:/mnt/data:ro,/models:/mnt/models). Entries without : are silently skipped
• 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
• TZ - Override container timezone (default: auto-detected from host via /etc/localtime). Example: TZ=Europe/Berlin ralphex docs/plans/feature.md Extra volume mounts:

# via CLI flags (can use multiple -v)
ralphex -v /data:/mnt/data:ro -v /models:/mnt/models docs/plans/feature.md

# via environment variable (comma-separated)
RALPHEX_EXTRA_VOLUMES="/data:/mnt/data:ro,/models:/mnt/models" ralphex docs/plans/feature.md

Extra environment variables:

# via CLI flags (can use multiple -E)
ralphex -E DEBUG=1 -E API_KEY docs/plans/feature.md

# via environment variable (comma-separated)
RALPHEX_EXTRA_ENV="DEBUG=1,LOG_LEVEL=verbose" ralphex docs/plans/feature.md

# name-only form inherits value from host (recommended for secrets)
export API_KEY=secret123
ralphex -E API_KEY docs/plans/feature.md

# values containing commas require -E flag (env var splits on commas)
ralphex -E "TAGS=foo,bar,baz" docs/plans/feature.md

Updating:

ralphex --update         # pull latest docker image
ralphex --update-script  # update the wrapper script itself

Available images

Two images are published:

Image	Description
ghcr.io/kulebyaka/ralphex_cp:latest	Base image with Copilot CLI and core tools
ghcr.io/kulebyaka/ralphex_cp-go:latest	Go development (extends base with Go toolchain)

Base image includes:

Tool	Version	Purpose
Copilot CLI	latest	AI coding assistant
Node.js/npm	24.x	Required for Copilot CLI
Python/pip	3.x	Scripts and automation
git	2.x	Version control
make	4.x	Build automation
gcc, musl-dev	-	C compiler for native extensions
bash	5.x	Shell
fzf	-	Fuzzy finder for plan selection
ripgrep	-	Fast search (used by Copilot CLI)

Go image adds:

Tool	Version	Purpose
Go	1.26.0	Go compiler and runtime
golangci-lint	latest	Go linter
moq	latest	Mock generator
goimports	latest	Import formatter

For Go projects, use the -go image:

RALPHEX_IMAGE=ghcr.io/kulebyaka/ralphex_cp-go:latest ralphex docs/plans/feature.md

For other languages, create a custom image by extending the base with your language toolchain. The Go image (Dockerfile-go) shows the pattern:

FROM ghcr.io/kulebyaka/ralphex_cp:latest

# install go from official distribution
ARG GO_VERSION=1.26.0
RUN ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') && \
    wget -qO- "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" | tar -xz -C /usr/local

ENV GOROOT=/usr/local/go
ENV GOPATH=/home/app/go
ENV PATH="${PATH}:${GOROOT}/bin:${GOPATH}/bin"

# install go tools
RUN wget -qO- https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b /usr/local/bin && \
    GOBIN=/usr/local/bin go install github.com/matryer/moq@latest && \
    GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest

Same approach for Rust, Java, or any other language:

FROM ghcr.io/kulebyaka/ralphex_cp:latest

# rust
RUN apk add --no-cache rust cargo
ENV CARGO_HOME=/home/app/.cargo PATH="${PATH}:${CARGO_HOME}/bin"

# java
RUN apk add --no-cache openjdk21-jdk
ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk PATH="${PATH}:${JAVA_HOME}/bin"

Build and use:

docker build -t my-ralphex -f Dockerfile.python .
RALPHEX_IMAGE=my-ralphex ralphex docs/plans/feature.md

Example with custom port:

RALPHEX_PORT=3000 ralphex --serve --port 3000 docs/plans/feature.md

Usage

Note: ralphex must be run from the repository root directory (where .git is located).

# execute plan with task loop + reviews
ralphex docs/plans/feature.md

# select plan with fzf, or create one interactively if none exist
ralphex

# review-only mode (skip task execution)
ralphex --review docs/plans/feature.md

# external-only mode (skip tasks and first review, run only external review loop)
ralphex --external-only

# tasks-only mode (run only task phase, skip all reviews)
ralphex --tasks-only docs/plans/feature.md

# run in isolated git worktree (parallel-safe)
ralphex --worktree docs/plans/feature.md

# override default branch for review diffs
ralphex --review --base-ref develop
ralphex --review --base-ref abc1234 --skip-finalize

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

# with custom max iterations
ralphex --max-iterations=100 docs/plans/feature.md

# limit external review iterations (0 = auto, derived from max-iterations)
ralphex --max-external-iterations=5 docs/plans/feature.md

# terminate external review after 3 unchanged rounds (stalemate detection)
ralphex --review-patience=3 docs/plans/feature.md

# wait and retry on rate limit (instead of exiting)
ralphex --wait 1h docs/plans/feature.md

# with web dashboard
ralphex --serve docs/plans/feature.md

# web dashboard on custom port
ralphex --serve --port 3000 docs/plans/feature.md

Options

Flag	Description	Default
-m, --max-iterations	Maximum task iterations	50
--max-external-iterations	Override external review iteration limit (0 = auto)	0
--review-patience	Terminate external review after N unchanged rounds (0 = disabled)	0
-r, --review	Skip task execution, run full review pipeline	false
-e, --external-only	Skip tasks and first review, run only external review loop	false
-c, --codex-only	Alias for --external-only (deprecated)	false
-t, --tasks-only	Run only task phase, skip all reviews	false
-b, --base-ref	Override default branch for review diffs (branch name or commit hash)	auto-detect
--skip-finalize	Skip finalize step even if enabled in config	false
--wait	Wait duration before retrying on rate limit (e.g., 1h, 30m)	disabled
--worktree	Run in isolated git worktree (enables parallel execution)	false
--plan	Create plan interactively (provide description)	-
-s, --serve	Start web dashboard for real-time streaming	false
-p, --port	Web dashboard port (used with --serve)	8080
-w, --watch	Directories to watch for progress files (repeatable)	-
-d, --debug	Enable debug logging	false
--no-color	Disable color output	false
--reset	Interactively reset global config to embedded defaults	-
--dump-defaults	Extract raw embedded defaults to specified directory	-
--config-dir	Custom config directory (env: RALPHEX_CONFIG_DIR)	~/.config/ralphex

Plan File Format

Plans are markdown files with task sections. Each task has checkboxes that the coding model marks complete.

# Plan: Add User Authentication

## Overview
Add JWT-based authentication to the API.

## Validation Commands
- `go test ./...`
- `golangci-lint run`

### Task 1: Add auth middleware
- [ ] Create JWT validation middleware
- [ ] Add to router for protected routes
- [ ] Add tests
- [ ] Mark completed

### Task 2: Add login endpoint
- [ ] Create /api/login handler
- [ ] Return JWT on successful auth
- [ ] Add tests
- [ ] Mark completed

Requirements:

• Task headers must use ### Task N: or ### Iteration N: format (N can be integer or non-integer like 2.5, 2a)
• Checkboxes: - [ ] (incomplete) or - [x] (completed)
• Include ## Validation Commands section with test/lint commands
• Place plans in docs/plans/ directory (configurable via plans_dir)

Review Agents

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.

Default Agents

These 5 agents cover common review concerns and work well out of the box. Customize or replace them based on your needs:

Agent	Phase	Purpose
quality	1st & 2nd	bugs, security issues, race conditions
implementation	1st & 2nd	verifies code achieves stated goals
testing	1st only	test coverage and quality
simplification	1st only	detects over-engineering
documentation	1st only	checks if docs need updates

Agent Options (Frontmatter)

Agent files support optional YAML frontmatter for per-agent configuration:

---
model: haiku
agent: code-reviewer
---
Review the code for quality issues...

Option	Values	Description
model	claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5, gpt-5.2-codex	Copilot model for this agent
agent	any string	Copilot CLI Task tool subagent type

Both options are optional. Without frontmatter, agents use default model and general-purpose subagent type. Full Copilot model IDs are used directly. Invalid model values are dropped with a warning.

Template Syntax

Custom prompt files support variable expansion. All variables use the {{VARIABLE}} syntax.

Available variables:

Variable	Description	Example value
{{PLAN_FILE}}	Path to the plan file being executed	docs/plans/feature.md
{{PROGRESS_FILE}}	Path to the progress log file	.ralphex/progress/progress-feature.txt
{{GOAL}}	Human-readable goal description	implementation of plan at docs/plans/feature.md
{{DEFAULT_BRANCH}}	Default branch name (overridable via --base-ref or default_branch config)	main, master, origin/main
{{agent:name}}	Expands to Task tool instructions for the named agent	(see below)

Agent references:

Reference agents in prompt files using {{agent:name}} syntax:

Launch the following review agents in parallel:
{{agent:quality}}
{{agent:implementation}}
{{agent:testing}}

Each {{agent:name}} expands to Task tool instructions that tell Copilot CLI to run that agent. Variables inside agent content are also expanded, so agents can use {{DEFAULT_BRANCH}} or other variables.

Customization

The entire system is designed for customization - both task execution and reviews:

Agent files (~/.config/ralphex/agents/):

• Edit existing files to modify agent behavior
• Add new .txt files to create custom agents
• Run ralphex --reset to interactively restore defaults, or delete all files manually
• Run ralphex --dump-defaults <dir> to extract raw defaults for comparison
• Use the /ralphex-update skill to smart-merge updated defaults into customized files
• Alternatively, reference agents already installed in your Copilot CLI directly in prompt files (see example below)

Prompt files (~/.config/ralphex/prompts/):

• task.txt - task execution prompt
• review_first.txt - comprehensive review (default: 5 language-agnostic agents - quality, implementation, testing, simplification, documentation; customizable)
• copilot_review.txt - Copilot external review prompt
• review_second.txt - final review, critical/major issues only (default: 2 agents - quality, implementation; customizable)
• finalize.txt - optional finalize step prompt (disabled by default)

Comment lines and markdown headers: 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:

# This single title line is preserved as a markdown header
check for SQL injection
# this mid-body comment is also preserved
check for XSS

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.

Note: Inline comments are not supported (text # comment keeps the entire line).

Examples:

• Add a security-focused agent for fintech projects
• Remove simplification agent if over-engineering isn't a concern
• Create language-specific agents (Python linting, TypeScript types)
• Modify prompts to change how many agents run per phase

Using Copilot CLI agents directly:

Instead of creating agent files, you can reference agents installed in your Copilot CLI directly in prompt files:

# in review_first.txt - just list agent names with their prompts
Agents to launch:
1. qa-expert - "Review for bugs and security issues"
2. go-test-expert - "Review test coverage and quality"
3. go-smells-expert - "Review for code smells"

Requirements

• copilot - GitHub Copilot CLI
• fzf - for plan selection (optional)

Configuration

ralphex uses a configuration directory at ~/.config/ralphex/ (override with --config-dir or RALPHEX_CONFIG_DIR) with the following structure:

~/.config/ralphex/
├── config              # main configuration file (INI format)
├── prompts/            # custom prompt templates
│   ├── task.txt
│   ├── review_first.txt
│   ├── review_second.txt
│   └── copilot_review.txt
└── agents/             # custom review agents (*.txt files)

On first run, ralphex creates this directory with default configuration.

Commented templates:

• Config files are installed with all content commented out (# prefix)
• Uncomment only the settings you want to customize
• Files that remain all-commented receive automatic updates with new defaults
• Once you uncomment any setting, the file is preserved and won't be overwritten

Local Project Config

Projects can override global settings with a .ralphex/ directory in the project root:

project/
├── .ralphex/           # optional, project-local config
│   ├── config          # overrides specific settings
│   ├── prompts/        # custom prompts for this project
│   └── agents/         # custom agents for this project

Priority: CLI flags > local .ralphex/ > global ~/.config/ralphex/ > embedded defaults

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.

Merge behavior:

• Config file: per-field override (local values override global, missing fields fall back)
• Prompts: per-file fallback (local → global → embedded for each prompt file)
• Agents: replace entirely (if local agents/ has .txt files, use ONLY local agents)

Configuration options

Option	Description	Default
copilot_command	Copilot CLI command	copilot
copilot_args	Copilot CLI arguments	--allow-all --no-ask-user --output-format json
copilot_coding_model	Model for task execution and review phases	claude-opus-4-6
copilot_review_model	Model for external review phases	gpt-5.2-codex
external_review_tool	External review tool (copilot, custom, none)	copilot
custom_review_script	Path to custom review script (when external_review_tool = custom)	-
max_external_iterations	Override external review iteration limit (0 = auto, derived from max_iterations)	0
review_patience	Terminate external review after N consecutive unchanged rounds (0 = disabled)	0
iteration_delay_ms	Delay between iterations	2000
task_retry_count	Task retry attempts	1
finalize_enabled	Enable finalize step after reviews	false
use_worktree	Run each plan in an isolated git worktree	false
plans_dir	Plans directory	docs/plans
default_branch	Override auto-detected default branch for review diffs	auto-detect
vcs_command	VCS command for the git backend (set to a translation script for hg repos)	git
color_task	Task execution phase color (hex)	#00ff00
color_review	Review phase color (hex)	#00ffff
color_copilot	Copilot review color (hex)	#ff00ff
color_copilot_eval	Copilot evaluation color (hex)	#64c8ff
color_warn	Warning messages color (hex)	#ffff00
color_error	Error messages color (hex)	#ff0000
color_signal	Completion/failure signals color (hex)	#ff6464
color_timestamp	Timestamp prefix color (hex)	#8a8a8a
color_info	Informational messages color (hex)	#b4b4b4
copilot_error_patterns	Patterns to detect in Copilot CLI output (comma-separated)	Rate limit,quota exceeded,API Error
copilot_limit_patterns	Limit patterns triggering wait+retry (comma-separated)	Rate limit,quota exceeded
wait_on_limit	Wait duration before retrying on rate limit (e.g., 1h, 30m)	disabled

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.

Error patterns use case-insensitive substring matching. When a pattern is detected in Copilot CLI output, ralphex exits gracefully with an informative message suggesting how to check usage/status. Multiple patterns are separated by commas, with whitespace trimmed from each pattern.

Rate limit retry: Limit patterns (copilot_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.

Custom prompts

Place custom prompt files in ~/.config/ralphex/prompts/ to override the built-in prompts. Missing files fall back to embedded defaults. See Review Agents section for agent customization.

Custom External Review

Use your own AI tool for external code review instead of Copilot CLI. This allows integration with OpenRouter, local LLMs, or any custom pipeline.

Configuration:

# in ~/.config/ralphex/config
external_review_tool = custom
custom_review_script = ~/.config/ralphex/scripts/my-review.sh

Script interface:

Your script receives a single argument: path to a prompt file containing review instructions. The script outputs findings to stdout - ralphex passes them to the coding model for evaluation and fixing.

#!/bin/bash
# example: ~/.config/ralphex/scripts/my-review.sh
prompt_file="$1"

# read the prompt (contains diff instructions, goal, review focus)
prompt=$(cat "$prompt_file")

# call your AI tool (OpenRouter, local LLM, etc.)
# example with curl to OpenRouter:
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"anthropic/claude-3.5-sonnet\",
    \"messages\": [{\"role\": \"user\", \"content\": $(echo "$prompt" | jq -Rs .)}]
  }" | jq -r '.choices[0].message.content'

Expected output format:

• Write findings to stdout as a structured list
• Use format: file:line - description of issue
• Output NO ISSUES FOUND when there are no problems

Iteration behavior:

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

The prompt's {{DIFF_INSTRUCTION}} variable adapts per iteration:

• First iteration: git diff main...HEAD (all changes in feature branch)
• Subsequent iterations: git diff (only uncommitted changes from previous fixes)

This lets the review tool focus on remaining issues after fixes.

Notifications

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.

# in ~/.config/ralphex/config or .ralphex/config
notify_channels = telegram, webhook
notify_telegram_token = 123456:ABC-DEF
notify_telegram_chat = -1001234567890
notify_webhook_urls = https://hooks.example.com/notify

Supported channels: telegram, email, slack, webhook, custom (script). Misconfigured channels are detected at startup.

See notifications documentation for setup guides, message format examples, and custom script integration.

Prompt customization:

Customize ~/.config/ralphex/prompts/custom_review.txt to modify the prompt sent to your script. Available variables:

• {{DIFF_INSTRUCTION}} - git diff command appropriate for current iteration
• {{GOAL}} - human-readable description of what's being implemented
• {{PLAN_FILE}} - path to the plan file
• {{DEFAULT_BRANCH}} - detected default branch (main, master, etc.)

Customize ~/.config/ralphex/prompts/custom_eval.txt to modify how Claude evaluates your tool's output.

Docker considerations:

When running ralphex in Docker, your script must be accessible inside the container:

• Mount your scripts directory: -v ~/.config/ralphex/scripts:/home/app/.config/ralphex/scripts:ro
• Ensure script dependencies are available (curl, jq, etc. are included in base image)
• Environment variables (API keys) must be passed to container: -e OPENROUTER_API_KEY

Copilot CLI Configuration

The copilot_command and copilot_args config options let you override the Copilot CLI command and its arguments. The CopilotExecutor uses two models controlled by copilot_coding_model (default: claude-opus-4-6) and copilot_review_model (default: gpt-5.2-codex).

# in ~/.config/ralphex/config or .ralphex/config
copilot_command = copilot
copilot_args = --allow-all --no-ask-user --output-format json
copilot_coding_model = claude-opus-4-6
copilot_review_model = gpt-5.2-codex

See custom providers documentation for details on the JSONL output format and configuration.

Configurable VCS Backend

ralphex can work with Mercurial repositories through the vcs_command config option and custom prompt files.

# in ~/.config/ralphex/config or .ralphex/config
vcs_command = ~/.config/ralphex/scripts/hg2git.sh

A reference translation script is included at scripts/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).

You will also need to customise prompt files to replace git commands that the coding model executes as bash commands during reviews. See Mercurial support documentation for full setup instructions, prompt replacement examples, .hgignore setup, and known limitations.

FAQ

I installed ralphex, what do I do next?

Create a plan file in docs/plans/ (see Quick Start for format), then run ralphex docs/plans/your-plan.md. ralphex will create a branch, execute tasks, and run reviews automatically.

Why are there two review phases?

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 do I use my own Copilot CLI agents?

Reference them directly in prompt files by name, e.g., qa-expert - "Review for bugs". See Customization.

What if external review is not needed?

External review is optional. Set external_review_tool = none in config to skip it entirely.

Can I run just reviews without task execution?

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 — manual edits, other AI agents, etc. Switch to the feature branch, commit your changes, and run ralphex --review. See Review-Only Mode for details.

Can I run ralphex in a non-git directory?

Not directly, but ralphex supports Mercurial repos through the vcs_command config option and a translation script. See Configurable VCS Backend for setup.

What if my repository has no commits?

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

Should I run ralphex on master or a feature branch?

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.

How do I restore default agents after customizing?

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 skill or ralphex --dump-defaults <dir> to extract defaults for manual comparison.

How does local .ralphex/ config interact with global config?

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: if local agents/ has any .txt files, it replaces global agents entirely.

What happens to uncommitted changes if ralphex fails?

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.

What if ralphex is interrupted mid-execution?

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.

Can I adjust the plan or change direction while ralphex is running?

Yes, two approaches depending on the situation:

1. Edit CLAUDE.md — for behavioral changes (coding style, libraries, constraints). Each task runs in a fresh Copilot CLI session that reads CLAUDE.md at startup, so changes take effect on the next task or iteration automatically. No need to stop ralphex.

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.

What's the difference between progress file and plan file?

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.

Do I need to commit changes before running ralphex?

It depends. If the plan file is the only uncommitted change, ralphex auto-commits it after creating the feature branch and continues execution. If other files have uncommitted changes, ralphex shows a helpful error with options: stash temporarily (git stash), commit first (git commit -am "wip"), or use review-only mode (ralphex --review).

What's the difference between agents/ and prompts/?

Agents define what to check (review instructions). Prompts define how the workflow runs (execution steps, signal handling).

Can I run a custom step before or after all tasks complete?

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:

STEP 3 - COMPLETE (after validation passes):
- ...existing steps...
- If NO more [ ] checkboxes in the entire plan, proceed to STEP 4

STEP 4 - STYLE CHECK (only when all tasks are done):
- Use /smells skill to analyze all files changed on this branch
- Fix all reported style and code quality issues
- Run tests and linter again to verify fixes
- Commit fixes if any: fix: address code smell findings
- Output exactly: <<<RALPHEX:ALL_TASKS_DONE>>>

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.

Can I use ralphex with Claude Pro plan?

Yes. Pro plans hit rate limits more frequently. Use --wait to pause and retry automatically instead of exiting:

ralphex --wait 1h docs/plans/feature.md

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.

Can I use a different model for task execution?

Yes. Configure copilot_coding_model in ~/.config/ralphex/config:

copilot_coding_model = claude-sonnet-4-6

See Copilot CLI Configuration for all available options.

Can I run something after all phases complete (notifications, rebase commits, etc.)?

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.

Web Dashboard

The --serve flag starts a browser-based dashboard for real-time monitoring of plan execution.

ralphex --serve docs/plans/feature.md
# web dashboard: http://localhost:8080

Features

• Real-time streaming - SSE connection for live output updates
• Phase navigation - filter by All/Task/Review/External phases
• Collapsible sections - organized output with expand/collapse
• Text search - find text with highlighting (keyboard: / to focus, Escape to clear)
• Auto-scroll - follows output, click to disable
• Late-join support - new clients receive full history

The dashboard uses a dark theme with phase-specific colors matching terminal output. All file and stdout logging continues unchanged when using --serve.

Multi-Session Mode

The --watch flag enables monitoring multiple ralphex sessions simultaneously:

# watch specific directories for progress files
ralphex --serve --watch ~/projects/frontend --watch ~/projects/backend

# configure watch directories in config file
# watch_dirs = /home/user/projects, /var/log/ralphex

Multi-session features:

• Session sidebar - lists all discovered sessions, click to switch (keyboard: S to toggle)
• Active detection - pulsing indicator for running sessions via file locking
• Auto-discovery - new sessions appear automatically as they start

Claude Code Integration (Optional)

ralphex works standalone from the terminal. Optionally, you can add slash commands for a more integrated experience.

Available Commands

Command	Description
/ralphex	Launch and monitor ralphex execution with interactive mode/plan selection
/ralphex-plan	Create structured implementation plans with guided context gathering
/ralphex-update	Smart-merge updated embedded defaults into customized prompts/agents

Installation

The ralphex CLI is the primary interface. Skills (/ralphex, /ralphex-plan, and /ralphex-update) are optional convenience commands.

Via Plugin Marketplace (Recommended)

# Add ralphex marketplace
/plugin marketplace add kulebyaka/ralphex_cp

# Install the plugin
/plugin install ralphex@kulebyaka-ralphex_cp

Benefits: Auto-updates when marketplace refreshes (at startup).

Manual Installation (Alternative)

The slash command definitions are hosted at:

• /ralphex
• /ralphex-plan
• /ralphex-update

To install, ask Claude Code to "install ralphex slash commands" or manually copy the files to ~/.claude/commands/.

Usage

Once installed:

# in conversation
/ralphex-plan add user authentication    # creates plan interactively
/ralphex docs/plans/auth.md              # launches execution
"check ralphex"                          # gets status update

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.

Note: Running from a standalone terminal is recommended for the best experience.

For LLMs

See llms.txt for LLM-optimized documentation.

License

MIT License - see LICENSE file.