使用 Claude Code 的自主计划执行

ralphex 是一款独立的命令行工具，可在 Git 仓库根目录下的终端中运行。它通过协调 Claude Code 自主执行实现计划——无需 IDE 插件或云服务，只需 Claude Code 和一个二进制文件即可。

Claude Code 功能强大，但需要交互式操作：您必须实时观察、批准并指导每一步。对于涉及多个任务的复杂功能，这意味着需要花费数小时进行全程监控。更糟糕的是，在长时间会话中，上下文信息不断累积，模型的表现会逐渐下降——它可能会开始犯错、忘记之前的决策，从而生成质量较差的代码。

ralphex 则同时解决了这两个问题。每个任务都在全新的 Claude Code 会话中执行，上下文信息极少，因此在整个计划执行过程中，模型都能保持高效。只需编写包含任务和验证命令的计划，启动 ralphex，然后就可以离开。稍后再回来查看，您的功能已经实现、经过审查并提交到版本库；或者您可以查看进度日志，了解当前的执行情况。

特性

• 零配置 - 开箱即用，采用合理默认值，无需任何配置
• 自主任务执行 - 按照计划逐个执行任务，并自动重试
• 交互式计划创建 - 通过 --plan 标志与 Claude 进行对话式创建计划
• 多阶段代码审查 - 包括 5 个代理 → codex → 2 个代理的审查流程
• 自定义审查代理 - 可通过 {{agent:name}} 模板系统和用户自定义提示进行配置
• 自动分支创建 - 根据计划文件名创建 Git 分支
• 计划完成跟踪 - 将已完成的计划移动到 completed/ 文件夹
• 自动提交 - 在每个任务和审查修复后自动提交
• 实时监控 - 流式输出，带有时间戳、颜色和详细日志
• Web 控制台 - 使用 --serve 标志可提供基于浏览器的实时视图
• Docker 支持 - 在隔离容器中运行，以实现更安全的自主执行
• 通知功能 - 可选择通过 Telegram、电子邮件、Slack、Webhook 或自定义脚本在完成/失败时接收提醒
• 工作树隔离 - 使用 --worktree 标志可并行运行多个计划
• 多种模式 - 完全执行、仅执行任务、仅审查、仅外部审查，或仅创建计划

快速入门

请确保已安装 ralphex，并且您的项目是一个 Git 仓库。您需要在 docs/plans/ 中准备一个计划文件，例如：

# 计划：我的功能

## 验证命令
- `go test ./...`

### 任务 1：实现功能
- [ ] 添加新功能
- [ ] 添加测试

然后运行：

ralphex docs/plans/my-feature.md

ralphex 将创建一个分支，执行任务，提交结果，进行多阶段审查，并在完成后将计划移动到 completed/ 文件夹。

工作原理

ralphex 按照四个阶段执行计划，并进行自动化代码审查，最后还有一个可选的收尾步骤。

第一阶段：任务执行

1. 读取计划文件，找到第一个未完成的任务（格式为 ### Task N:，带有 - [ ] 复选框）
2. 将任务发送给 Claude Code 执行
3. 每个任务完成后运行验证命令（如测试、代码检查工具）
4. 将复选框标记为已完成 [x]，并提交更改
5. 重复上述步骤，直到所有任务完成或达到最大迭代次数

中途控制： 在任务执行过程中，按下 Ctrl+\ (SIGQUIT) 可暂停执行。ralphex 会取消当前的 Claude 会话，并提示“按 Enter 继续，Ctrl+C 中止”。暂停期间，您可以编辑计划文件——按下 Enter 后，同一任务将以全新会话重新执行，并再次读取计划。按下 Ctrl+C 可干净地中止。此功能在 Windows 上不可用。

第二阶段：首次代码审查

通过 Claude Code 的 Task 工具并行启动 5 个审查代理：

Claude 会核实审查结果，修复确认的问题，并提交更改。

默认代理 提供通用的、与语言无关的审查步骤。它们可以根据您的具体需求、使用的编程语言和工作流程进行自定义和调整。有关详细信息，请参阅自定义部分。

第三阶段：外部审查（可选）

1. 运行外部审查工具（默认为 codex，也可使用自定义脚本）
2. Claude 评估审查结果，修复有效问题
3. 重复上述步骤，直到没有未解决的问题

循环将在以下情况下终止：所有问题均已解决、达到最大迭代次数、检测到僵局（通过 --review-patience 设置）或手动中断（按下 Ctrl+\ (SIGQUIT)）。

僵局检测： 当外部工具和 Claude 对审查结果无法达成一致时，循环可能会浪费大量 token 不断迭代至最大次数。设置 --review-patience=N（或在配置中设置 review_patience），以便在连续 N 轮没有提交或工作树发生变化时终止循环。

手动中断： 在外部审查循环中按下 Ctrl+\ (SIGQUIT) 可立即终止该循环。当前的执行过程将通过上下文取消而被终止。而在任务阶段，Ctrl+\ 则用于暂停执行——请参阅第一阶段：任务执行。此功能在 Windows 上不可用。

支持的工具：

• codex（默认）：OpenAI Codex，用于独立代码审查
• 自定义：您自己的脚本，可封装任何 AI（如 OpenRouter、本地 LLM 等）
• 无：完全跳过外部审查

有关如何使用自定义脚本的详细信息，请参阅自定义外部审查。

第四阶段：第二次代码审查

1. 启动 2 个代理（quality + implementation）进行最终审查
2. 重点关注关键或重大问题
3. 重复上述步骤，直到没有发现任何问题
4. 成功完成后，将计划移至 completed/ 文件夹

第二次审查代理可通过 prompts/review_second.txt 进行配置。

最终步骤（可选）

在所有评审阶段成功完成后，ralphex 可以运行一个可选的最终步骤。默认情况下此功能已禁用。

作用： 运行一次 Claude Code 会话，并使用可自定义的提示模板。默认的 finalize.txt 提示模板会将提交变基到默认分支上，并可选择性地将相关提交压缩成逻辑组。

如何启用：

在 ~/.config/ralphex/config 或 .ralphex/config 中设置 finalize_enabled = true。

行为：

• 只运行一次（没有迭代循环）
• 尽最大努力——失败会被记录，但不会阻止整体成功
• 在具有评审流水线的模式下触发：完整模式、仅评审模式、仅外部模式
• 使用任务颜色（绿色）输出

自定义：

编辑 ~/.config/ralphex/prompts/finalize.txt（或 .ralphex/prompts/finalize.txt），以更改评审后的操作。例如：推送到远程仓库、发送通知、运行部署脚本，或任何完成后的自动化流程。模板变量如 {{DEFAULT_BRANCH}} 均可使用。

仅评审模式

仅评审模式（--review）会对当前分支上已有的更改运行完整的评审流水线（阶段 2 → 阶段 3 → 阶段 4）。当更改是在 ralphex 外部进行时——例如通过 Claude Code 的内置计划模式、手动编辑、其他 AI 代理，或任何其他工作流——此模式非常有用。

工作流程：

1. 在特性分支上进行更改（使用任何工具或工作流）
2. 提交更改
3. 运行 ralphex --review

ralphex 会将该分支与默认分支进行比较（git diff master...HEAD），启动多智能体评审，并迭代修复直到所有智能体都报告无问题。无需提供计划文件——如果提供了，它将为评审者提供关于预期更改的额外上下文。

# 切换到包含现有更改的特性分支
git checkout feature-auth

# 对这些更改运行评审流水线
ralphex --review

# 可选地传递一个计划文件以提供上下文
ralphex --review docs/plans/add-auth.md

工作树隔离

--worktree 标志会在 .ralphex/worktrees/<branch> 下的一个隔离 Git 工作树中运行计划执行，从而允许在同一仓库上并行执行多个计划，而不会发生分支冲突。

支持的模式： --worktree 仅适用于完整模式和 --tasks-only 模式。对于 --review、--external-only 和 --plan 模式，此标志会被静默忽略——这些模式直接在当前目录中运行。

在工作树分支上重新运行评审： 如果任务阶段已在工作树中完成，但需要重新运行评审阶段，则可以进入工作树目录并在那里运行评审：

# 查找工作树
ls .ralphex/worktrees/

# 从工作树内部运行评审
cd .ralphex/worktrees/my-feature-branch
ralphex --review
# 或
ralphex --external-only

工作树会在成功完成时自动删除。如果运行被中断，工作树目录可能会保留下来，可以再次使用或手动删除。

计划创建

计划可以通过多种方式创建：

• Claude Code - 使用斜杠命令，如 /ralphex-plan，或您自己的规划工作流
• 手动 - 直接在 docs/plans/ 中编写 Markdown 文件
• --plan 标志 - 集成选项，可处理整个流程
• 自动检测 - 如果在 master/main 分支上不带参数运行 ralphex，且没有计划存在，则会提示创建计划

--plan 标志提供了一个更简单的集成体验：

ralphex --plan "添加健康检查端点"

Claude 会探索您的代码库，通过终端选择器（fzf 或数字回退）提出澄清问题，并在 docs/plans/ 中生成一个完整的计划文件。在审查草稿时，您可以接受、通过文本反馈进行修改、在 $EDITOR 中打开以进行交互式注释，或拒绝该计划。

示例会话：

$ ralphex --plan "为 API 响应添加缓存"
[10:30:05] 分析代码库结构...
[10:30:12] 发现 pkg/store/ 中已有存储层

问题：使用哪种缓存后端？
  > Redis
    内存缓存
    文件缓存
    其他（输入您自己的答案）

[10:30:45] 回答：Redis
[10:31:00] 继续创建计划...
[10:32:05] 计划已写入 docs/plans/add-api-caching.md

是否继续执行计划？
  > 是，执行计划
    否，退出

计划创建完成后，您可以选择立即执行计划，或退出以便稍后再运行 ralphex。进度会记录在 .ralphex/progress/progress-plan-<name>.txt 中。

安装

从源码安装

go install github.com/umputun/ralphex/cmd/ralphex@latest

使用 Homebrew

brew install umputun/apps/ralphex

从发布版本下载

从 releases 下载合适的二进制文件。

使用 Docker

下载包装脚本并安装到 PATH 中：

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

该脚本默认使用 Go 镜像（ralphex-go）。对于其他语言，您可以基于基础镜像构建自定义镜像，并在其中安装您的工具链（示例请参见 可用镜像），然后通过以下环境变量指向该镜像：

export RALPHEX_IMAGE=my-ralphex

之后即可正常使用 ralphex，它会在一个预装了 Claude Code 和 Codex 的容器中运行。脚本启动时会显示当前使用的镜像。

为什么使用 Docker？ ralphex 以 --dangerously-skip-permissions 参数运行 Claude Code，这使其拥有执行命令和修改文件的完全权限。而在容器中运行可以提供隔离——Claude 只能访问挂载的项目目录，而无法触及您的整个系统。这种机制使得自主执行变得更加安全。

卷挂载：

• 只读：~/.claude 和 ~/.codex 挂载到 /mnt/，启动时复制以保持隔离
• 读写：项目目录（/workspace）——ralphex 在此创建分支、编辑代码并提交
• 额外挂载：通过 -v/--volume 标志或 RALPHEX_EXTRA_VOLUMES 环境变量指定的自定义卷

要求：

• Python 3.9 或更高版本（用于包装脚本）
• 已安装并运行的 Docker
• ~/.claude/ 中的 Claude Code 凭据（或在设置了 $CLAUDE_CONFIG_DIR 时使用该目录）
• ~/.codex/ 中的 Codex 凭据（可选，用于 Codex 审查阶段）
• ~/.gitconfig 中的 Git 配置（用于提交）

环境变量：

• RALPHEX_IMAGE——要使用的 Docker 镜像（默认：ghcr.io/umputun/ralphex-go:latest）
• RALPHEX_PORT——使用 --serve 时 Web 仪表盘的端口（默认：8080）
• RALPHEX_CONFIG_DIR——自定义配置目录（默认：~/.config/ralphex）。覆盖全局配置位置，用于提示词、代理和设置
• CLAUDE_CONFIG_DIR——Claude 配置目录（默认：~/.claude）。可用于替代的 Claude 安装路径（例如 ~/.claude2）。无论是在 Docker 包装器中（通过卷挂载和钥匙串派生）还是非 Docker 使用场景中（直接传递给 Claude Code），都能正常工作。钥匙串服务名称会根据路径自动派生。
• RALPHEX_EXTRA_VOLUMES——额外的卷挂载，以逗号分隔（例如 /data:/mnt/data:ro,/models:/mnt/models）。未包含冒号的条目将被静默忽略。
• RALPHEX_EXTRA_ENV——额外的环境变量，以逗号分隔（例如 DEBUG=1,API_KEY）。格式为 VAR=value 或 VAR（从宿主机继承）。对于包含敏感名称（KEY、SECRET、TOKEN 等）且显式赋值的情况，会发出安全警告——建议仅使用变量名形式来传递敏感凭据。
• RALPHEX_DOCKER_SOCKET——启用 Docker 套接字挂载：1、true 或 yes（仅限 Docker 包装器）。命令行标志：--docker
• RALPHEX_DOCKER_NETWORK——Docker 网络模式（例如 host、my-network）。适用于访问 docker-compose 服务。命令行标志：--network
• TZ——覆盖容器时区（默认：根据 /etc/localtime 自动检测宿主机时区）。示例：TZ=Europe/Berlin ralphex docs/plans/feature.md
• RALPHEX_CLAUDE_PROVIDER——Claude 提供商模式：default 或 bedrock（仅限 Docker 包装器）

Docker 套接字支持：

--docker 标志（或 RALPHEX_DOCKER_SOCKET=1）会将宿主机的 Docker 套接字挂载到容器中，从而支持 testcontainers 和依赖 Docker 的工作流：

ralphex --docker docs/plans/feature.md
ralphex --docker --dry-run   # 验证套接字挂载是否成功

• 自动检测套接字的 GID，并传递 DOCKER_GID 环境变量以便在基础镜像中设置组权限
• 在 Linux 系统上会发出安全警告（macOS 由于虚拟机隔离，无需警告）
• 如果套接字文件不存在，则会立即报错（快速失败，不会出现无声降级）

AWS Bedrock 支持：

当设置 --claude-provider bedrock 或 RALPHEX_CLAUDE_PROVIDER=bedrock 时：

• 将跳过钥匙串凭据提取步骤（Bedrock 认证不需要）
• AWS 凭据会通过 aws configure export-credentials 自动从 AWS_PROFILE 中导出
• 必要的 Bedrock 环境变量会被传递到容器中：CLAUDE_CODE_USE_BEDROCK、AWS_REGION 以及相关凭据

Bedrock 所需的环境变量：

• AWS_REGION——Bedrock 已启用的 AWS 地区
• AWS_PROFILE 或 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY——认证信息

注意：使用 --claude-provider bedrock 时，会自动设置 CLAUDE_CODE_USE_BEDROCK=1。

# 使用 AWS 配置文件（凭据会自动导出）
export AWS_PROFILE=my-bedrock-profile
export AWS_REGION=us-east-1
ralphex --claude-provider bedrock docs/plans/feature.md

# 或者使用环境变量进行会话范围的设置
export RALPHEX_CLAUDE_PROVIDER=bedrock
ralphex docs/plans/feature.md

有关详细的 IAM 策略和设置说明，请参阅 Bedrock 设置文档。

额外的卷挂载：

# 通过 CLI 标志（可多次使用 -v）
ralphex -v /data:/mnt/data:ro -v /models:/mnt/models docs/plans/feature.md

# 通过环境变量（以逗号分隔）
RALPHEX_EXTRA_VOLUMES="/data:/mnt/data:ro,/models:/mnt/models" ralphex docs/plans/feature.md

额外的环境变量：

# 通过 CLI 标志（可多次使用 -E）
ralphex -E DEBUG=1 -E API_KEY docs/plans/feature.md

# 通过环境变量（以逗号分隔）
RALPHEX_EXTRA_ENV="DEBUG=1,LOG_LEVEL=verbose" ralphex docs/plans/feature.md

# 仅使用变量名的形式会从宿主机继承值（推荐用于敏感信息）
export API_KEY=secret123
ralphex -E API_KEY docs/plans/feature.md

# 包含逗号的值需要使用 -E 标志（环境变量按逗号分隔）
ralphex -E "TAGS=foo,bar,baz" docs/plans/feature.md

调试：

ralphex --dry-run docs/plans/feature.md  # 显示 docker 命令但不执行

--dry-run 标志会打印出原本要执行的完整 docker run 命令。这在调试容器配置或复制命令以手动执行时非常有用。

注意：继承的环境变量（例如 -E FOO 而没有 =value）在将命令复制到不同 shell 中时可能无法正常工作。为了保证可移植性，请使用显式指定的值。

更新：

ralphex --update         # 拉取最新的 Docker 镜像
ralphex --update-script  # 更新包装脚本本身

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

FROM ghcr.io/umputun/ralphex:latest

# 从官方渠道安装 Go
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"

# 安装 Go 工具
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

FROM ghcr.io/umputun/ralphex: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"

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

带有自定义端口的示例：

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

使用方法

注意： ralphex 必须从仓库根目录（即 .git 所在的目录）运行。

# 执行计划，包含任务循环和评审
ralphex docs/plans/feature.md

# 使用 fzf 选择计划，或在没有计划时交互式创建一个
ralphex

# 仅评审模式（跳过任务执行）
ralphex --review docs/plans/feature.md

# 仅外部评审模式（跳过任务和首次评审，只运行外部评审循环）
ralphex --external-only

# 仅任务模式（只运行任务阶段，跳过所有评审）
ralphex --tasks-only docs/plans/feature.md

# 在隔离的 Git 工作树中运行（仅限完整模式和任务模式）
ralphex --worktree docs/plans/feature.md

# 覆盖默认分支以进行评审差异比较
ralphex --review --base-ref develop
ralphex --review --base-ref abc1234 --skip-finalize

# 初始化当前项目的本地 .ralphex/ 配置文件（包含注释掉的默认值）
ralphex --init

# 交互式创建计划
ralphex --plan "添加用户认证"

# 使用自定义最大迭代次数
ralphex --max-iterations=100 docs/plans/feature.md

# 限制外部评审的迭代次数（0 表示自动计算，基于最大迭代次数）
ralphex --max-external-iterations=5 docs/plans/feature.md

# 当连续 3 轮评审结果未变化时终止外部评审（僵局检测）
ralphex --review-patience=3 docs/plans/feature.md

# 在达到速率限制时等待并重试，而不是直接退出
ralphex --wait 1h docs/plans/feature.md

# 设置会话超时时间，以结束挂起的 Claude 会话
ralphex --session-timeout 30m docs/plans/feature.md

# 当 Claude 会话 5 分钟内无输出时终止会话（空闲检测）
ralphex --idle-timeout 5m docs/plans/feature.md

# 启用 Web 控制台
ralphex --serve docs/plans/feature.md

# 在自定义端口上启用 Web 控制台
ralphex --serve --port 3000 docs/plans/feature.md

选项

计划文件格式

计划是包含任务部分的 Markdown 文件。每个任务都有复选框，由 claude 标记为已完成。

# 计划：添加用户认证

## 概述
为 API 添加基于 JWT 的认证。

## 验证命令
- `go test ./...`
- `golangci-lint run`

### 任务 1：添加认证中间件
- [ ] 创建 JWT 验证中间件
- [ ] 添加到受保护路由的路由器
- [ ] 添加测试
- [ ] 标记完成

### 任务 2：添加登录端点
- [ ] 创建 /api/login 处理程序
- [ ] 在认证成功时返回 JWT
- [ ] 添加测试
- [ ] 标记完成

要求：

• 任务标题必须使用 ### Task N: 或 ### Iteration N: 格式（N 可以是整数或非整数，如 2.5, 2a）
• 复选框：- [ ]（未完成）或 - [x]（已完成）
• 复选框只能出现在任务部分（### Task N: 或 ### Iteration N:）。不要在成功标准、概述或上下文中放置复选框——它们会导致额外的循环迭代。代理在遇到这些复选框时会优雅地处理，但为了最佳效果，计划作者应避免使用它们。
• 包含 ## 验证命令 部分，并列出测试/静态分析命令
• 将计划放在 docs/plans/ 目录中（可通过 plans_dir 配置）

评审代理

评审流程完全可定制。ralphex 提供了适用于任何语言的合理默认设置，但您可以根据自己的工作流程修改代理、添加新代理或完全替换提示词。

默认代理

这 5 个代理涵盖了常见的评审关注点，开箱即用效果良好。您可以根据需要自定义或替换它们：

代理选项（YAML 前言）

代理文件支持可选的 YAML 前言，用于代理的个性化配置：

---
model: haiku
agent: code-reviewer
---
审查代码中的质量问题……

这两个选项均为可选。如果没有前言，代理将使用默认模型和 general-purpose 子代理类型。完整的模型 ID（如 claude-sonnet-4-5-20250929）会被标准化为简短关键词（sonnet），因为 Claude Code 只接受 haiku、sonnet 和 opus。无效的模型值将被忽略，并发出警告。

模板语法

自定义提示文件支持变量扩展。所有变量均采用 {{VARIABLE}} 语法。

可用变量：

代理引用：

在提示文件中使用 {{agent:name}} 语法引用代理：

并行启动以下评审代理：
{{agent:quality}}
{{agent:implementation}}
{{agent:testing}}

每个 {{agent:name}} 都会展开为 Task 工具指令，指示 Claude Code 运行该代理。代理内容中的变量也会被展开，因此代理可以使用 {{DEFAULT_BRANCH}} 或其他变量。

自定义

整个系统专为自定义而设计，无论是任务执行还是评审：

代理文件（~/.config/ralphex/agents/）：

• 首次运行时，ralphex 会安装 5 个默认的代理文件作为注释掉的模板。这些文件仅作为示例——虽然完全被注释掉，但它们并不会生效，实际使用的是内置的默认设置。取消注释并编辑即可进行自定义。
• 每个代理都有文件级回退机制：ralphex 会依次检查本地 .ralphex/agents/ → 全局 ~/.config/ralphex/agents/ → 内置默认设置。内置的 5 个代理始终是基础配置——即使从磁盘上删除某个代理文件，也不会禁用它，系统仍会使用内置版本作为回退。
• 若要禁用特定代理，只需将其 {{agent:name}} 引用从提示文件中移除（如 review_first.txt、review_second.txt），而无需删除代理文件本身。
• 可以添加新的 .txt 文件来创建自定义代理，并在提示文件中通过 {{agent:name}} 引用它们。
• 运行 ralphex --init 可以创建包含注释默认值的本地 .ralphex/ 项目配置。
• 运行 ralphex --reset 可以交互式地恢复默认设置，或手动删除所有文件。
• 运行 ralphex --dump-defaults <dir> 可以提取原始默认设置以便比较。
• 使用 /ralphex-update Claude Code 技能可以将更新后的默认设置智能合并到自定义文件中。
• 或者，也可以直接在提示文件中引用已安装在 Claude Code 中的代理（见下文示例）。

提示文件（~/.config/ralphex/prompts/）：

• task.txt - 任务执行提示
• review_first.txt - 综合评审（默认：5 个语言无关的代理——质量、实现、测试、简化、文档；可自定义）
• codex.txt - Codex 评估提示（Claude 评估 Codex 的输出）
• codex_review.txt - Codex 评审提示（发送至 Codex 外部评审工具）
• custom_review.txt - 自定义外部评审提示（发送至自定义评审脚本）
• custom_eval.txt - 自定义评估提示（Claude 评估自定义工具的输出）
• review_second.txt - 最终评审，仅关注关键/重大问题（默认：2 个代理——质量、实现；可自定义）
• make_plan.txt - 交互式计划创建提示
• finalize.txt - 可选的最终步骤提示（默认关闭）

注释行和 Markdown 标题： 文件顶部连续出现 2 行及以上的注释行（以 # 开头）会被视为元注释，并在加载时被移除。而文件顶部单独的一行 # 标题 则会被保留（被视为 Markdown 标题）。文件主体中后续出现的注释行则会始终保留：

# 这一行标题会被保留为 Markdown 标题
检查 SQL 注入
# 这条位于文件中间的注释也会被保留
检查 XSS

如果文件仅包含注释行（每行都以 # 开头），则会被视为未修改的模板，并回退到内置默认设置。这就是注释掉的默认文件的工作方式——一旦添加任何非注释内容，文件就会按原样使用。

注意：不支持内联注释（text # comment 会保留整行内容）。

示例：

• 为金融科技项目添加一个专注于安全的代理。
• 如果不担心过度工程化，可以从提示文件中移除 {{agent:simplification}}。
• 创建针对特定语言的代理（如 Python 代码风格检查、TypeScript 类型检查）。
• 修改提示以调整每个阶段运行的代理数量。

直接使用 Claude Code 代理：

无需创建代理文件，可以直接在提示文件中引用已安装在 Claude Code 中的代理：

# 在 review_first.txt 中，只需列出代理名称及其提示
要启动的代理：
1. qa-expert - “审查 bug 和安全问题”
2. go-test-expert - “审查测试覆盖率和质量”
3. go-smells-expert - “审查代码异味”

要求

• claude - Claude Code CLI
• fzf - 用于选择计划（可选）
• codex - 用于外部评审（可选）

配置

ralphex 使用位于 ~/.config/ralphex/ 的配置目录（可通过 --config-dir 或 RALPHEX_CONFIG_DIR 覆盖），其结构如下：

~/.config/ralphex/
├── config              # 主配置文件（INI 格式）
├── prompts/            # 自定义提示模板
│   ├── task.txt
│   ├── review_first.txt
│   ├── review_second.txt
│   ├── codex.txt
│   ├── codex_review.txt
│   ├── custom_review.txt
│   ├── custom_eval.txt
│   ├── make_plan.txt
│   └── finalize.txt
└── agents/             # 自定义评审代理（*.txt 文件）

首次运行时，ralphex 会创建该目录并配备默认配置。

注释模板：

• 配置文件的所有内容都被注释掉（以 # 为前缀）。
• 只需取消您想要自定义的设置的注释。
• 如果文件始终保持全部注释状态，则会在新默认设置发布时自动更新。
• 一旦取消对某项设置的注释，该文件将被保留，不会被覆盖。

本地项目配置

项目可以在项目根目录下创建 .ralphex/ 目录来覆盖全局设置。运行 ralphex --init 即可创建一个包含注释默认值的目录：

project/
├── .ralphex/           # 可选，项目本地配置
│   ├── config          # 覆盖特定设置
│   ├── prompts/        # 该项目的自定义提示
│   └── agents/         # 该项目的自定义代理

优先级：CLI 标志 > 本地 .ralphex/ > 全局 ~/.config/ralphex/ > 内置默认设置

使用 --config-dir 或 RALPHEX_CONFIG_DIR 可以覆盖全局配置的位置。这对于为不同工作流维护独立的代理/提示集合非常有用。

合并行为：

• 配置文件：逐字段覆盖（本地值优先于全局值，缺失字段则回退）
• 提示文件：文件级回退（本地 → 全局 → 内置，默认值，每个提示文件独立）
• 代理文件：文件级回退（本地 → 全局 → 内置，默认值，每个代理文件独立，与提示文件相同）

配置选项

颜色使用 24 位 RGB（真彩色），所有现代终端（iTerm2、Kitty、Terminal.app、Windows Terminal、GNOME 终端、Alacritty、Zed、VS Code 等）均原生支持。旧版终端会优雅降级。使用 --no-color 可完全禁用颜色。

错误模式采用不区分大小写的子字符串匹配。当在 Claude 或 Codex 输出中检测到模式时，ralphex 会优雅退出，并显示提示信息，建议如何检查使用情况或状态。多个模式用逗号分隔，每个模式前后会去除空格。

限流重试： 限流模式（claude_limit_patterns、codex_limit_patterns）功能类似，但支持可选的等待+重试行为。当设置了 --wait（或配置中的 wait_on_limit）时，匹配限流模式会触发等待，随后自动重试，而不是直接退出。如果没有 --wait，限流模式将退化为错误模式的行为。限流模式会在错误模式之前被检查——如果同一字符串同时匹配两者，则在启用等待时，限流模式优先。

自定义提示

将自定义提示文件放置在 ~/.config/ralphex/prompts/ 目录下，以覆盖内置提示。缺失的文件将回退到嵌入式默认值。有关代理自定义，请参阅“审查代理”部分。

自定义外部审查

使用您自己的 AI 工具进行外部代码审查，而非 Codex。这允许与 OpenRouter、本地 LLM 或任何自定义流程集成。

配置：

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

脚本接口：

您的脚本接收一个参数：包含审查指令的提示文件路径。脚本将发现结果输出到 stdout，ralphex 将其传递给 Claude 进行评估和修复。

#!/bin/bash
# 示例：~/.config/ralphex/scripts/my-review.sh
prompt_file="$1"

# 读取提示（包含差异指令、目标、审查重点）
prompt=$(cat "$prompt_file")

# 调用您的 AI 工具（OpenRouter、本地 LLM 等）
# 以 curl 调用 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'

预期输出格式：

• 将发现结果以结构化列表形式写入 stdout
• 格式为：文件:行 - 问题描述
• 如果没有问题，则输出 NO ISSUES FOUND

迭代行为：

外部审查循环默认最多运行 max(3, max_iterations/5) 次迭代。可通过 max_external_iterations 配置选项或 --max-external-iterations CLI 标志进行覆盖（0 = 自动）。

提示中的 {{DIFF_INSTRUCTION}} 变量会根据每次迭代调整：

• 第一次迭代：git diff main...HEAD（功能分支中的所有更改）
• 后续迭代：git diff（仅包含上次修复后的未提交更改）

这样可以让审查工具专注于修复后剩余的问题。

通知

ralphex 可在执行完成或失败时发送通知。通知为可选，默认关闭，且为尽力而为的服务——失败会被记录，但绝不会影响退出代码。

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

支持的通道：telegram、email、slack、webhook、custom（脚本）。配置错误的通道会在启动时被检测到。

请参阅通知文档，了解设置指南、消息格式示例以及自定义脚本集成方法。

提示自定义：

通过自定义 ~/.config/ralphex/prompts/custom_review.txt 来修改发送给您的脚本的提示。可用变量：

• {{DIFF_INSTRUCTION}} - 当前迭代适用的 git diff 命令
• {{GOAL}} - 正在实现的内容的人类可读描述
• {{PLAN_FILE}} - 计划文件的路径
• {{PROGRESS_FILE}} - 包含先前评审迭代的进度日志文件路径
• {{DEFAULT_BRANCH}} - 检测到的默认分支（main、master 等）
• {{PREVIOUS_REVIEW_CONTEXT}} - 上一次评审上下文（首次迭代为空，后续会填充）

通过自定义 ~/.config/ralphex/prompts/custom_eval.txt 来修改 Claude 如何评估您工具的输出。

Docker 注意事项：

在 Docker 中运行 ralphex 时，您的脚本必须在容器内可访问：

• 挂载您的脚本目录：-v ~/.config/ralphex/scripts:/home/app/.config/ralphex/scripts:ro
• 确保脚本依赖项可用（curl、jq 等包含在基础镜像中）
• 必须将环境变量（API 密钥）传递给容器：-e OPENROUTER_API_KEY

使用替代提供商进行 Claude 阶段

claude_command 和 claude_args 配置选项允许您用任何能产生兼容 stream-json 输出的 CLI 替换 Claude Code。这意味着 codex、Gemini CLI、本地 LLM 或其他工具都可以驱动任务执行和评审阶段——您只需要一个能够转换工具输出格式的包装脚本。

提供了一个可用示例：scripts/codex-as-claude/codex-as-claude.sh 包装了 codex，以生成与 Claude 兼容的事件。要使用它：

# 在 ~/.config/ralphex/config 或 .ralphex/config 中
claude_command = /path/to/codex-as-claude.sh
claude_args =

将 claude_args 设置为空是可选的。请注意，由于配置回退行为，默认的 Claude 标志（--dangerously-skip-permissions、--output-format stream-json、--verbose）仍可能被传递。包装脚本应优雅地忽略未知标志——附带的脚本通过其 *) shift ;; 通配符来实现这一点。

该包装脚本支持以下环境变量：

• CODEX_MODEL - 要使用的 codex 模型（默认：codex 默认模型）
• CODEX_SANDBOX - 沙盒模式（默认：danger-full-access）
• CODEX_VERBOSE - 设置为 1 可以将命令执行输出包含在流中（默认：0，仅显示代理消息）

请参阅自定义提供商文档，获取编写其他提供商包装脚本的详细指南。

可配置的 VCS 后端

ralphex 可以通过 vcs_command 配置选项和自定义提示文件与 Mercurial 仓库配合使用。

# 在 ~/.config/ralphex/config 或 .ralphex/config 中
vcs_command = ~/.config/ralphex/scripts/hg2git.sh

参考转换脚本位于 scripts/hg2git/hg2git.sh。它将 ralphex 内部使用的约 15 个 git 子命令映射到 Mercurial 的等效命令，并采用基于阶段的提交逻辑（草稿阶段修正，公开阶段提交）。需要 bash 4.0+（用于解析差异统计信息的关联数组）。

您还需要自定义提示文件，以替换 Claude 在评审期间作为 bash 命令执行的 git 命令。请参阅Mercurial 支持文档，获取完整的设置说明、提示替换示例、.hgignore 设置以及已知限制。

步骤 3 - 完成（验证通过后）：
- ...现有步骤...
- 如果整个计划中不再有 [ ] 复选框，则进入步骤 4

步骤 4 - 风格检查（仅当所有任务完成时）：
- 使用 /smells 技能分析此分支上所有已更改的文件
- 修复所有报告的风格和代码质量问题
- 再次运行测试和 linter 以验证修复效果
- 如果有任何修复，则提交：fix: 解决代码异味问题
- 输出内容为：<<<RALPHEX:ALL_TASKS_DONE>>>

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

claude_command = agent
claude_args = --force --output-format stream-json

claude_command = /path/to/codex-as-claude.sh
claude_args =

CLAUDE_CONFIG_DIR=~/.claude2 ralphex docs/plans/feature.md

Web 仪表板

--serve 标志会启动一个基于浏览器的仪表板，用于实时监控计划的执行情况。

ralphex --serve docs/plans/feature.md
# web 仪表板：http://localhost:8080

功能特性

• 实时流式传输 - 使用 SSE 连接实现实时输出更新
• 阶段导航 - 按全部/任务/评审/Codex 阶段进行筛选
• 可折叠区块 - 输出内容有序组织，支持展开/折叠
• 文本搜索 - 支持高亮显示搜索结果（键盘：/ 聚焦，Escape 清除）
• 自动滚动 - 自动跟随输出内容，点击可关闭
• 中途加入支持 - 新客户端可接收完整历史记录

仪表板采用深色主题，并为不同阶段分配与终端输出相匹配的颜色。使用 --serve 时，所有文件和标准输出日志记录均保持不变。

多会话模式

通过 --watch 标志可同时监控多个 ralphex 会话：

# 监控特定目录中的进度文件
ralphex --serve --watch ~/projects/frontend --watch ~/projects/backend

# 在配置文件中设置监控目录
# watch_dirs = /home/user/projects, /var/log/ralphex

多会话功能：

• 会话侧边栏 - 列出所有已发现的会话，点击即可切换（键盘：S 切换）
• 活动检测 - 通过文件锁机制为正在运行的会话显示脉冲指示
• 自动发现 - 新会话启动时会自动显示

Claude Code 集成（可选）

ralphex 可以独立在终端中运行。您也可以选择将斜杠命令添加到 Claude Code 中，以获得更一体化的体验。

可用命令

安装

ralphex CLI 是主要界面。Claude Code 技能（/ralphex、/ralphex-plan 和 /ralphex-update）是可选的便捷命令。

通过插件市场安装（推荐）

# 添加 ralphex 插件市场
/plugin marketplace add umputun/ralphex

# 安装插件
/plugin install ralphex@umputun-ralphex

优势：当插件市场刷新时（Claude Code 启动时），插件会自动更新。

手动安装（替代方案）

斜杠命令的定义托管在以下地址：

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

要安装，您可以要求 Claude Code “安装 ralphex 斜杠命令”，或者手动将这些文件复制到 ~/.claude/commands/ 目录下。

使用方法

安装完成后：

# 在 Claude Code 对话中
/ralphex-plan add user authentication    # 交互式创建计划
/ralphex docs/plans/auth.md              # 启动执行
“check ralphex”                          # 获取状态更新

/ralphex 命令会在后台运行 ralphex，并根据请求提供状态更新。/ralphex-plan 命令则会引导您完成结构化的计划创建，包括上下文发现和方案选择。

注意： ralphex 会自动从子进程中移除 CLAUDECODE 环境变量，从而允许它在 Claude Code 内部运行。不过，为了获得最佳体验，仍建议在独立终端中运行。如果遇到嵌套会话错误，ralphex 会通过错误模式匹配检测到该问题，并优雅地退出。

针对 LLMs 的说明

有关针对 LLM 优化的文档，请参阅 llms.txt。

许可证

MIT 许可证 - 请参阅 LICENSE 文件。

Ralphex 快速上手指南

Ralphex 是一个独立的命令行工具，旨在让 Claude Code 自主执行开发计划。它无需 IDE 插件或云服务，即可在终端中自动完成任务执行、代码审查、提交和分支管理，解决长会话中上下文溢出导致模型质量下降的问题。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows (部分交互功能如 Ctrl+\ 在 Windows 上不可用)。
• Git 仓库：当前项目必须初始化为 Git 仓库。
• 核心依赖：
  • Claude Code：必须已安装并配置好 API Key。Ralphex 依赖它来执行具体编码任务。
  • Go 语言环境 (仅源码安装时需要)。
• 可选依赖：
  • Docker：如果需要隔离运行环境。
  • fzf：用于计划创建时的交互式选择（非必需，有降级方案）。

安装步骤

你可以选择以下任一方式进行安装：

方式一：使用 Go 安装（推荐）

如果你已安装 Go 环境：

go install github.com/umputun/ralphex/cmd/ralphex@latest

方式二：使用 Homebrew (macOS)

brew install umputun/apps/ralphex

方式三：下载二进制文件

访问 Releases 页面 下载对应系统的二进制文件，解压后将其放入 $PATH 目录中。

方式四：使用 Docker

下载官方包装脚本并赋予执行权限：

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

注：国内用户若下载脚本缓慢，可手动下载脚本内容后保存为 /usr/local/bin/ralphex。

基本使用

1. 创建计划文件

在项目根目录下创建 docs/plans/ 文件夹，并新建一个 Markdown 格式的计划文件（例如 my-feature.md）。

文件内容示例：

# Plan: My Feature

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

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

2. 执行计划

在终端运行以下命令启动 Ralphex：

ralphex docs/plans/my-feature.md

执行流程：

1. 自动建支：根据文件名创建新的 Git 分支。
2. 任务执行：调用 Claude Code 逐个完成未勾选的任务，并在每步后运行验证命令（如测试）。
3. 自动提交：每完成一个任务自动提交代码。
4. 多阶段审查：启动多个 Agent 并行审查代码质量、实现逻辑和测试覆盖率，并自动修复问题。
5. 归档：全部完成后，将计划文件移至 completed/ 文件夹。

3. 交互式创建计划（可选）

如果你还没有计划文件，可以使用 --plan 标志让 Ralphex 辅助生成：

ralphex --plan "add health check endpoint"

Ralphex 会分析代码库，通过终端提问澄清需求，生成完整的计划文件，并询问是否立即执行。

4. 实时监控

执行过程中，终端会实时流式输出带时间戳和颜色的日志。如需在浏览器中查看实时仪表盘，可添加 --serve 标志：

ralphex docs/plans/my-feature.md --serve