[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-umputun--ralphex":3,"tool-umputun--ralphex":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",146793,2,"2026-04-08T23:32:35",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":75,"owner_location":76,"owner_email":77,"owner_twitter":75,"owner_website":78,"owner_url":79,"languages":80,"stars":113,"forks":114,"last_commit_at":115,"license":116,"difficulty_score":32,"env_os":117,"env_gpu":118,"env_ram":118,"env_deps":119,"category_tags":126,"github_topics":127,"view_count":32,"oss_zip_url":75,"oss_zip_packed_at":75,"status":17,"created_at":134,"updated_at":135,"faqs":136,"releases":169},5683,"umputun\u002Fralphex","ralphex","Extended Ralph loop for autonomous AI-driven plan execution","ralphex 是一款专为开发者设计的命令行工具，旨在利用 Claude Code 实现 AI 驱动的计划自动执行。它能在 Git 仓库根目录直接运行，无需依赖 IDE 插件或云端服务，即可将复杂的开发计划转化为自动化的代码实施过程。\n\n在使用原生 Claude Code 处理多步骤复杂任务时，开发者往往需要长时间守在屏幕前逐步确认，且随着会话上下文堆积，模型容易遗忘早期决策或产生错误。ralphex 完美解决了这一痛点：它将大计划拆解为独立任务，每个任务都在全新的会话中以最小上下文执行，确保 AI 始终保持“头脑清醒”。用户只需定义好任务和验证命令，启动后便可离开，待返回时即可看到已完成编码、审查甚至提交的功能代码。\n\n该工具特别适合希望提升开发效率、减少重复性交互的后端工程师及全栈开发者。其技术亮点包括零配置开箱即用、多阶段自动化代码审查（含自定义 Agent 支持）、实时 Web 监控面板以及 Docker 隔离运行模式。此外，它还支持并行处理多个开发计划，并通过即时通知机制让用户随时掌握进度。ralphex 让 AI 编程从“辅助对话”真正进化为“自主交付”。","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_54eb4be2b533.png\" alt=\"ralphex\" width=\"400\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"build\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fcoveralls.io\u002Fgithub\u002Fumputun\u002Fralphex?branch=master\">\u003Cimg src=\"https:\u002F\u002Fcoveralls.io\u002Frepos\u002Fgithub\u002Fumputun\u002Fralphex\u002Fbadge.svg?branch=master\" alt=\"Coverage Status\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fumputun\u002Fralphex\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_2b4a70945b89.png\" alt=\"Go Report Card\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Ch2 align=\"center\">Autonomous plan execution with Claude Code\u003C\u002Fh2>\n\n*ralphex is a standalone CLI tool that runs in your terminal from the root of a git repository. It orchestrates Claude Code to execute implementation plans autonomously - no IDE plugins or cloud services required, just Claude Code and a single binary.*\n\nClaude Code is powerful but interactive - it requires you to watch, approve, and guide each step. For complex features spanning multiple tasks, this means hours of babysitting. Worse, as context fills up during long sessions, the model's quality degrades - it starts making mistakes, forgetting earlier decisions, and producing worse code.\n\nralphex solves both problems. Each task executes in a fresh Claude Code session with minimal context, keeping the model sharp throughout the entire plan. Write a plan with tasks and validation commands, start ralphex, and walk away. Come back to find your feature implemented, reviewed, and committed - or check the progress log to see what it's doing.\n\n\u003Cdetails markdown>\n\u003Csummary>Task Execution Screenshot\u003C\u002Fsummary>\n\n![ralphex tasks](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_e070296ea8f0.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary>Review Mode Screenshot\u003C\u002Fsummary>\n\n![ralphex review](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_081fd18e7eb9.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary>Web Dashboard Screenshot\u003C\u002Fsummary>\n\n![ralphex web dashboard](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_74eb72f79476.png)\n\n\u003C\u002Fdetails>\n\n## Features\n\n- **Zero setup** - works out of the box with sensible defaults, no configuration required\n- **Autonomous task execution** - executes plan tasks one at a time with automatic retry\n- **Interactive plan creation** - create plans through dialogue with Claude via `--plan` flag\n- **Multi-phase code review** - 5 agents → codex → 2 agents review pipeline\n- **Custom review agents** - configurable agents with `{{agent:name}}` template system and user defined prompts\n- **Automatic branch creation** - creates git branch from plan filename\n- **Plan completion tracking** - moves completed plans to `completed\u002F` folder\n- **Automatic commits** - commits after each task and review fix\n- **Real-time monitoring** - streaming output with timestamps, colors, and detailed logs\n- **Web dashboard** - browser-based real-time view with `--serve` flag\n- **Docker support** - run in isolated container for safer autonomous execution\n- **Notifications** - optional alerts on completion\u002Ffailure via Telegram, Email, Slack, Webhook, or custom script\n- **Worktree isolation** - run multiple plans in parallel via `--worktree` flag\n- **Multiple modes** - full execution, tasks-only, review-only, external-only, or plan creation\n\n## Quick Start\n\nMake sure ralphex is [installed](#installation) and your project is a git repository. You need a  [plan file](#plan-creation) in `docs\u002Fplans\u002F`, for example:\n\n```markdown\n# Plan: My Feature\n\n## Validation Commands\n- `go test .\u002F...`\n\n### Task 1: Implement feature\n- [ ] Add the new functionality\n- [ ] Add tests\n```\n\nThen run:\n\n```bash\nralphex docs\u002Fplans\u002Fmy-feature.md\n```\n\nralphex will create a branch, execute tasks, commit results, run multi-phase reviews, and move the plan to `completed\u002F` when done.\n\n## How It Works\n\nralphex executes plans in four phases with automated code reviews, plus an optional finalize step.\n\n\u003Cdetails markdown>\n\u003Csummary>Execution Flow Diagram\u003C\u002Fsummary>\n\n![ralphex flow](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_11ab961a4e9d.png)\n\n\u003C\u002Fdetails>\n\n### Phase 1: Task Execution\n\n1. Reads plan file and finds first incomplete task (`### Task N:` with `- [ ]` checkboxes)\n2. Sends task to Claude Code for execution\n3. Runs validation commands (tests, linters) after each task\n4. Marks checkboxes as done `[x]`, commits changes\n5. Repeats until all tasks complete or max iterations reached\n\n**Steering mid-run:** Press Ctrl+\\ (SIGQUIT) during a task iteration to pause execution. ralphex cancels the current Claude session and prompts \"press Enter to continue, Ctrl+C to abort\". While paused, you can edit the plan file — on Enter, the same task re-runs with a fresh session that re-reads the plan. Press Ctrl+C to abort cleanly. Not available on Windows.\n\n### Phase 2: First Code Review\n\nLaunches 5 review agents **in parallel** via Claude Code Task tool:\n\n| Agent | Purpose |\n|-------|---------|\n| `quality` | bugs, security issues, race conditions |\n| `implementation` | verifies code achieves stated goals |\n| `testing` | test coverage and quality |\n| `simplification` | detects over-engineering |\n| `documentation` | checks if docs need updates |\n\nClaude verifies findings, fixes confirmed issues, and commits.\n\n*[Default agents](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Ftree\u002Fmaster\u002Fpkg\u002Fconfig\u002Fdefaults\u002Fagents) provide common, language-agnostic review steps. They can be customized and tuned for your specific needs, languages, and workflows. See [Customization](#customization) for details.*\n\n### Phase 3: External Review (optional)\n\n1. Runs external review tool (codex by default, or custom script)\n2. Claude evaluates findings, fixes valid issues\n3. Iterates until no open issues\n\nThe loop terminates when: all issues resolved, max iterations reached, stalemate detected (via `--review-patience`), or manual break via Ctrl+\\ (SIGQUIT).\n\n**Stalemate detection:** When the external tool and Claude can't agree on findings, the loop can waste tokens iterating to the max. Set `--review-patience=N` (or `review_patience` in config) to terminate after N consecutive rounds with no commits or working tree changes.\n\n**Manual break:** Press Ctrl+\\ (SIGQUIT) during the external review loop to terminate it immediately. The current executor run is cancelled via context cancellation. During the task phase, Ctrl+\\ pauses instead — see [Phase 1: Task Execution](#phase-1-task-execution). Not available on Windows.\n\nSupported tools:\n- **codex** (default): OpenAI Codex for independent code review\n- **custom**: Your own script wrapping any AI (OpenRouter, local LLM, etc.)\n- **none**: Skip external review entirely\n\nSee [Custom External Review](#custom-external-review) for details on using custom scripts.\n\n### Phase 4: Second Code Review\n\n1. Launches 2 agents (`quality` + `implementation`) for final review\n2. Focuses on critical\u002Fmajor issues only\n3. Iterates until no issues found\n4. Moves plan to `completed\u002F` folder on success\n\n*Second review agents are configurable via `prompts\u002Freview_second.txt`.*\n\n### Finalize Step (optional)\n\nAfter all review phases complete successfully, ralphex can run an optional finalize step. Disabled by default.\n\n**What it does:** runs a single Claude Code session with a customizable prompt. The default `finalize.txt` prompt rebases commits onto the default branch and optionally squashes related commits into logical groups.\n\n**How to enable:**\n\nSet `finalize_enabled = true` in `~\u002F.config\u002Fralphex\u002Fconfig` or `.ralphex\u002Fconfig`.\n\n**Behavior:**\n- Runs once (no iteration loop)\n- Best-effort — failures are logged but don't block success\n- Triggers on modes with review pipeline: full, review-only, external-only\n- Uses task color (green) for output\n\n**Customization:**\n\nEdit `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt` (or `.ralphex\u002Fprompts\u002Ffinalize.txt`) to change what happens after reviews. Examples: push to remote, send notifications, run deployment scripts, or any post-completion automation. Template variables like `{{DEFAULT_BRANCH}}` are available.\n\n### Review-Only Mode\n\nReview-only mode (`--review`) runs the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already present on the current branch. This is useful when changes were made outside ralphex — via Claude Code's built-in plan mode, manual edits, other AI agents, or any other workflow.\n\n**Workflow:**\n\n1. Make changes on a feature branch (using any tool or workflow)\n2. Commit the changes\n3. Run `ralphex --review`\n\nralphex compares the branch against the default branch (`git diff master...HEAD`), launches multi-agent reviews, and iterates fixes until all agents report clean. No plan file is required — if provided, it gives reviewers additional context about the intended changes.\n\n```bash\n# switch to feature branch with existing changes\ngit checkout feature-auth\n\n# run review pipeline on those changes\nralphex --review\n\n# optionally pass a plan file for context\nralphex --review docs\u002Fplans\u002Fadd-auth.md\n```\n\n### Worktree Isolation\n\nThe `--worktree` flag runs plan execution in an isolated git worktree at `.ralphex\u002Fworktrees\u002F\u003Cbranch>`, enabling parallel execution of multiple plans on the same repo without branch conflicts.\n\n**Supported modes:** `--worktree` only applies to full mode and `--tasks-only`. It is silently ignored for `--review`, `--external-only`, and `--plan` — these modes operate from the current directory.\n\n**Re-running reviews on a worktree branch:** if the task phase completed in a worktree but the review phase needs to be re-run, `cd` into the worktree directory and run the review from there:\n\n```bash\n# find the worktree\nls .ralphex\u002Fworktrees\u002F\n\n# run review from inside it\ncd .ralphex\u002Fworktrees\u002Fmy-feature-branch\nralphex --review\n# or\nralphex --external-only\n```\n\nWorktrees are automatically removed on successful completion. If a run is interrupted, the worktree directory may remain and can be reused or removed manually.\n\n### Plan Creation\n\nPlans can be created in several ways:\n- **[Claude Code](#claude-code-integration-optional)** - use slash commands like `\u002Fralphex-plan` or your own planning workflows\n- **Manually** - write markdown files directly in `docs\u002Fplans\u002F`\n- **`--plan` flag** - integrated option that handles the entire flow\n- **Auto-detection** - running `ralphex` without arguments on master\u002Fmain prompts for plan creation if no plans exist\n\nThe `--plan` flag provides a simpler integrated experience:\n\n```bash\nralphex --plan \"add health check endpoint\"\n```\n\nClaude explores your codebase, asks clarifying questions via a terminal picker (fzf or numbered fallback), and generates a complete plan file in `docs\u002Fplans\u002F`. When reviewing the draft, you can accept, revise with text feedback, open it in `$EDITOR` for interactive annotation, or reject it.\n\n**Example session:**\n```\n$ ralphex --plan \"add caching for API responses\"\n[10:30:05] analyzing codebase structure...\n[10:30:12] found existing store layer in pkg\u002Fstore\u002F\n\nQUESTION: Which cache backend?\n  > Redis\n    In-memory\n    File-based\n    Other (type your own answer)\n\n[10:30:45] ANSWER: Redis\n[10:31:00] continuing plan creation...\n[10:32:05] plan written to docs\u002Fplans\u002Fadd-api-caching.md\n\nContinue with plan implementation?\n  > Yes, execute plan\n    No, exit\n```\n\nAfter plan creation, you can choose to continue with immediate execution or exit to run ralphex later. Progress is logged to `.ralphex\u002Fprogress\u002Fprogress-plan-\u003Cname>.txt`.\n\n## Installation\n\n### From source\n\n```bash\ngo install github.com\u002Fumputun\u002Fralphex\u002Fcmd\u002Fralphex@latest\n```\n\n### Using Homebrew\n\n```bash\nbrew install umputun\u002Fapps\u002Fralphex\n```\n\n### From releases\n\nDownload the appropriate binary from [releases](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Freleases).\n\n### Using Docker\n\nDownload the wrapper script and install to PATH:\n\n```bash\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Fumputun\u002Fralphex\u002Fmaster\u002Fscripts\u002Fralphex-dk.sh -o \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\n```\n\nThe script defaults to the Go image (`ralphex-go`). For other languages, build a custom image from the base with your toolchain installed (see [Available images](#available-images) for examples), then point the wrapper at it:\n```bash\nexport RALPHEX_IMAGE=my-ralphex\n```\n\nThen use `ralphex` as usual - it runs in a container with Claude Code and Codex pre-installed. The script shows which image it's using at startup.\n\n**Why use Docker?** ralphex runs Claude Code with `--dangerously-skip-permissions`, giving it full access to execute commands and modify files. Running in a container provides isolation - Claude can only access the mounted project directory, not your entire system. This makes autonomous execution significantly safer.\n\n\u003Cdetails markdown>\n\u003Csummary>Isolation details\u003C\u002Fsummary>\n\n**Container CAN access (read-write):**\n- Project directory mounted at `\u002Fworkspace` - full access to create, modify, delete files\n- Git operations within the project (branch, commit, etc.)\n\n**Container CAN access (read-only):**\n- `~\u002F.claude\u002F` - credentials and settings (copied at startup, not modified)\n- `~\u002F.codex\u002F` - codex credentials if present\n- `~\u002F.config\u002Fralphex\u002F` - user-level ralphex configuration\n- `~\u002F.gitconfig` - git identity for commits\n- Global gitignore (`core.excludesFile`) - auto-detected and mounted\n- `.ralphex\u002F` - project-level configuration if present\n\n**Container CANNOT access:**\n- Host filesystem outside mounted directories\n- Other projects or repositories\n- SSH keys, AWS credentials, or other secrets in `~\u002F.ssh`, `~\u002F.aws`, etc.\n- System files, binaries, or configurations\n- Other running processes or containers\n\n**Network:** Full network access (required for Claude API calls)\n\n**Privileges:** Runs as non-root user with no elevated capabilities\n\n\u003C\u002Fdetails>\n\n**Volume mounts:**\n- **Read-only**: `~\u002F.claude` and `~\u002F.codex` mounted to `\u002Fmnt\u002F`, copied at startup to preserve isolation\n- **Read-write**: project directory (`\u002Fworkspace`) - where ralphex creates branches, edits code, and commits\n- **Extra mounts**: user-defined volumes via `-v`\u002F`--volume` flags or `RALPHEX_EXTRA_VOLUMES` env var\n\n**Requirements:**\n- Python 3.9+ (for the wrapper script)\n- Docker installed and running\n- Claude Code credentials in `~\u002F.claude\u002F` (or in `$CLAUDE_CONFIG_DIR` when set)\n- Codex credentials in `~\u002F.codex\u002F` (optional, for codex review phase)\n- Git config in `~\u002F.gitconfig` (for commits)\n\n**Environment variables:**\n- `RALPHEX_IMAGE` - Docker image to use (default: `ghcr.io\u002Fumputun\u002Fralphex-go:latest`)\n- `RALPHEX_PORT` - Port for web dashboard when using `--serve` (default: `8080`)\n- `RALPHEX_CONFIG_DIR` - Custom config directory (default: `~\u002F.config\u002Fralphex`). Overrides global config location for prompts, agents, and settings\n- `CLAUDE_CONFIG_DIR` - Claude config directory (default: `~\u002F.claude`). Use for alternate Claude installations (e.g., `~\u002F.claude2`). Works both with Docker wrapper (volume mounts and keychain derivation) and non-Docker usage (passed through to Claude Code directly). Keychain service name is derived automatically from the path.\n- `RALPHEX_EXTRA_VOLUMES` - Extra volume mounts, comma-separated (e.g., `\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels`). Entries without `:` are silently skipped\n- `RALPHEX_EXTRA_ENV` - Extra environment variables, comma-separated (e.g., `DEBUG=1,API_KEY`). Format: `VAR=value` or `VAR` (inherit from host). Security warning emitted for sensitive names (KEY, SECRET, TOKEN, etc.) with explicit values - use name-only form for secure credential passing\n- `RALPHEX_DOCKER_SOCKET` - Enable Docker socket mount: `1`, `true`, or `yes` (Docker wrapper only). CLI flag: `--docker`\n- `RALPHEX_DOCKER_NETWORK` - Docker network mode (e.g., `host`, `my-network`). Useful for reaching docker-compose services. CLI flag: `--network`\n- `TZ` - Override container timezone (default: auto-detected from host via `\u002Fetc\u002Flocaltime`). Example: `TZ=Europe\u002FBerlin ralphex docs\u002Fplans\u002Ffeature.md`\n- `RALPHEX_CLAUDE_PROVIDER` - Claude provider mode: `default` or `bedrock` (Docker wrapper only)\n\n**Docker socket support:**\n\nThe `--docker` flag (or `RALPHEX_DOCKER_SOCKET=1`) mounts the host Docker socket into the container, enabling testcontainers and Docker-dependent workflows:\n\n```bash\nralphex --docker docs\u002Fplans\u002Ffeature.md\nralphex --docker --dry-run   # verify socket mount in command\n```\n\n- Auto-detects socket GID and passes `DOCKER_GID` env var for baseimage group setup\n- Emits security warning on Linux (macOS has VM isolation, no warning needed)\n- Exits with error if socket file doesn't exist (fail-fast, no silent degradation)\n\n**AWS Bedrock support:**\n\nWhen `--claude-provider bedrock` or `RALPHEX_CLAUDE_PROVIDER=bedrock` is set:\n- Keychain credential extraction is skipped (not needed for Bedrock auth)\n- AWS credentials are automatically exported from `AWS_PROFILE` via `aws configure export-credentials`\n- Required Bedrock env vars are passed to container: `CLAUDE_CODE_USE_BEDROCK`, `AWS_REGION`, credentials\n\nRequired environment for Bedrock:\n- `AWS_REGION` - AWS region where Bedrock is enabled\n- `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`\u002F`AWS_SECRET_ACCESS_KEY` - authentication\n\nNote: `CLAUDE_CODE_USE_BEDROCK=1` is automatically set when using `--claude-provider bedrock`.\n\n```bash\n# with AWS profile (credentials exported automatically)\nexport AWS_PROFILE=my-bedrock-profile\nexport AWS_REGION=us-east-1\nralphex --claude-provider bedrock docs\u002Fplans\u002Ffeature.md\n\n# or use env var for session-wide setting\nexport RALPHEX_CLAUDE_PROVIDER=bedrock\nralphex docs\u002Fplans\u002Ffeature.md\n```\n\nSee [Bedrock setup documentation](docs\u002Fbedrock-setup.md) for detailed IAM policies and setup instructions.\n\n**Extra volume mounts:**\n```bash\n# via CLI flags (can use multiple -v)\nralphex -v \u002Fdata:\u002Fmnt\u002Fdata:ro -v \u002Fmodels:\u002Fmnt\u002Fmodels docs\u002Fplans\u002Ffeature.md\n\n# via environment variable (comma-separated)\nRALPHEX_EXTRA_VOLUMES=\"\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels\" ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**Extra environment variables:**\n```bash\n# via CLI flags (can use multiple -E)\nralphex -E DEBUG=1 -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# via environment variable (comma-separated)\nRALPHEX_EXTRA_ENV=\"DEBUG=1,LOG_LEVEL=verbose\" ralphex docs\u002Fplans\u002Ffeature.md\n\n# name-only form inherits value from host (recommended for secrets)\nexport API_KEY=secret123\nralphex -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# values containing commas require -E flag (env var splits on commas)\nralphex -E \"TAGS=foo,bar,baz\" docs\u002Fplans\u002Ffeature.md\n```\n\n**Debugging:**\n```bash\nralphex --dry-run docs\u002Fplans\u002Ffeature.md  # show docker command without executing\n```\n\nThe `--dry-run` flag prints the full `docker run` command that would be executed. Useful for debugging container configuration or copying the command for manual execution.\n\nNote: inherited env vars (`-E FOO` without `=value`) won't work when copying the command to a different shell. Use explicit values for portability.\n\n**Updating:**\n```bash\nralphex --update         # pull latest docker image\nralphex --update-script  # update the wrapper script itself\n```\n\n\u003Ca id=\"available-images\">\u003C\u002Fa>\n\u003Cdetails markdown>\n\u003Csummary>Available images\u003C\u002Fsummary>\n\nTwo images are published:\n\n| Image | Description |\n|-------|-------------|\n| `ghcr.io\u002Fumputun\u002Fralphex:latest` | Base image with Claude Code, Codex, and core tools |\n| `ghcr.io\u002Fumputun\u002Fralphex-go:latest` | Go development (extends base with Go toolchain) |\n\n**Base image includes:**\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| Claude Code | latest | AI coding assistant |\n| Codex | latest | External code review |\n| Node.js\u002Fnpm | 24.x | Required for Claude Code |\n| Python\u002Fpip | 3.x | Scripts and automation |\n| git | 2.x | Version control |\n| docker-cli | - | Docker client for container workflows |\n| make | 4.x | Build automation |\n| gcc, musl-dev | - | C compiler for native extensions |\n| bash | 5.x | Shell |\n| fzf | - | Fuzzy finder for plan selection |\n| ripgrep | - | Fast search (used by Claude Code) |\n\n**Go image adds:**\n\n| Tool | Version | Purpose |\n|------|---------|---------|\n| Go | 1.26.0 | Go compiler and runtime |\n| golangci-lint | latest | Go linter |\n| moq | latest | Mock generator |\n| goimports | latest | Import formatter |\n\n**For Go projects**, use the `-go` image:\n```bash\nRALPHEX_IMAGE=ghcr.io\u002Fumputun\u002Fralphex-go:latest ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**For other languages**, create a custom image by extending the base with your language toolchain. The Go image (`Dockerfile-go`) shows the pattern:\n\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# install go from official distribution\nARG GO_VERSION=1.26.0\nRUN ARCH=$(uname -m | sed 's\u002Fx86_64\u002Famd64\u002F;s\u002Faarch64\u002Farm64\u002F') && \\\n    wget -qO- \"https:\u002F\u002Fgo.dev\u002Fdl\u002Fgo${GO_VERSION}.linux-${ARCH}.tar.gz\" | tar -xz -C \u002Fusr\u002Flocal\n\nENV GOROOT=\u002Fusr\u002Flocal\u002Fgo\nENV GOPATH=\u002Fhome\u002Fapp\u002Fgo\nENV PATH=\"${PATH}:${GOROOT}\u002Fbin:${GOPATH}\u002Fbin\"\n\n# install go tools\nRUN wget -qO- https:\u002F\u002Fraw.githubusercontent.com\u002Fgolangci\u002Fgolangci-lint\u002FHEAD\u002Finstall.sh | sh -s -- -b \u002Fusr\u002Flocal\u002Fbin && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install github.com\u002Fmatryer\u002Fmoq@latest && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install golang.org\u002Fx\u002Ftools\u002Fcmd\u002Fgoimports@latest\n```\n\nSame approach for Rust, Java, or any other language:\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# rust\nRUN apk add --no-cache rust cargo\nENV CARGO_HOME=\u002Fhome\u002Fapp\u002F.cargo PATH=\"${PATH}:${CARGO_HOME}\u002Fbin\"\n\n# java\nRUN apk add --no-cache openjdk21-jdk\nENV JAVA_HOME=\u002Fusr\u002Flib\u002Fjvm\u002Fjava-21-openjdk PATH=\"${PATH}:${JAVA_HOME}\u002Fbin\"\n```\n\nBuild and use:\n```bash\ndocker build -t my-ralphex -f Dockerfile.python .\nRALPHEX_IMAGE=my-ralphex ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n\u003C\u002Fdetails>\n\nExample with custom port:\n```bash\nRALPHEX_PORT=3000 ralphex --serve --port 3000 docs\u002Fplans\u002Ffeature.md\n```\n\n## Usage\n\n**Note:** ralphex must be run from the repository root directory (where `.git` is located).\n\n```bash\n# execute plan with task loop + reviews\nralphex docs\u002Fplans\u002Ffeature.md\n\n# select plan with fzf, or create one interactively if none exist\nralphex\n\n# review-only mode (skip task execution)\nralphex --review docs\u002Fplans\u002Ffeature.md\n\n# external-only mode (skip tasks and first review, run only external review loop)\nralphex --external-only\n\n# tasks-only mode (run only task phase, skip all reviews)\nralphex --tasks-only docs\u002Fplans\u002Ffeature.md\n\n# run in isolated git worktree (full and tasks-only modes only)\nralphex --worktree docs\u002Fplans\u002Ffeature.md\n\n# override default branch for review diffs\nralphex --review --base-ref develop\nralphex --review --base-ref abc1234 --skip-finalize\n\n# initialize local .ralphex\u002F config in current project (commented-out defaults)\nralphex --init\n\n# interactive plan creation\nralphex --plan \"add user authentication\"\n\n# with custom max iterations\nralphex --max-iterations=100 docs\u002Fplans\u002Ffeature.md\n\n# limit external review iterations (0 = auto, derived from max-iterations)\nralphex --max-external-iterations=5 docs\u002Fplans\u002Ffeature.md\n\n# terminate external review after 3 unchanged rounds (stalemate detection)\nralphex --review-patience=3 docs\u002Fplans\u002Ffeature.md\n\n# wait and retry on rate limit (instead of exiting)\nralphex --wait 1h docs\u002Fplans\u002Ffeature.md\n\n# set per-session timeout to kill hanging claude sessions\nralphex --session-timeout 30m docs\u002Fplans\u002Ffeature.md\n\n# kill claude session when no output for 5 minutes (idle detection)\nralphex --idle-timeout 5m docs\u002Fplans\u002Ffeature.md\n\n# with web dashboard\nralphex --serve docs\u002Fplans\u002Ffeature.md\n\n# web dashboard on custom port\nralphex --serve --port 3000 docs\u002Fplans\u002Ffeature.md\n```\n\n### Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-m, --max-iterations` | Maximum task iterations | 50 |\n| `--max-external-iterations` | Override external review iteration limit (0 = auto) | 0 |\n| `--review-patience` | Terminate external review after N unchanged rounds (0 = disabled) | 0 |\n| `-r, --review` | Skip task execution, run full review pipeline | false |\n| `-e, --external-only` | Skip tasks and first review, run only external review loop | false |\n| `-c, --codex-only` | Alias for `--external-only` (deprecated) | false |\n| `-t, --tasks-only` | Run only task phase, skip all reviews | false |\n| `-b, --base-ref` | Override default branch for review diffs (branch name or commit hash) | auto-detect |\n| `--skip-finalize` | Skip finalize step even if enabled in config | false |\n| `--wait` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |\n| `--session-timeout` | Per-session timeout for claude (e.g., `30m`, `1h`). Kills hanging sessions | disabled |\n| `--idle-timeout` | Kill claude session when no output for specified duration (e.g., `5m`). Resets on each output line | disabled |\n| `--worktree` | Run in isolated git worktree (full and tasks-only modes only) | false |\n| `--plan` | Create plan interactively (provide description) | - |\n| `-s, --serve` | Start web dashboard for real-time streaming | false |\n| `-p, --port` | Web dashboard port (used with `--serve`) | 8080 |\n| `-w, --watch` | Directories to watch for progress files (repeatable) | - |\n| `-d, --debug` | Enable debug logging | false |\n| `--no-color` | Disable color output | false |\n| `--init` | Initialize local `.ralphex\u002F` config in current project | - |\n| `--reset` | Interactively reset global config to embedded defaults | - |\n| `--dump-defaults` | Extract raw embedded defaults to specified directory | - |\n| `--config-dir` | Custom config directory (env: `RALPHEX_CONFIG_DIR`) | `~\u002F.config\u002Fralphex` |\n\n## Plan File Format\n\nPlans are markdown files with task sections. Each task has checkboxes that claude marks complete.\n\n```markdown\n# Plan: Add User Authentication\n\n## Overview\nAdd JWT-based authentication to the API.\n\n## Validation Commands\n- `go test .\u002F...`\n- `golangci-lint run`\n\n### Task 1: Add auth middleware\n- [ ] Create JWT validation middleware\n- [ ] Add to router for protected routes\n- [ ] Add tests\n- [ ] Mark completed\n\n### Task 2: Add login endpoint\n- [ ] Create \u002Fapi\u002Flogin handler\n- [ ] Return JWT on successful auth\n- [ ] Add tests\n- [ ] Mark completed\n```\n\n**Requirements:**\n- Task headers must use `### Task N:` or `### Iteration N:` format (N can be integer or non-integer like `2.5`, `2a`)\n- Checkboxes: `- [ ]` (incomplete) or `- [x]` (completed)\n- Checkboxes belong only in Task sections (`### Task N:` or `### Iteration N:`). Do not put checkboxes in Success criteria, Overview, or Context — they cause extra loop iterations. The agent handles them gracefully when present, but plan authors should avoid them for best behavior.\n- Include `## Validation Commands` section with test\u002Flint commands\n- Place plans in `docs\u002Fplans\u002F` directory (configurable via `plans_dir`)\n\n## Review Agents\n\nThe review pipeline is fully customizable. ralphex ships with sensible defaults that work for any language, but you can modify agents, add new ones, or replace prompts entirely to match your specific workflow.\n\n### Default Agents\n\nThese 5 agents cover common review concerns and work well out of the box. Customize or replace them based on your needs:\n\n| Agent | Phase | Purpose |\n|-------|-------|---------|\n| `quality` | 1st & 2nd | bugs, security issues, race conditions |\n| `implementation` | 1st & 2nd | verifies code achieves stated goals |\n| `testing` | 1st only | test coverage and quality |\n| `simplification` | 1st only | detects over-engineering |\n| `documentation` | 1st only | checks if docs need updates |\n\n### Agent Options (Frontmatter)\n\nAgent files support optional YAML frontmatter for per-agent configuration:\n\n```txt\n---\nmodel: haiku\nagent: code-reviewer\n---\nReview the code for quality issues...\n```\n\n| Option | Values | Description |\n|--------|--------|-------------|\n| `model` | `haiku`, `sonnet`, `opus` | Claude model for this agent |\n| `agent` | any string | Claude Code Task tool subagent type |\n\nBoth options are optional. Without frontmatter, agents use default model and `general-purpose` subagent type. Full model IDs (e.g. `claude-sonnet-4-5-20250929`) are normalized to short keywords (`sonnet`) since Claude Code only accepts `haiku`, `sonnet`, `opus`. Invalid model values are dropped with a warning.\n\n### Template Syntax\n\nCustom prompt files support variable expansion. All variables use the `{{VARIABLE}}` syntax.\n\n**Available variables:**\n\n| Variable | Description | Example value |\n|----------|-------------|---------------|\n| `{{PLAN_FILE}}` | Path to the plan file being executed | `docs\u002Fplans\u002Ffeature.md` |\n| `{{PROGRESS_FILE}}` | Path to the progress log file | `.ralphex\u002Fprogress\u002Fprogress-feature.txt` |\n| `{{GOAL}}` | Human-readable goal description | `implementation of plan at docs\u002Fplans\u002Ffeature.md` |\n| `{{DEFAULT_BRANCH}}` | Default branch name (overridable via `--base-ref` or `default_branch` config) | `main`, `master`, `origin\u002Fmain` |\n| `{{agent:name}}` | Expands to Task tool instructions for the named agent | (see below) |\n\n**Agent references:**\n\nReference agents in prompt files using `{{agent:name}}` syntax:\n\n```\nLaunch the following review agents in parallel:\n{{agent:quality}}\n{{agent:implementation}}\n{{agent:testing}}\n```\n\nEach `{{agent:name}}` expands to Task tool instructions that tell Claude Code to run that agent. Variables inside agent content are also expanded, so agents can use `{{DEFAULT_BRANCH}}` or other variables.\n\n### Customization\n\nThe entire system is designed for customization - both task execution and reviews:\n\n**Agent files** (`~\u002F.config\u002Fralphex\u002Fagents\u002F`):\n- On first run, ralphex installs 5 default agent files as commented-out templates. These serve as examples — while fully commented out, they are inactive and the embedded defaults are used instead. Uncomment and edit to customize\n- Per-file fallback: for each agent, ralphex checks local `.ralphex\u002Fagents\u002F` → global `~\u002F.config\u002Fralphex\u002Fagents\u002F` → embedded default. The 5 embedded agents are always the baseline — deleting an agent file from disk does not disable it, the embedded version is used as fallback\n- To disable a specific agent, remove its `{{agent:name}}` reference from the prompt files (`review_first.txt`, `review_second.txt`), not the agent file itself\n- Add new `.txt` files to create custom agents (reference them in prompts with `{{agent:name}}`)\n- Run `ralphex --init` to create local `.ralphex\u002F` project config with commented-out defaults\n- Run `ralphex --reset` to interactively restore defaults, or delete all files manually\n- Run `ralphex --dump-defaults \u003Cdir>` to extract raw defaults for comparison\n- Use the `\u002Fralphex-update` Claude Code skill to smart-merge updated defaults into customized files\n- Alternatively, reference agents already installed in your Claude Code directly in prompt files (see example below)\n\n**Prompt files** (`~\u002F.config\u002Fralphex\u002Fprompts\u002F`):\n- `task.txt` - task execution prompt\n- `review_first.txt` - comprehensive review (default: 5 language-agnostic agents - quality, implementation, testing, simplification, documentation; customizable)\n- `codex.txt` - codex evaluation prompt (Claude evaluates codex output)\n- `codex_review.txt` - codex review prompt (sent to codex external review tool)\n- `custom_review.txt` - custom external review prompt (sent to custom review script)\n- `custom_eval.txt` - custom evaluation prompt (Claude evaluates custom tool output)\n- `review_second.txt` - final review, critical\u002Fmajor issues only (default: 2 agents - quality, implementation; customizable)\n- `make_plan.txt` - interactive plan creation prompt\n- `finalize.txt` - optional finalize step prompt (disabled by default)\n\n**Comment lines and markdown headers:**\nA leading block of 2+ contiguous comment lines (starting with `#`) at the top of a file is treated as a meta-comment and stripped when loading. A single `# Title` at the top is preserved (treated as a markdown header). Comment lines appearing later in the file body are always preserved:\n\n```txt\n# This single title line is preserved as a markdown header\ncheck for SQL injection\n# this mid-body comment is also preserved\ncheck for XSS\n```\n\nFiles containing *only* comment lines (every line starts with `#`) are treated as unmodified templates and fall back to embedded defaults. This is how commented-out default files work — once you add any non-comment content, the file is used as-is.\n\nNote: Inline comments are not supported (`text # comment` keeps the entire line).\n\n**Examples:**\n- Add a security-focused agent for fintech projects\n- Remove `{{agent:simplification}}` from prompt files if over-engineering isn't a concern\n- Create language-specific agents (Python linting, TypeScript types)\n- Modify prompts to change how many agents run per phase\n\n**Using Claude Code agents directly:**\n\nInstead of creating agent files, you can reference agents installed in your Claude Code directly in prompt files:\n\n```txt\n# in review_first.txt - just list agent names with their prompts\nAgents to launch:\n1. qa-expert - \"Review for bugs and security issues\"\n2. go-test-expert - \"Review test coverage and quality\"\n3. go-smells-expert - \"Review for code smells\"\n```\n\n## Requirements\n\n- `claude` - Claude Code CLI\n- `fzf` - for plan selection (optional)\n- `codex` - for external review (optional)\n\n## Configuration\n\nralphex uses a configuration directory at `~\u002F.config\u002Fralphex\u002F` (override with `--config-dir` or `RALPHEX_CONFIG_DIR`) with the following structure:\n\n```\n~\u002F.config\u002Fralphex\u002F\n├── config              # main configuration file (INI format)\n├── prompts\u002F            # custom prompt templates\n│   ├── task.txt\n│   ├── review_first.txt\n│   ├── review_second.txt\n│   ├── codex.txt\n│   ├── codex_review.txt\n│   ├── custom_review.txt\n│   ├── custom_eval.txt\n│   ├── make_plan.txt\n│   └── finalize.txt\n└── agents\u002F             # custom review agents (*.txt files)\n```\n\nOn first run, ralphex creates this directory with default configuration.\n\n**Commented templates:**\n- Config files are installed with all content commented out (`# ` prefix)\n- Uncomment only the settings you want to customize\n- Files that remain all-commented receive automatic updates with new defaults\n- Once you uncomment any setting, the file is preserved and won't be overwritten\n\n### Local Project Config\n\nProjects can override global settings with a `.ralphex\u002F` directory in the project root. Run `ralphex --init` to create it with commented-out defaults:\n\n```\nproject\u002F\n├── .ralphex\u002F           # optional, project-local config\n│   ├── config          # overrides specific settings\n│   ├── prompts\u002F        # custom prompts for this project\n│   └── agents\u002F         # custom agents for this project\n```\n\n**Priority:** CLI flags > local `.ralphex\u002F` > global `~\u002F.config\u002Fralphex\u002F` > embedded defaults\n\nUse `--config-dir` or `RALPHEX_CONFIG_DIR` to override the global config location. This is useful for maintaining separate agent\u002Fprompt sets for different workflows.\n\n**Merge behavior:**\n- **Config file**: per-field override (local values override global, missing fields fall back)\n- **Prompts**: per-file fallback (local → global → embedded for each prompt file)\n- **Agents**: per-file fallback (local → global → embedded for each agent file, same as prompts)\n\n### Configuration options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `claude_command` | Claude CLI command | `claude` |\n| `claude_args` | Claude CLI arguments | `--dangerously-skip-permissions --output-format stream-json --verbose` |\n| `codex_enabled` | Enable codex review phase | `true` |\n| `codex_command` | Codex CLI command | `codex` |\n| `codex_model` | Codex model ID | `gpt-5.4` |\n| `codex_reasoning_effort` | Reasoning effort level | `xhigh` |\n| `codex_timeout_ms` | Codex timeout in ms | `3600000` |\n| `codex_sandbox` | Sandbox mode | `read-only` |\n| `external_review_tool` | External review tool (`codex`, `custom`, `none`) | `codex` |\n| `custom_review_script` | Path to custom review script (when `external_review_tool = custom`) | - |\n| `max_external_iterations` | Override external review iteration limit (0 = auto, derived from `max_iterations`) | `0` |\n| `review_patience` | Terminate external review after N consecutive unchanged rounds (0 = disabled) | `0` |\n| `iteration_delay_ms` | Delay between iterations | `2000` |\n| `task_retry_count` | Task retry attempts | `1` |\n| `finalize_enabled` | Enable finalize step after reviews | `false` |\n| `use_worktree` | Run each plan in an isolated git worktree (full and tasks-only modes only) | `false` |\n| `plans_dir` | Plans directory | `docs\u002Fplans` |\n| `default_branch` | Override auto-detected default branch for review diffs | auto-detect |\n| `vcs_command` | VCS command for the git backend (set to a translation script for hg repos) | `git` |\n| `commit_trailer` | Trailer line appended to all ralphex-orchestrated git commits | disabled |\n| `color_task` | Task execution phase color (hex) | `#00ff00` |\n| `color_review` | Review phase color (hex) | `#00ffff` |\n| `color_codex` | Codex review color (hex) | `#ff00ff` |\n| `color_claude_eval` | Claude evaluation color (hex) | `#64c8ff` |\n| `color_warn` | Warning messages color (hex) | `#ffff00` |\n| `color_error` | Error messages color (hex) | `#ff0000` |\n| `color_signal` | Completion\u002Ffailure signals color (hex) | `#ff6464` |\n| `color_timestamp` | Timestamp prefix color (hex) | `#8a8a8a` |\n| `color_info` | Informational messages color (hex) | `#b4b4b4` |\n| `claude_error_patterns` | Patterns to detect in claude output (comma-separated) | `You've hit your limit,API Error:,cannot be launched inside another Claude Code session` |\n| `codex_error_patterns` | Patterns to detect in codex output (comma-separated) | `Rate limit,quota exceeded` |\n| `claude_limit_patterns` | Limit patterns for claude triggering wait+retry (comma-separated) | `You've hit your limit` |\n| `codex_limit_patterns` | Limit patterns for codex triggering wait+retry (comma-separated) | `Rate limit,quota exceeded` |\n| `wait_on_limit` | Wait duration before retrying on rate limit (e.g., `1h`, `30m`) | disabled |\n| `session_timeout` | Per-session timeout for claude (e.g., `30m`, `1h`). Kills hanging sessions | disabled |\n| `idle_timeout` | Kill claude session when no output for specified duration (e.g., `5m`). Resets on each output line | disabled |\n\nColors use 24-bit RGB (true color), supported natively by all modern terminals (iTerm2, Kitty, Terminal.app, Windows Terminal, GNOME Terminal, Alacritty, Zed, VS Code, etc). Older terminals will degrade gracefully. Use `--no-color` to disable colors entirely.\n\nError patterns use case-insensitive substring matching. When a pattern is detected in claude or codex output, ralphex exits gracefully with an informative message suggesting how to check usage\u002Fstatus. Multiple patterns are separated by commas, with whitespace trimmed from each pattern.\n\n**Rate limit retry:** Limit patterns (`claude_limit_patterns`, `codex_limit_patterns`) work similarly but support optional wait+retry behavior. When `--wait` is set (or `wait_on_limit` in config), a limit pattern match triggers a wait followed by automatic retry instead of exiting. Without `--wait`, limit patterns fall through to error pattern behavior. Limit patterns are checked before error patterns — if the same string matches both, the limit pattern takes priority when wait is enabled.\n\n### Custom prompts\n\nPlace custom prompt files in `~\u002F.config\u002Fralphex\u002Fprompts\u002F` to override the built-in prompts. Missing files fall back to embedded defaults. See [Review Agents](#review-agents) section for agent customization.\n\n### Custom External Review\n\nUse your own AI tool for external code review instead of codex. This allows integration with OpenRouter, local LLMs, or any custom pipeline.\n\n**Configuration:**\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig\nexternal_review_tool = custom\ncustom_review_script = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\n```\n\n**Script interface:**\n\nYour script receives a single argument: path to a prompt file containing review instructions. The script outputs findings to stdout - ralphex passes them to Claude for evaluation and fixing.\n\n```bash\n#!\u002Fbin\u002Fbash\n# example: ~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\nprompt_file=\"$1\"\n\n# read the prompt (contains diff instructions, goal, review focus)\nprompt=$(cat \"$prompt_file\")\n\n# call your AI tool (OpenRouter, local LLM, etc.)\n# example with curl to OpenRouter:\ncurl -s https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $OPENROUTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d \"{\n    \\\"model\\\": \\\"anthropic\u002Fclaude-3.5-sonnet\\\",\n    \\\"messages\\\": [{\\\"role\\\": \\\"user\\\", \\\"content\\\": $(echo \"$prompt\" | jq -Rs .)}]\n  }\" | jq -r '.choices[0].message.content'\n```\n\n**Expected output format:**\n\n- Write findings to stdout as a structured list\n- Use format: `file:line - description of issue`\n- Output `NO ISSUES FOUND` when there are no problems\n\n**Iteration behavior:**\n\nThe external review loop runs up to `max(3, max_iterations\u002F5)` iterations by default. Override with `max_external_iterations` config option or `--max-external-iterations` CLI flag (0 = auto).\n\nThe prompt's `{{DIFF_INSTRUCTION}}` variable adapts per iteration:\n- **First iteration**: `git diff main...HEAD` (all changes in feature branch)\n- **Subsequent iterations**: `git diff` (only uncommitted changes from previous fixes)\n\nThis lets the review tool focus on remaining issues after fixes.\n\n### Notifications\n\nralphex can send notifications when execution completes or fails. Notifications are optional, disabled by default, and best-effort - failures are logged but never affect the exit code.\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nnotify_channels = telegram, webhook\nnotify_telegram_token = 123456:ABC-DEF\nnotify_telegram_chat = -1001234567890\nnotify_webhook_urls = https:\u002F\u002Fhooks.example.com\u002Fnotify\n```\n\nSupported channels: `telegram`, `email`, `slack`, `webhook`, `custom` (script). Misconfigured channels are detected at startup.\n\nSee [notifications documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fnotifications.md) for setup guides, message format examples, and custom script integration.\n\n**Prompt customization:**\n\nCustomize `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_review.txt` to modify the prompt sent to your script. Available variables:\n- `{{DIFF_INSTRUCTION}}` - git diff command appropriate for current iteration\n- `{{GOAL}}` - human-readable description of what's being implemented\n- `{{PLAN_FILE}}` - path to the plan file\n- `{{PROGRESS_FILE}}` - path to progress log with previous review iterations\n- `{{DEFAULT_BRANCH}}` - detected default branch (main, master, etc.)\n- `{{PREVIOUS_REVIEW_CONTEXT}}` - previous review context (empty on first iteration, populated on subsequent)\n\nCustomize `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_eval.txt` to modify how Claude evaluates your tool's output.\n\n**Docker considerations:**\n\nWhen running ralphex in Docker, your script must be accessible inside the container:\n- Mount your scripts directory: `-v ~\u002F.config\u002Fralphex\u002Fscripts:\u002Fhome\u002Fapp\u002F.config\u002Fralphex\u002Fscripts:ro`\n- Ensure script dependencies are available (curl, jq, etc. are included in base image)\n- Environment variables (API keys) must be passed to container: `-e OPENROUTER_API_KEY`\n\n### Using Alternative Providers for Claude Phases\n\nThe `claude_command` and `claude_args` config options let you replace Claude Code with any CLI that produces compatible `stream-json` output. This means codex, 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.\n\nA working example is included: [`scripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh) wraps codex to produce Claude-compatible events. To use it:\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nclaude_command = \u002Fpath\u002Fto\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\nSetting `claude_args` to empty is optional. Note that default Claude flags (`--dangerously-skip-permissions`, `--output-format stream-json`, `--verbose`) may still be passed due to config fallback behavior. Wrapper scripts should ignore unknown flags gracefully — the included script does this via its `*) shift ;;` catch-all.\n\nThe wrapper supports environment variables:\n- `CODEX_MODEL` - codex model to use (default: codex default)\n- `CODEX_SANDBOX` - sandbox mode (default: `danger-full-access`)\n- `CODEX_VERBOSE` - set to `1` to include command execution output in the stream (default: `0`, only agent messages are shown)\n\nSee [custom providers documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md) for a detailed guide on writing wrappers for other providers.\n\n### Configurable VCS Backend\n\nralphex can work with Mercurial repositories through the `vcs_command` config option and custom prompt files.\n\n```ini\n# in ~\u002F.config\u002Fralphex\u002Fconfig or .ralphex\u002Fconfig\nvcs_command = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fhg2git.sh\n```\n\nA reference translation script is included at [`scripts\u002Fhg2git\u002Fhg2git.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fhg2git\u002Fhg2git.sh). It maps the ~15 git subcommands ralphex uses internally to Mercurial equivalents, with phase-based commit logic (amend on draft, commit on public). Requires bash 4.0+ (for associative arrays used in diff stats parsing).\n\nYou will also need to customise prompt files to replace git commands that Claude executes as bash commands during reviews. See [Mercurial support documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fhg-support.md) for full setup instructions, prompt replacement examples, `.hgignore` setup, and known limitations.\n\n\u003Cdetails markdown>\n\u003Csummary>\u003Cb>FAQ\u003C\u002Fb>\u003C\u002Fsummary>\n\n**I installed ralphex, what do I do next?**\n\nCreate a plan file in `docs\u002Fplans\u002F` (see [Quick Start](#quick-start) for format), then run `ralphex docs\u002Fplans\u002Fyour-plan.md`. ralphex will create a branch, execute tasks, and run reviews automatically.\n\n**Why are there two review phases?**\n\nFirst review is comprehensive (5 agents by default), second is a final check focusing on critical\u002Fmajor issues only (2 agents). See [How It Works](#how-it-works).\n\n**How do I use my own Claude Code agents?**\n\nReference them directly in prompt files by name, e.g., `qa-expert - \"Review for bugs\"`. See [Customization](#customization).\n\n**What if codex isn't installed?**\n\nCodex is optional. If not installed, the codex review phase is skipped automatically.\n\n**Can I run just reviews without task execution?**\n\nYes, use `--review` flag to run the full review pipeline (Phase 2 → Phase 3 → Phase 4) on changes already on the current branch. This works for changes made by any tool — Claude Code's built-in mode, manual edits, other agents, etc. Switch to the feature branch, commit your changes, and run `ralphex --review`. See [Review-Only Mode](#review-only-mode) for details.\n\n**Can I run ralphex in a non-git directory?**\n\nNot directly, but ralphex supports Mercurial repos through the `vcs_command` config option and a translation script. See [Configurable VCS Backend](#configurable-vcs-backend) for setup.\n\n**What if my repository has no commits?**\n\nralphex prompts to create an initial commit when the repository is empty. This is required because ralphex needs branches for feature isolation. Answer \"y\" to let ralphex stage all files and create an initial commit, or create one manually first with `git add . && git commit -m \"initial commit\"`.\n\n**Should I run ralphex on master or a feature branch?**\n\nFor full mode, start on master - ralphex creates a branch automatically from the plan filename. For `--review` mode, switch to your feature branch first - reviews compare against master using `git diff master...HEAD`.\n\n**How do I restore default agents after customizing?**\n\nRun `ralphex --reset` to interactively reset global config. Select which components to reset (config, prompts, agents). Alternatively, delete all `.txt` files from `~\u002F.config\u002Fralphex\u002Fagents\u002F` manually. To smart-merge updated defaults into customized files (preserving your changes), use the `\u002Fralphex-update` Claude Code skill or `ralphex --dump-defaults \u003Cdir>` to extract defaults for manual comparison.\n\n**How do I disable a default agent?**\n\nDeleting an agent file from `~\u002F.config\u002Fralphex\u002Fagents\u002F` does not disable it — the embedded default is used as fallback. To disable a specific agent, edit the prompt files (`review_first.txt`, `review_second.txt`) and remove the `{{agent:name}}` reference for that agent.\n\n**How does local .ralphex\u002F config interact with global config?**\n\nPriority: CLI flags > local `.ralphex\u002Fconfig` > global `~\u002F.config\u002Fralphex\u002Fconfig` > embedded defaults. Each local setting overrides the corresponding global one—no need to duplicate the entire file. For agents: per-file fallback (local → global → embedded), same as prompts. Override one agent without copying all others.\n\n**What happens to uncommitted changes if ralphex fails?**\n\nRalphex commits after each completed task. If execution fails, completed tasks are already committed to the feature branch. Uncommitted changes from the failed task remain in the working directory for manual inspection.\n\n**What if ralphex is interrupted mid-execution?**\n\nCompleted tasks are already committed to the feature branch. To resume, re-run `ralphex docs\u002Fplans\u002F\u003Cplan>.md`. Ralphex detects completed tasks via `[x]` checkboxes in the plan and continues from the first incomplete task. For review sessions, simply restart. Reviews re-run from iteration 1, but fixes from previous iterations remain in the codebase.\n\n**Can I adjust the plan or change direction while ralphex is running?**\n\nYes, two approaches depending on the situation:\n\n1. **Edit CLAUDE.md** — for behavioral changes (coding style, libraries, constraints). Each task runs in a fresh Claude Code session that reads CLAUDE.md at startup, so changes take effect on the next task or iteration automatically. No need to stop ralphex.\n\n2. **Stop, edit plan, re-run** — for structural changes (reorder tasks, add\u002Fremove tasks, change requirements). Press Ctrl+C to stop, edit the plan file (uncheck `[x]` → `[ ]` to redo tasks, add new tasks, modify descriptions), then re-run `ralphex docs\u002Fplans\u002F\u003Cplan>.md`. Ralphex picks up from the first incomplete task and adapts to the updated plan.\n\n**What's the difference between progress file and plan file?**\n\nProgress file (`.ralphex\u002Fprogress\u002Fprogress-*.txt`) is a real-time execution log—tail it to monitor. Plan file tracks task state (`[ ]` vs `[x]`). To resume, re-run ralphex on the plan file; it finds incomplete tasks automatically.\n\n**Do I need to commit changes before running ralphex?**\n\nIt depends. If the plan file is the only uncommitted change, ralphex auto-commits it after creating the feature branch and continues execution. If other files have uncommitted changes, ralphex shows a helpful error with options: stash temporarily (`git stash`), commit first (`git commit -am \"wip\"`), or use review-only mode (`ralphex --review`).\n\n**What's the difference between agents\u002F and prompts\u002F?**\n\nAgents define *what* to check (review instructions). Prompts define *how* the workflow runs (execution steps, signal handling).\n\n**Can I run a custom step before or after all tasks complete?**\n\nYes. Customize `prompts\u002Ftask.txt` to inject extra steps at any point in the task lifecycle. A common pattern is adding a \"gate step\" that runs after all tasks are done but before signaling completion. For example, to run a code smells check after the last task:\n\n```txt\nSTEP 3 - COMPLETE (after validation passes):\n- ...existing steps...\n- If NO more [ ] checkboxes in the entire plan, proceed to STEP 4\n\nSTEP 4 - STYLE CHECK (only when all tasks are done):\n- Use \u002Fsmells skill to analyze all files changed on this branch\n- Fix all reported style and code quality issues\n- Run tests and linter again to verify fixes\n- Commit fixes if any: fix: address code smell findings\n- Output exactly: \u003C\u003C\u003CRALPHEX:ALL_TASKS_DONE>>>\n```\n\nThis works because ralphex only checks for the `ALL_TASKS_DONE` signal — it doesn't care how many steps precede it. The same approach works for any tool or skill: security scanning, formatting, documentation generation, etc. Place it in `~\u002F.config\u002Fralphex\u002Fprompts\u002Ftask.txt` for global use or `.ralphex\u002Fprompts\u002Ftask.txt` for a specific project.\n\n**Can I use ralphex with Claude Pro plan?**\n\nYes. Pro plans hit rate limits more frequently. Use `--wait` to pause and retry automatically instead of exiting:\n\n```bash\nralphex --wait 1h docs\u002Fplans\u002Ffeature.md\n```\n\nWhen a rate limit is detected, ralphex waits the specified duration and retries. Execution takes longer but completes unattended. You can also set `wait_on_limit = 1h` in config to make it the default.\n\n**Can I use Cursor CLI instead of Claude Code?**\n\nYes. [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fcli) is community-tested as a drop-in alternative. Configure in `~\u002F.config\u002Fralphex\u002Fconfig`:\n\n```ini\nclaude_command = agent\nclaude_args = --force --output-format stream-json\n```\n\nKey differences: `agent` command (not `claude`), `--force` flag (not `--dangerously-skip-permissions`). Stream format and signals are compatible. *Note: this is community-tested, not officially supported. Compatibility depends on Cursor maintaining Claude Code compatibility.*\n\n**Can I use codex (or another model) for task execution instead of Claude?**\n\nYes. Use the included wrapper script that translates codex output to Claude's stream-json format:\n\n```ini\nclaude_command = \u002Fpath\u002Fto\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\nSet `CODEX_MODEL` env var to choose the model. See [Using Alternative Providers](#using-alternative-providers-for-claude-phases) and [custom providers documentation](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md) for writing wrappers for other tools.\n\n**How do I use multiple Claude accounts?**\n\nSet the `CLAUDE_CONFIG_DIR` environment variable to point to the alternate Claude config directory:\n\n```bash\nCLAUDE_CONFIG_DIR=~\u002F.claude2 ralphex docs\u002Fplans\u002Ffeature.md\n```\n\nThis is the same env var Claude Code itself uses. With Docker, the wrapper script mounts the specified directory and derives the correct macOS Keychain service name from the path. Without Docker, the env var passes through to the child Claude Code process directly. Each Claude installation stores credentials under a unique Keychain entry based on its config directory. No additional configuration is needed — just point `CLAUDE_CONFIG_DIR` to the right directory.\n\n**Can I run something after all phases complete (notifications, rebase commits, etc.)?**\n\nYes. Enable the finalize step with `finalize_enabled = true` in config. It runs once after successful review phases (best-effort—failures are logged but don't block success). The default `finalize.txt` prompt rebases onto the default branch and optionally squashes commits into logical groups. Customize `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt` for other actions like sending notifications, pushing to remote, or running custom scripts.\n\n\u003C\u002Fdetails>\n\n## Web Dashboard\n\nThe `--serve` flag starts a browser-based dashboard for real-time monitoring of plan execution.\n\n```bash\nralphex --serve docs\u002Fplans\u002Ffeature.md\n# web dashboard: http:\u002F\u002Flocalhost:8080\n```\n\n### Features\n\n- **Real-time streaming** - SSE connection for live output updates\n- **Phase navigation** - filter by All\u002FTask\u002FReview\u002FCodex phases\n- **Collapsible sections** - organized output with expand\u002Fcollapse\n- **Text search** - find text with highlighting (keyboard: `\u002F` to focus, `Escape` to clear)\n- **Auto-scroll** - follows output, click to disable\n- **Late-join support** - new clients receive full history\n\nThe dashboard uses a dark theme with phase-specific colors matching terminal output. All file and stdout logging continues unchanged when using `--serve`.\n\n### Multi-Session Mode\n\nThe `--watch` flag enables monitoring multiple ralphex sessions simultaneously:\n\n```bash\n# watch specific directories for progress files\nralphex --serve --watch ~\u002Fprojects\u002Ffrontend --watch ~\u002Fprojects\u002Fbackend\n\n# configure watch directories in config file\n# watch_dirs = \u002Fhome\u002Fuser\u002Fprojects, \u002Fvar\u002Flog\u002Fralphex\n```\n\nMulti-session features:\n- **Session sidebar** - lists all discovered sessions, click to switch (keyboard: `S` to toggle)\n- **Active detection** - pulsing indicator for running sessions via file locking\n- **Auto-discovery** - new sessions appear automatically as they start\n\n## Claude Code Integration (Optional)\n\nralphex works standalone from the terminal. Optionally, you can add slash commands to Claude Code for a more integrated experience.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `\u002Fralphex` | Launch and monitor ralphex execution with interactive mode\u002Fplan selection |\n| `\u002Fralphex-plan` | Create structured implementation plans with guided context gathering |\n| `\u002Fralphex-update` | Smart-merge updated embedded defaults into customized prompts\u002Fagents |\n\n### Installation\n\nThe ralphex CLI is the primary interface. Claude Code skills (`\u002Fralphex`, `\u002Fralphex-plan`, and `\u002Fralphex-update`) are optional convenience commands.\n\n**Via Plugin Marketplace (Recommended)**\n\n```bash\n# Add ralphex marketplace\n\u002Fplugin marketplace add umputun\u002Fralphex\n\n# Install the plugin\n\u002Fplugin install ralphex@umputun-ralphex\n```\n\nBenefits: Auto-updates when marketplace refreshes (at Claude Code startup).\n\n**Manual Installation (Alternative)**\n\nThe slash command definitions are hosted at:\n- [`\u002Fralphex`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex.md)\n- [`\u002Fralphex-plan`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex-plan.md)\n- [`\u002Fralphex-update`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex-update.md)\n\nTo install, ask Claude Code to \"install ralphex slash commands\" or manually copy the files to `~\u002F.claude\u002Fcommands\u002F`.\n\n### Usage\n\nOnce installed:\n\n```\n# in Claude Code conversation\n\u002Fralphex-plan add user authentication    # creates plan interactively\n\u002Fralphex docs\u002Fplans\u002Fauth.md              # launches execution\n\"check ralphex\"                          # gets status update\n```\n\nThe `\u002Fralphex` command runs ralphex in the background and provides status updates on request. The `\u002Fralphex-plan` command guides you through creating well-structured plans with context discovery and approach selection.\n\n> **Note:** ralphex automatically strips the `CLAUDECODE` env var from child processes, allowing it to run from inside Claude Code. 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.\n\n## For LLMs\n\nSee [llms.txt](llms.txt) for LLM-optimized documentation.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n","\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_54eb4be2b533.png\" alt=\"ralphex\" width=\"400\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"build\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fcoveralls.io\u002Fgithub\u002Fumputun\u002Fralphex?branch=master\">\u003Cimg src=\"https:\u002F\u002Fcoveralls.io\u002Frepos\u002Fgithub\u002Fumputun\u002Fralphex\u002Fbadge.svg?branch=master\" alt=\"Coverage Status\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fumputun\u002Fralphex\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_2b4a70945b89.png\" alt=\"Go Report Card\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Ch2 align=\"center\">使用 Claude Code 的自主计划执行\u003C\u002Fh2>\n\n*ralphex 是一款独立的命令行工具，可在 Git 仓库根目录下的终端中运行。它通过协调 Claude Code 自主执行实现计划——无需 IDE 插件或云服务，只需 Claude Code 和一个二进制文件即可。*\n\nClaude Code 功能强大，但需要交互式操作：您必须实时观察、批准并指导每一步。对于涉及多个任务的复杂功能，这意味着需要花费数小时进行全程监控。更糟糕的是，在长时间会话中，上下文信息不断累积，模型的表现会逐渐下降——它可能会开始犯错、忘记之前的决策，从而生成质量较差的代码。\n\nralphex 则同时解决了这两个问题。每个任务都在全新的 Claude Code 会话中执行，上下文信息极少，因此在整个计划执行过程中，模型都能保持高效。只需编写包含任务和验证命令的计划，启动 ralphex，然后就可以离开。稍后再回来查看，您的功能已经实现、经过审查并提交到版本库；或者您可以查看进度日志，了解当前的执行情况。\n\n\u003Cdetails markdown>\n\u003Csummary>任务执行截图 \u003C\u002Fsummary>\n\n![ralphex tasks](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_e070296ea8f0.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary> 审查模式截图 \u003C\u002Fsummary>\n\n![ralphex review](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_081fd18e7eb9.png)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails markdown>\n\u003Csummary> Web 控制台截图 \u003C\u002Fsummary>\n\n![ralphex web dashboard](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_74eb72f79476.png)\n\n\u003C\u002Fdetails>\n\n## 特性\n\n- **零配置** - 开箱即用，采用合理默认值，无需任何配置\n- **自主任务执行** - 按照计划逐个执行任务，并自动重试\n- **交互式计划创建** - 通过 `--plan` 标志与 Claude 进行对话式创建计划\n- **多阶段代码审查** - 包括 5 个代理 → codex → 2 个代理的审查流程\n- **自定义审查代理** - 可通过 `{{agent:name}}` 模板系统和用户自定义提示进行配置\n- **自动分支创建** - 根据计划文件名创建 Git 分支\n- **计划完成跟踪** - 将已完成的计划移动到 `completed\u002F` 文件夹\n- **自动提交** - 在每个任务和审查修复后自动提交\n- **实时监控** - 流式输出，带有时间戳、颜色和详细日志\n- **Web 控制台** - 使用 `--serve` 标志可提供基于浏览器的实时视图\n- **Docker 支持** - 在隔离容器中运行，以实现更安全的自主执行\n- **通知功能** - 可选择通过 Telegram、电子邮件、Slack、Webhook 或自定义脚本在完成\u002F失败时接收提醒\n- **工作树隔离** - 使用 `--worktree` 标志可并行运行多个计划\n- **多种模式** - 完全执行、仅执行任务、仅审查、仅外部审查，或仅创建计划\n\n## 快速入门\n\n请确保已[安装](#installation) ralphex，并且您的项目是一个 Git 仓库。您需要在 `docs\u002Fplans\u002F` 中准备一个[计划文件](#plan-creation)，例如：\n\n```markdown\n# 计划：我的功能\n\n## 验证命令\n- `go test .\u002F...`\n\n### 任务 1：实现功能\n- [ ] 添加新功能\n- [ ] 添加测试\n```\n\n然后运行：\n\n```bash\nralphex docs\u002Fplans\u002Fmy-feature.md\n```\n\nralphex 将创建一个分支，执行任务，提交结果，进行多阶段审查，并在完成后将计划移动到 `completed\u002F` 文件夹。\n\n## 工作原理\n\nralphex 按照四个阶段执行计划，并进行自动化代码审查，最后还有一个可选的收尾步骤。\n\n\u003Cdetails markdown>\n\u003Csummary> 执行流程图 \u003C\u002Fsummary>\n\n![ralphex flow](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_readme_11ab961a4e9d.png)\n\n\u003C\u002Fdetails>\n\n### 第一阶段：任务执行\n\n1. 读取计划文件，找到第一个未完成的任务（格式为 `### Task N:`，带有 `- [ ]` 复选框）\n2. 将任务发送给 Claude Code 执行\n3. 每个任务完成后运行验证命令（如测试、代码检查工具）\n4. 将复选框标记为已完成 `[x]`，并提交更改\n5. 重复上述步骤，直到所有任务完成或达到最大迭代次数\n\n**中途控制：** 在任务执行过程中，按下 Ctrl+\\ (SIGQUIT) 可暂停执行。ralphex 会取消当前的 Claude 会话，并提示“按 Enter 继续，Ctrl+C 中止”。暂停期间，您可以编辑计划文件——按下 Enter 后，同一任务将以全新会话重新执行，并再次读取计划。按下 Ctrl+C 可干净地中止。此功能在 Windows 上不可用。\n\n### 第二阶段：首次代码审查\n\n通过 Claude Code 的 Task 工具**并行**启动 5 个审查代理：\n\n| 代理 | 目的 |\n|-------|---------|\n| `quality` | 检查 bug、安全问题和竞态条件 |\n| `implementation` | 验证代码是否实现了既定目标 |\n| `testing` | 检查测试覆盖率和质量 |\n| `simplification` | 检测过度设计 |\n| `documentation` | 检查文档是否需要更新 |\n\nClaude 会核实审查结果，修复确认的问题，并提交更改。\n\n*[默认代理](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Ftree\u002Fmaster\u002Fpkg\u002Fconfig\u002Fdefaults\u002Fagents) 提供通用的、与语言无关的审查步骤。它们可以根据您的具体需求、使用的编程语言和工作流程进行自定义和调整。有关详细信息，请参阅[自定义](#customization)部分。*\n\n### 第三阶段：外部审查（可选）\n\n1. 运行外部审查工具（默认为 codex，也可使用自定义脚本）\n2. Claude 评估审查结果，修复有效问题\n3. 重复上述步骤，直到没有未解决的问题\n\n循环将在以下情况下终止：所有问题均已解决、达到最大迭代次数、检测到僵局（通过 `--review-patience` 设置）或手动中断（按下 Ctrl+\\ (SIGQUIT)）。\n\n**僵局检测：** 当外部工具和 Claude 对审查结果无法达成一致时，循环可能会浪费大量 token 不断迭代至最大次数。设置 `--review-patience=N`（或在配置中设置 `review_patience`），以便在连续 N 轮没有提交或工作树发生变化时终止循环。\n\n**手动中断：** 在外部审查循环中按下 Ctrl+\\ (SIGQUIT) 可立即终止该循环。当前的执行过程将通过上下文取消而被终止。而在任务阶段，Ctrl+\\ 则用于暂停执行——请参阅[第一阶段：任务执行](#phase-1-task-execution)。此功能在 Windows 上不可用。\n\n支持的工具：\n- **codex**（默认）：OpenAI Codex，用于独立代码审查\n- **自定义**：您自己的脚本，可封装任何 AI（如 OpenRouter、本地 LLM 等）\n- **无**：完全跳过外部审查\n\n有关如何使用自定义脚本的详细信息，请参阅[自定义外部审查](#custom-external-review)。\n\n### 第四阶段：第二次代码审查\n\n1. 启动 2 个代理（`quality` + `implementation`）进行最终审查\n2. 重点关注关键或重大问题\n3. 重复上述步骤，直到没有发现任何问题\n4. 成功完成后，将计划移至 `completed\u002F` 文件夹\n\n*第二次审查代理可通过 `prompts\u002Freview_second.txt` 进行配置。*\n\n### 最终步骤（可选）\n\n在所有评审阶段成功完成后，ralphex 可以运行一个可选的最终步骤。默认情况下此功能已禁用。\n\n**作用：** 运行一次 Claude Code 会话，并使用可自定义的提示模板。默认的 `finalize.txt` 提示模板会将提交变基到默认分支上，并可选择性地将相关提交压缩成逻辑组。\n\n**如何启用：**\n\n在 `~\u002F.config\u002Fralphex\u002Fconfig` 或 `.ralphex\u002Fconfig` 中设置 `finalize_enabled = true`。\n\n**行为：**\n- 只运行一次（没有迭代循环）\n- 尽最大努力——失败会被记录，但不会阻止整体成功\n- 在具有评审流水线的模式下触发：完整模式、仅评审模式、仅外部模式\n- 使用任务颜色（绿色）输出\n\n**自定义：**\n\n编辑 `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt`（或 `.ralphex\u002Fprompts\u002Ffinalize.txt`），以更改评审后的操作。例如：推送到远程仓库、发送通知、运行部署脚本，或任何完成后的自动化流程。模板变量如 `{{DEFAULT_BRANCH}}` 均可使用。\n\n### 仅评审模式\n\n仅评审模式（`--review`）会对当前分支上已有的更改运行完整的评审流水线（阶段 2 → 阶段 3 → 阶段 4）。当更改是在 ralphex 外部进行时——例如通过 Claude Code 的内置计划模式、手动编辑、其他 AI 代理，或任何其他工作流——此模式非常有用。\n\n**工作流程：**\n\n1. 在特性分支上进行更改（使用任何工具或工作流）\n2. 提交更改\n3. 运行 `ralphex --review`\n\nralphex 会将该分支与默认分支进行比较（`git diff master...HEAD`），启动多智能体评审，并迭代修复直到所有智能体都报告无问题。无需提供计划文件——如果提供了，它将为评审者提供关于预期更改的额外上下文。\n\n```bash\n# 切换到包含现有更改的特性分支\ngit checkout feature-auth\n\n# 对这些更改运行评审流水线\nralphex --review\n\n# 可选地传递一个计划文件以提供上下文\nralphex --review docs\u002Fplans\u002Fadd-auth.md\n```\n\n### 工作树隔离\n\n`--worktree` 标志会在 `.ralphex\u002Fworktrees\u002F\u003Cbranch>` 下的一个隔离 Git 工作树中运行计划执行，从而允许在同一仓库上并行执行多个计划，而不会发生分支冲突。\n\n**支持的模式：** `--worktree` 仅适用于完整模式和 `--tasks-only` 模式。对于 `--review`、`--external-only` 和 `--plan` 模式，此标志会被静默忽略——这些模式直接在当前目录中运行。\n\n**在工作树分支上重新运行评审：** 如果任务阶段已在工作树中完成，但需要重新运行评审阶段，则可以进入工作树目录并在那里运行评审：\n\n```bash\n# 查找工作树\nls .ralphex\u002Fworktrees\u002F\n\n# 从工作树内部运行评审\ncd .ralphex\u002Fworktrees\u002Fmy-feature-branch\nralphex --review\n# 或\nralphex --external-only\n```\n\n工作树会在成功完成时自动删除。如果运行被中断，工作树目录可能会保留下来，可以再次使用或手动删除。\n\n### 计划创建\n\n计划可以通过多种方式创建：\n- **[Claude Code](#claude-code-integration-optional)** - 使用斜杠命令，如 `\u002Fralphex-plan`，或您自己的规划工作流\n- **手动** - 直接在 `docs\u002Fplans\u002F` 中编写 Markdown 文件\n- **`--plan` 标志** - 集成选项，可处理整个流程\n- **自动检测** - 如果在 master\u002Fmain 分支上不带参数运行 `ralphex`，且没有计划存在，则会提示创建计划\n\n`--plan` 标志提供了一个更简单的集成体验：\n\n```bash\nralphex --plan \"添加健康检查端点\"\n```\n\nClaude 会探索您的代码库，通过终端选择器（fzf 或数字回退）提出澄清问题，并在 `docs\u002Fplans\u002F` 中生成一个完整的计划文件。在审查草稿时，您可以接受、通过文本反馈进行修改、在 `$EDITOR` 中打开以进行交互式注释，或拒绝该计划。\n\n**示例会话：**\n```\n$ ralphex --plan \"为 API 响应添加缓存\"\n[10:30:05] 分析代码库结构...\n[10:30:12] 发现 pkg\u002Fstore\u002F 中已有存储层\n\n问题：使用哪种缓存后端？\n  > Redis\n    内存缓存\n    文件缓存\n    其他（输入您自己的答案）\n\n[10:30:45] 回答：Redis\n[10:31:00] 继续创建计划...\n[10:32:05] 计划已写入 docs\u002Fplans\u002Fadd-api-caching.md\n\n是否继续执行计划？\n  > 是，执行计划\n    否，退出\n```\n\n计划创建完成后，您可以选择立即执行计划，或退出以便稍后再运行 ralphex。进度会记录在 `.ralphex\u002Fprogress\u002Fprogress-plan-\u003Cname>.txt` 中。\n\n## 安装\n\n### 从源码安装\n\n```bash\ngo install github.com\u002Fumputun\u002Fralphex\u002Fcmd\u002Fralphex@latest\n```\n\n### 使用 Homebrew\n\n```bash\nbrew install umputun\u002Fapps\u002Fralphex\n```\n\n### 从发布版本下载\n\n从 [releases](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Freleases) 下载合适的二进制文件。\n\n### 使用 Docker\n\n下载包装脚本并安装到 PATH 中：\n\n```bash\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Fumputun\u002Fralphex\u002Fmaster\u002Fscripts\u002Fralphex-dk.sh -o \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\n```\n\n该脚本默认使用 Go 镜像（`ralphex-go`）。对于其他语言，您可以基于基础镜像构建自定义镜像，并在其中安装您的工具链（示例请参见 [可用镜像](#available-images)），然后通过以下环境变量指向该镜像：\n```bash\nexport RALPHEX_IMAGE=my-ralphex\n```\n\n之后即可正常使用 `ralphex`，它会在一个预装了 Claude Code 和 Codex 的容器中运行。脚本启动时会显示当前使用的镜像。\n\n**为什么使用 Docker？** ralphex 以 `--dangerously-skip-permissions` 参数运行 Claude Code，这使其拥有执行命令和修改文件的完全权限。而在容器中运行可以提供隔离——Claude 只能访问挂载的项目目录，而无法触及您的整个系统。这种机制使得自主执行变得更加安全。\n\n\u003Cdetails markdown>\n\u003Csummary>隔离细节\u003C\u002Fsummary>\n\n**容器可访问（读写）：**\n- 挂载在 `\u002Fworkspace` 的项目目录——对文件的创建、修改和删除具有完全权限\n- 项目内的 Git 操作（分支、提交等）\n\n**容器可访问（只读）：**\n- `~\u002F.claude\u002F`——凭据和设置（启动时复制，不会被修改）\n- `~\u002F.codex\u002F`——如果存在，则包含 Codex 凭据\n- `~\u002F.config\u002Fralphex\u002F`——用户级别的 ralphex 配置\n- `~\u002F.gitconfig`——用于提交的 Git 用户身份\n- 全局 `.gitignore` 文件（`core.excludesFile`）——自动检测并挂载\n- `.ralphex\u002F`——如果存在，则为项目级配置\n\n**容器不可访问：**\n- 挂载目录之外的主机文件系统\n- 其他项目或仓库\n- `~\u002F.ssh`、`~\u002F.aws` 等目录中的 SSH 密钥、AWS 凭据或其他敏感信息\n- 系统文件、二进制文件或配置\n- 其他正在运行的进程或容器\n\n**网络：** 完全网络访问（Claude API 调用所需）\n\n**权限：** 以非 root 用户身份运行，无任何提升的权限\n\n\u003C\u002Fdetails>\n\n**卷挂载：**\n- **只读**：`~\u002F.claude` 和 `~\u002F.codex` 挂载到 `\u002Fmnt\u002F`，启动时复制以保持隔离\n- **读写**：项目目录（`\u002Fworkspace`）——ralphex 在此创建分支、编辑代码并提交\n- **额外挂载**：通过 `-v`\u002F`--volume` 标志或 `RALPHEX_EXTRA_VOLUMES` 环境变量指定的自定义卷\n\n**要求：**\n- Python 3.9 或更高版本（用于包装脚本）\n- 已安装并运行的 Docker\n- `~\u002F.claude\u002F` 中的 Claude Code 凭据（或在设置了 `$CLAUDE_CONFIG_DIR` 时使用该目录）\n- `~\u002F.codex\u002F` 中的 Codex 凭据（可选，用于 Codex 审查阶段）\n- `~\u002F.gitconfig` 中的 Git 配置（用于提交）\n\n**环境变量：**\n- `RALPHEX_IMAGE`——要使用的 Docker 镜像（默认：`ghcr.io\u002Fumputun\u002Fralphex-go:latest`）\n- `RALPHEX_PORT`——使用 `--serve` 时 Web 仪表盘的端口（默认：`8080`）\n- `RALPHEX_CONFIG_DIR`——自定义配置目录（默认：`~\u002F.config\u002Fralphex`）。覆盖全局配置位置，用于提示词、代理和设置\n- `CLAUDE_CONFIG_DIR`——Claude 配置目录（默认：`~\u002F.claude`）。可用于替代的 Claude 安装路径（例如 `~\u002F.claude2`）。无论是在 Docker 包装器中（通过卷挂载和钥匙串派生）还是非 Docker 使用场景中（直接传递给 Claude Code），都能正常工作。钥匙串服务名称会根据路径自动派生。\n- `RALPHEX_EXTRA_VOLUMES`——额外的卷挂载，以逗号分隔（例如 `\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels`）。未包含冒号的条目将被静默忽略。\n- `RALPHEX_EXTRA_ENV`——额外的环境变量，以逗号分隔（例如 `DEBUG=1,API_KEY`）。格式为 `VAR=value` 或 `VAR`（从宿主机继承）。对于包含敏感名称（KEY、SECRET、TOKEN 等）且显式赋值的情况，会发出安全警告——建议仅使用变量名形式来传递敏感凭据。\n- `RALPHEX_DOCKER_SOCKET`——启用 Docker 套接字挂载：`1`、`true` 或 `yes`（仅限 Docker 包装器）。命令行标志：`--docker`\n- `RALPHEX_DOCKER_NETWORK`——Docker 网络模式（例如 `host`、`my-network`）。适用于访问 docker-compose 服务。命令行标志：`--network`\n- `TZ`——覆盖容器时区（默认：根据 `\u002Fetc\u002Flocaltime` 自动检测宿主机时区）。示例：`TZ=Europe\u002FBerlin ralphex docs\u002Fplans\u002Ffeature.md`\n- `RALPHEX_CLAUDE_PROVIDER`——Claude 提供商模式：`default` 或 `bedrock`（仅限 Docker 包装器）\n\n**Docker 套接字支持：**\n\n`--docker` 标志（或 `RALPHEX_DOCKER_SOCKET=1`）会将宿主机的 Docker 套接字挂载到容器中，从而支持 testcontainers 和依赖 Docker 的工作流：\n\n```bash\nralphex --docker docs\u002Fplans\u002Ffeature.md\nralphex --docker --dry-run   # 验证套接字挂载是否成功\n```\n\n- 自动检测套接字的 GID，并传递 `DOCKER_GID` 环境变量以便在基础镜像中设置组权限\n- 在 Linux 系统上会发出安全警告（macOS 由于虚拟机隔离，无需警告）\n- 如果套接字文件不存在，则会立即报错（快速失败，不会出现无声降级）\n\n**AWS Bedrock 支持：**\n\n当设置 `--claude-provider bedrock` 或 `RALPHEX_CLAUDE_PROVIDER=bedrock` 时：\n- 将跳过钥匙串凭据提取步骤（Bedrock 认证不需要）\n- AWS 凭据会通过 `aws configure export-credentials` 自动从 `AWS_PROFILE` 中导出\n- 必要的 Bedrock 环境变量会被传递到容器中：`CLAUDE_CODE_USE_BEDROCK`、`AWS_REGION` 以及相关凭据\n\nBedrock 所需的环境变量：\n- `AWS_REGION`——Bedrock 已启用的 AWS 地区\n- `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`\u002F`AWS_SECRET_ACCESS_KEY`——认证信息\n\n注意：使用 `--claude-provider bedrock` 时，会自动设置 `CLAUDE_CODE_USE_BEDROCK=1`。\n\n```bash\n# 使用 AWS 配置文件（凭据会自动导出）\nexport AWS_PROFILE=my-bedrock-profile\nexport AWS_REGION=us-east-1\nralphex --claude-provider bedrock docs\u002Fplans\u002Ffeature.md\n\n# 或者使用环境变量进行会话范围的设置\nexport RALPHEX_CLAUDE_PROVIDER=bedrock\nralphex docs\u002Fplans\u002Ffeature.md\n```\n\n有关详细的 IAM 策略和设置说明，请参阅 [Bedrock 设置文档](docs\u002Fbedrock-setup.md)。\n\n**额外的卷挂载：**\n```bash\n# 通过 CLI 标志（可多次使用 -v）\nralphex -v \u002Fdata:\u002Fmnt\u002Fdata:ro -v \u002Fmodels:\u002Fmnt\u002Fmodels docs\u002Fplans\u002Ffeature.md\n\n# 通过环境变量（以逗号分隔）\nRALPHEX_EXTRA_VOLUMES=\"\u002Fdata:\u002Fmnt\u002Fdata:ro,\u002Fmodels:\u002Fmnt\u002Fmodels\" ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**额外的环境变量：**\n```bash\n# 通过 CLI 标志（可多次使用 -E）\nralphex -E DEBUG=1 -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# 通过环境变量（以逗号分隔）\nRALPHEX_EXTRA_ENV=\"DEBUG=1,LOG_LEVEL=verbose\" ralphex docs\u002Fplans\u002Ffeature.md\n\n# 仅使用变量名的形式会从宿主机继承值（推荐用于敏感信息）\nexport API_KEY=secret123\nralphex -E API_KEY docs\u002Fplans\u002Ffeature.md\n\n# 包含逗号的值需要使用 -E 标志（环境变量按逗号分隔）\nralphex -E \"TAGS=foo,bar,baz\" docs\u002Fplans\u002Ffeature.md\n```\n\n**调试：**\n```bash\nralphex --dry-run docs\u002Fplans\u002Ffeature.md  # 显示 docker 命令但不执行\n```\n\n`--dry-run` 标志会打印出原本要执行的完整 `docker run` 命令。这在调试容器配置或复制命令以手动执行时非常有用。\n\n注意：继承的环境变量（例如 `-E FOO` 而没有 `=value`）在将命令复制到不同 shell 中时可能无法正常工作。为了保证可移植性，请使用显式指定的值。\n\n**更新：**\n```bash\nralphex --update         # 拉取最新的 Docker 镜像\nralphex --update-script  # 更新包装脚本本身\n```\n\n\u003Ca id=\"available-images\">\u003C\u002Fa>\n\u003Cdetails markdown>\n\u003Csummary>可用镜像\u003C\u002Fsummary>\n\n目前发布了两个镜像：\n\n| 镜像 | 描述 |\n|-------|-------------|\n| `ghcr.io\u002Fumputun\u002Fralphex:latest` | 基础镜像，包含 Claude Code、Codex 和核心工具 |\n| `ghcr.io\u002Fumputun\u002Fralphex-go:latest` | Go 开发环境（在基础镜像基础上扩展了 Go 工具链） |\n\n**基础镜像包含：**\n\n| 工具 | 版本 | 用途 |\n|------|---------|---------|\n| Claude Code | 最新版本 | AI 编程助手 |\n| Codex | 最新版本 | 外部代码审查 |\n| Node.js\u002Fnpm | 24.x | Claude Code 所需 |\n| Python\u002Fpip | 3.x | 脚本和自动化 |\n| git | 2.x | 版本控制 |\n| docker-cli | - | Docker 客户端，用于容器工作流 |\n| make | 4.x | 构建自动化 |\n| gcc, musl-dev | - | 用于原生扩展的 C 编译器 |\n| bash | 5.x | Shell |\n| fzf | - | 用于计划选择的模糊查找工具 |\n| ripgrep | - | 快速搜索工具（Claude Code 使用） |\n\n**Go 镜像额外添加：**\n\n| 工具 | 版本 | 用途 |\n|------|---------|---------|\n| Go | 1.26.0 | Go 编译器和运行时 |\n| golangci-lint | 最新版本 | Go 代码检查工具 |\n| moq | 最新版本 | Mock 生成工具 |\n| goimports | 最新版本 | 导入语句格式化工具 |\n\n**对于 Go 项目**，请使用 `-go` 镜像：\n```bash\nRALPHEX_IMAGE=ghcr.io\u002Fumputun\u002Fralphex-go:latest ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n**对于其他语言**，可以通过在基础镜像上扩展你的语言工具链来创建自定义镜像。Go 镜像（`Dockerfile-go`）展示了这种模式：\n\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# 从官方渠道安装 Go\nARG GO_VERSION=1.26.0\nRUN ARCH=$(uname -m | sed 's\u002Fx86_64\u002Famd64\u002F;s\u002Faarch64\u002Farm64\u002F') && \\\n    wget -qO- \"https:\u002F\u002Fgo.dev\u002Fdl\u002Fgo${GO_VERSION}.linux-${ARCH}.tar.gz\" | tar -xz -C \u002Fusr\u002Flocal\n\nENV GOROOT=\u002Fusr\u002Flocal\u002Fgo\nENV GOPATH=\u002Fhome\u002Fapp\u002Fgo\nENV PATH=\"${PATH}:${GOROOT}\u002Fbin:${GOPATH}\u002Fbin\"\n\n# 安装 Go 工具\nRUN wget -qO- https:\u002F\u002Fraw.githubusercontent.com\u002Fgolangci\u002Fgolangci-lint\u002FHEAD\u002Finstall.sh | sh -s -- -b \u002Fusr\u002Flocal\u002Fbin && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install github.com\u002Fmatryer\u002Fmoq@latest && \\\n    GOBIN=\u002Fusr\u002Flocal\u002Fbin go install golang.org\u002Fx\u002Ftools\u002Fcmd\u002Fgoimports@latest\n```\n\nRust、Java 或其他任何语言也可以采用相同的方法：\n```dockerfile\nFROM ghcr.io\u002Fumputun\u002Fralphex:latest\n\n# rust\nRUN apk add --no-cache rust cargo\nENV CARGO_HOME=\u002Fhome\u002Fapp\u002F.cargo PATH=\"${PATH}:${CARGO_HOME}\u002Fbin\"\n\n# java\nRUN apk add --no-cache openjdk21-jdk\nENV JAVA_HOME=\u002Fusr\u002Flib\u002Fjvm\u002Fjava-21-openjdk PATH=\"${PATH}:${JAVA_HOME}\u002Fbin\"\n```\n\n构建并使用：\n```bash\ndocker build -t my-ralphex -f Dockerfile.python .\nRALPHEX_IMAGE=my-ralphex ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n\u003C\u002Fdetails>\n\n带有自定义端口的示例：\n```bash\nRALPHEX_PORT=3000 ralphex --serve --port 3000 docs\u002Fplans\u002Ffeature.md\n```\n\n## 使用方法\n\n**注意：** ralphex 必须从仓库根目录（即 `.git` 所在的目录）运行。\n\n```bash\n# 执行计划，包含任务循环和评审\nralphex docs\u002Fplans\u002Ffeature.md\n\n# 使用 fzf 选择计划，或在没有计划时交互式创建一个\nralphex\n\n# 仅评审模式（跳过任务执行）\nralphex --review docs\u002Fplans\u002Ffeature.md\n\n# 仅外部评审模式（跳过任务和首次评审，只运行外部评审循环）\nralphex --external-only\n\n# 仅任务模式（只运行任务阶段，跳过所有评审）\nralphex --tasks-only docs\u002Fplans\u002Ffeature.md\n\n# 在隔离的 Git 工作树中运行（仅限完整模式和任务模式）\nralphex --worktree docs\u002Fplans\u002Ffeature.md\n\n# 覆盖默认分支以进行评审差异比较\nralphex --review --base-ref develop\nralphex --review --base-ref abc1234 --skip-finalize\n\n# 初始化当前项目的本地 .ralphex\u002F 配置文件（包含注释掉的默认值）\nralphex --init\n\n# 交互式创建计划\nralphex --plan \"添加用户认证\"\n\n# 使用自定义最大迭代次数\nralphex --max-iterations=100 docs\u002Fplans\u002Ffeature.md\n\n# 限制外部评审的迭代次数（0 表示自动计算，基于最大迭代次数）\nralphex --max-external-iterations=5 docs\u002Fplans\u002Ffeature.md\n\n# 当连续 3 轮评审结果未变化时终止外部评审（僵局检测）\nralphex --review-patience=3 docs\u002Fplans\u002Ffeature.md\n\n# 在达到速率限制时等待并重试，而不是直接退出\nralphex --wait 1h docs\u002Fplans\u002Ffeature.md\n\n# 设置会话超时时间，以结束挂起的 Claude 会话\nralphex --session-timeout 30m docs\u002Fplans\u002Ffeature.md\n\n# 当 Claude 会话 5 分钟内无输出时终止会话（空闲检测）\nralphex --idle-timeout 5m docs\u002Fplans\u002Ffeature.md\n\n# 启用 Web 控制台\nralphex --serve docs\u002Fplans\u002Ffeature.md\n\n# 在自定义端口上启用 Web 控制台\nralphex --serve --port 3000 docs\u002Fplans\u002Ffeature.md\n```\n\n### 选项\n\n| 标志 | 描述 | 默认值 |\n|------|-------------|---------|\n| `-m, --max-iterations` | 最大任务迭代次数 | 50 |\n| `--max-external-iterations` | 覆盖外部评审迭代限制（0 = 自动） | 0 |\n| `--review-patience` | 在连续 N 轮无变化后终止外部评审（0 = 禁用） | 0 |\n| `-r, --review` | 跳过任务执行，运行完整评审流程 | false |\n| `-e, --external-only` | 跳过任务和首次评审，仅运行外部评审循环 | false |\n| `-c, --codex-only` | `--external-only` 的别名（已弃用） | false |\n| `-t, --tasks-only` | 仅运行任务阶段，跳过所有评审 | false |\n| `-b, --base-ref` | 覆盖用于评审差异的默认分支（分支名称或提交哈希） | 自动检测 |\n| `--skip-finalize` | 即使配置中启用，也跳过最终步骤 | false |\n| `--wait` | 在达到速率限制后重试前的等待时长（例如 `1h`, `30m`） | 已禁用 |\n| `--session-timeout` | claude 每会话超时时间（例如 `30m`, `1h`）。会话挂起时将被终止 | 已禁用 |\n| `--idle-timeout` | 当指定时长内无输出时终止 claude 会话（例如 `5m`）。每输出一行则重置 | 已禁用 |\n| `--worktree` | 在隔离的 git 工作树中运行（仅限完整模式和仅任务模式） | false |\n| `--plan` | 交互式创建计划（需提供描述） | - |\n| `-s, --serve` | 启动用于实时流式的 Web 仪表板 | false |\n| `-p, --port` | Web 仪表板端口（与 `--serve` 一起使用） | 8080 |\n| `-w, --watch` | 监控进度文件的目录（可重复） | - |\n| `-d, --debug` | 启用调试日志记录 | false |\n| `--no-color` | 禁用彩色输出 | false |\n| `--init` | 在当前项目中初始化本地 `.ralphex\u002F` 配置 | - |\n| `--reset` | 交互式地将全局配置重置为内置默认值 | - |\n| `--dump-defaults` | 将原始内置默认值提取到指定目录 | - |\n| `--config-dir` | 自定义配置目录（环境变量：`RALPHEX_CONFIG_DIR`） | `~\u002F.config\u002Fralphex` |\n\n## 计划文件格式\n\n计划是包含任务部分的 Markdown 文件。每个任务都有复选框，由 claude 标记为已完成。\n\n```markdown\n# 计划：添加用户认证\n\n## 概述\n为 API 添加基于 JWT 的认证。\n\n## 验证命令\n- `go test .\u002F...`\n- `golangci-lint run`\n\n### 任务 1：添加认证中间件\n- [ ] 创建 JWT 验证中间件\n- [ ] 添加到受保护路由的路由器\n- [ ] 添加测试\n- [ ] 标记完成\n\n### 任务 2：添加登录端点\n- [ ] 创建 \u002Fapi\u002Flogin 处理程序\n- [ ] 在认证成功时返回 JWT\n- [ ] 添加测试\n- [ ] 标记完成\n```\n\n**要求：**\n- 任务标题必须使用 `### Task N:` 或 `### Iteration N:` 格式（N 可以是整数或非整数，如 `2.5`, `2a`）\n- 复选框：`- [ ]`（未完成）或 `- [x]`（已完成）\n- 复选框只能出现在任务部分（`### Task N:` 或 `### Iteration N:`）。不要在成功标准、概述或上下文中放置复选框——它们会导致额外的循环迭代。代理在遇到这些复选框时会优雅地处理，但为了最佳效果，计划作者应避免使用它们。\n- 包含 `## 验证命令` 部分，并列出测试\u002F静态分析命令\n- 将计划放在 `docs\u002Fplans\u002F` 目录中（可通过 `plans_dir` 配置）\n\n## 评审代理\n\n评审流程完全可定制。ralphex 提供了适用于任何语言的合理默认设置，但您可以根据自己的工作流程修改代理、添加新代理或完全替换提示词。\n\n### 默认代理\n\n这 5 个代理涵盖了常见的评审关注点，开箱即用效果良好。您可以根据需要自定义或替换它们：\n\n| 代理 | 阶段 | 目的 |\n|-------|-------|---------|\n| `quality` | 第一和第二轮 | 检测 bug、安全问题、竞态条件 |\n| `implementation` | 第一和第二轮 | 验证代码是否实现既定目标 |\n| `testing` | 仅第一轮 | 测试覆盖率和质量 |\n| `simplification` | 仅第一轮 | 检测过度工程化 |\n| `documentation` | 仅第一轮 | 检查文档是否需要更新 |\n\n### 代理选项（YAML 前言）\n\n代理文件支持可选的 YAML 前言，用于代理的个性化配置：\n\n```txt\n---\nmodel: haiku\nagent: code-reviewer\n---\n审查代码中的质量问题……\n```\n\n| 选项 | 取值 | 描述 |\n|--------|--------|-------------|\n| `model` | `haiku`, `sonnet`, `opus` | 此代理使用的 Claude 模型 |\n| `agent` | 任意字符串 | Claude Code Task 工具的子代理类型 |\n\n这两个选项均为可选。如果没有前言，代理将使用默认模型和 `general-purpose` 子代理类型。完整的模型 ID（如 `claude-sonnet-4-5-20250929`）会被标准化为简短关键词（`sonnet`），因为 Claude Code 只接受 `haiku`、`sonnet` 和 `opus`。无效的模型值将被忽略，并发出警告。\n\n### 模板语法\n\n自定义提示文件支持变量扩展。所有变量均采用 `{{VARIABLE}}` 语法。\n\n**可用变量：**\n\n| 变量 | 描述 | 示例值 |\n|----------|-------------|---------------|\n| `{{PLAN_FILE}}` | 正在执行的计划文件路径 | `docs\u002Fplans\u002Ffeature.md` |\n| `{{PROGRESS_FILE}}` | 进度日志文件路径 | `.ralphex\u002Fprogress\u002Fprogress-feature.txt` |\n| `{{GOAL}}` | 人类可读的目标描述 | `docs\u002Fplans\u002Ffeature.md 中计划的实现` |\n| `{{DEFAULT_BRANCH}}` | 默认分支名称（可通过 `--base-ref` 或 `default_branch` 配置覆盖） | `main`, `master`, `origin\u002Fmain` |\n| `{{agent:name}}` | 展开为指定代理的任务工具指令 | （见下文） |\n\n**代理引用：**\n\n在提示文件中使用 `{{agent:name}}` 语法引用代理：\n\n```\n并行启动以下评审代理：\n{{agent:quality}}\n{{agent:implementation}}\n{{agent:testing}}\n```\n\n每个 `{{agent:name}}` 都会展开为 Task 工具指令，指示 Claude Code 运行该代理。代理内容中的变量也会被展开，因此代理可以使用 `{{DEFAULT_BRANCH}}` 或其他变量。\n\n### 自定义\n\n整个系统专为自定义而设计，无论是任务执行还是评审：\n\n**代理文件**（`~\u002F.config\u002Fralphex\u002Fagents\u002F`）：\n- 首次运行时，ralphex 会安装 5 个默认的代理文件作为注释掉的模板。这些文件仅作为示例——虽然完全被注释掉，但它们并不会生效，实际使用的是内置的默认设置。取消注释并编辑即可进行自定义。\n- 每个代理都有文件级回退机制：ralphex 会依次检查本地 `.ralphex\u002Fagents\u002F` → 全局 `~\u002F.config\u002Fralphex\u002Fagents\u002F` → 内置默认设置。内置的 5 个代理始终是基础配置——即使从磁盘上删除某个代理文件，也不会禁用它，系统仍会使用内置版本作为回退。\n- 若要禁用特定代理，只需将其 `{{agent:name}}` 引用从提示文件中移除（如 `review_first.txt`、`review_second.txt`），而无需删除代理文件本身。\n- 可以添加新的 `.txt` 文件来创建自定义代理，并在提示文件中通过 `{{agent:name}}` 引用它们。\n- 运行 `ralphex --init` 可以创建包含注释默认值的本地 `.ralphex\u002F` 项目配置。\n- 运行 `ralphex --reset` 可以交互式地恢复默认设置，或手动删除所有文件。\n- 运行 `ralphex --dump-defaults \u003Cdir>` 可以提取原始默认设置以便比较。\n- 使用 `\u002Fralphex-update` Claude Code 技能可以将更新后的默认设置智能合并到自定义文件中。\n- 或者，也可以直接在提示文件中引用已安装在 Claude Code 中的代理（见下文示例）。\n\n**提示文件**（`~\u002F.config\u002Fralphex\u002Fprompts\u002F`）：\n- `task.txt` - 任务执行提示\n- `review_first.txt` - 综合评审（默认：5 个语言无关的代理——质量、实现、测试、简化、文档；可自定义）\n- `codex.txt` - Codex 评估提示（Claude 评估 Codex 的输出）\n- `codex_review.txt` - Codex 评审提示（发送至 Codex 外部评审工具）\n- `custom_review.txt` - 自定义外部评审提示（发送至自定义评审脚本）\n- `custom_eval.txt` - 自定义评估提示（Claude 评估自定义工具的输出）\n- `review_second.txt` - 最终评审，仅关注关键\u002F重大问题（默认：2 个代理——质量、实现；可自定义）\n- `make_plan.txt` - 交互式计划创建提示\n- `finalize.txt` - 可选的最终步骤提示（默认关闭）\n\n**注释行和 Markdown 标题**：\n文件顶部连续出现 2 行及以上的注释行（以 `#` 开头）会被视为元注释，并在加载时被移除。而文件顶部单独的一行 `# 标题` 则会被保留（被视为 Markdown 标题）。文件主体中后续出现的注释行则会始终保留：\n\n```txt\n# 这一行标题会被保留为 Markdown 标题\n检查 SQL 注入\n# 这条位于文件中间的注释也会被保留\n检查 XSS\n```\n\n如果文件*仅*包含注释行（每行都以 `#` 开头），则会被视为未修改的模板，并回退到内置默认设置。这就是注释掉的默认文件的工作方式——一旦添加任何非注释内容，文件就会按原样使用。\n\n注意：不支持内联注释（`text # comment` 会保留整行内容）。\n\n**示例**：\n- 为金融科技项目添加一个专注于安全的代理。\n- 如果不担心过度工程化，可以从提示文件中移除 `{{agent:simplification}}`。\n- 创建针对特定语言的代理（如 Python 代码风格检查、TypeScript 类型检查）。\n- 修改提示以调整每个阶段运行的代理数量。\n\n**直接使用 Claude Code 代理**：\n\n无需创建代理文件，可以直接在提示文件中引用已安装在 Claude Code 中的代理：\n\n```txt\n# 在 review_first.txt 中，只需列出代理名称及其提示\n要启动的代理：\n1. qa-expert - “审查 bug 和安全问题”\n2. go-test-expert - “审查测试覆盖率和质量”\n3. go-smells-expert - “审查代码异味”\n```\n\n## 要求\n\n- `claude` - Claude Code CLI\n- `fzf` - 用于选择计划（可选）\n- `codex` - 用于外部评审（可选）\n\n## 配置\n\nralphex 使用位于 `~\u002F.config\u002Fralphex\u002F` 的配置目录（可通过 `--config-dir` 或 `RALPHEX_CONFIG_DIR` 覆盖），其结构如下：\n\n```\n~\u002F.config\u002Fralphex\u002F\n├── config              # 主配置文件（INI 格式）\n├── prompts\u002F            # 自定义提示模板\n│   ├── task.txt\n│   ├── review_first.txt\n│   ├── review_second.txt\n│   ├── codex.txt\n│   ├── codex_review.txt\n│   ├── custom_review.txt\n│   ├── custom_eval.txt\n│   ├── make_plan.txt\n│   └── finalize.txt\n└── agents\u002F             # 自定义评审代理（*.txt 文件）\n```\n\n首次运行时，ralphex 会创建该目录并配备默认配置。\n\n**注释模板**：\n- 配置文件的所有内容都被注释掉（以 `#` 为前缀）。\n- 只需取消您想要自定义的设置的注释。\n- 如果文件始终保持全部注释状态，则会在新默认设置发布时自动更新。\n- 一旦取消对某项设置的注释，该文件将被保留，不会被覆盖。\n\n### 本地项目配置\n\n项目可以在项目根目录下创建 `.ralphex\u002F` 目录来覆盖全局设置。运行 `ralphex --init` 即可创建一个包含注释默认值的目录：\n\n```\nproject\u002F\n├── .ralphex\u002F           # 可选，项目本地配置\n│   ├── config          # 覆盖特定设置\n│   ├── prompts\u002F        # 该项目的自定义提示\n│   └── agents\u002F         # 该项目的自定义代理\n```\n\n**优先级**：CLI 标志 > 本地 `.ralphex\u002F` > 全局 `~\u002F.config\u002Fralphex\u002F` > 内置默认设置\n\n使用 `--config-dir` 或 `RALPHEX_CONFIG_DIR` 可以覆盖全局配置的位置。这对于为不同工作流维护独立的代理\u002F提示集合非常有用。\n\n**合并行为**：\n- **配置文件**：逐字段覆盖（本地值优先于全局值，缺失字段则回退）\n- **提示文件**：文件级回退（本地 → 全局 → 内置，默认值，每个提示文件独立）\n- **代理文件**：文件级回退（本地 → 全局 → 内置，默认值，每个代理文件独立，与提示文件相同）\n\n### 配置选项\n\n| 选项 | 描述 | 默认值 |\n|--------|-------------|---------|\n| `claude_command` | Claude CLI 命令 | `claude` |\n| `claude_args` | Claude CLI 参数 | `--dangerously-skip-permissions --output-format stream-json --verbose` |\n| `codex_enabled` | 启用 Codex 审查阶段 | `true` |\n| `codex_command` | Codex CLI 命令 | `codex` |\n| `codex_model` | Codex 模型 ID | `gpt-5.4` |\n| `codex_reasoning_effort` | 推理努力程度 | `xhigh` |\n| `codex_timeout_ms` | Codex 超时时间（毫秒） | `3600000` |\n| `codex_sandbox` | 沙盒模式 | `read-only` |\n| `external_review_tool` | 外部审查工具（`codex`、`custom`、`none`） | `codex` |\n| `custom_review_script` | 自定义审查脚本路径（当 `external_review_tool = custom` 时） | - |\n| `max_external_iterations` | 覆盖外部审查迭代次数限制（0 = 自动，基于 `max_iterations` 计算） | `0` |\n| `review_patience` | 连续 N 轮未变化后终止外部审查（0 = 禁用） | `0` |\n| `iteration_delay_ms` | 迭代之间延迟 | `2000` |\n| `task_retry_count` | 任务重试次数 | `1` |\n| `finalize_enabled` | 审查后启用最终完成步骤 | `false` |\n| `use_worktree` | 在隔离的 git 工作树中运行每个计划（仅限完整模式和仅任务模式） | `false` |\n| `plans_dir` | 计划目录 | `docs\u002Fplans` |\n| `default_branch` | 覆盖自动检测的默认分支以用于审查差异 | 自动检测 |\n| `vcs_command` | 用于 git 后端的 VCS 命令（对于 hg 仓库设置为翻译脚本） | `git` |\n| `commit_trailer` | 追加到所有 ralphex 协调的 git 提交末尾的尾行 | 禁用 |\n| `color_task` | 任务执行阶段颜色（十六进制） | `#00ff00` |\n| `color_review` | 审查阶段颜色（十六进制） | `#00ffff` |\n| `color_codex` | Codex 审查颜色（十六进制） | `#ff00ff` |\n| `color_claude_eval` | Claude 评估颜色（十六进制） | `#64c8ff` |\n| `color_warn` | 警告消息颜色（十六进制） | `#ffff00` |\n| `color_error` | 错误消息颜色（十六进制） | `#ff0000` |\n| `color_signal` | 完成\u002F失败信号颜色（十六进制） | `#ff6464` |\n| `color_timestamp` | 时间戳前缀颜色（十六进制） | `#8a8a8a` |\n| `color_info` | 信息性消息颜色（十六进制） | `#b4b4b4` |\n| `claude_error_patterns` | 在 Claude 输出中检测的模式（逗号分隔） | `You've hit your limit,API Error:,cannot be launched inside another Claude Code session` |\n| `codex_error_patterns` | 在 Codex 输出中检测的模式（逗号分隔） | `Rate limit,quota exceeded` |\n| `claude_limit_patterns` | 触发等待+重试的 Claude 限流模式（逗号分隔） | `You've hit your limit` |\n| `codex_limit_patterns` | 触发等待+重试的 Codex 限流模式（逗号分隔） | `Rate limit,quota exceeded` |\n| `wait_on_limit` | 限流后重试前的等待时长（例如 `1h`, `30m`） | 禁用 |\n| `session_timeout` | Claude 的会话超时时间（例如 `30m`, `1h`）。终止挂起的会话 | 禁用 |\n| `idle_timeout` | 当指定时间内无输出时终止 Claude 会话（例如 `5m`）。每输出一行则重置 | 禁用 |\n\n颜色使用 24 位 RGB（真彩色），所有现代终端（iTerm2、Kitty、Terminal.app、Windows Terminal、GNOME 终端、Alacritty、Zed、VS Code 等）均原生支持。旧版终端会优雅降级。使用 `--no-color` 可完全禁用颜色。\n\n错误模式采用不区分大小写的子字符串匹配。当在 Claude 或 Codex 输出中检测到模式时，ralphex 会优雅退出，并显示提示信息，建议如何检查使用情况或状态。多个模式用逗号分隔，每个模式前后会去除空格。\n\n**限流重试：** 限流模式（`claude_limit_patterns`、`codex_limit_patterns`）功能类似，但支持可选的等待+重试行为。当设置了 `--wait`（或配置中的 `wait_on_limit`）时，匹配限流模式会触发等待，随后自动重试，而不是直接退出。如果没有 `--wait`，限流模式将退化为错误模式的行为。限流模式会在错误模式之前被检查——如果同一字符串同时匹配两者，则在启用等待时，限流模式优先。\n\n### 自定义提示\n\n将自定义提示文件放置在 `~\u002F.config\u002Fralphex\u002Fprompts\u002F` 目录下，以覆盖内置提示。缺失的文件将回退到嵌入式默认值。有关代理自定义，请参阅“审查代理”部分。\n\n### 自定义外部审查\n\n使用您自己的 AI 工具进行外部代码审查，而非 Codex。这允许与 OpenRouter、本地 LLM 或任何自定义流程集成。\n\n**配置：**\n\n```ini\n# 在 ~\u002F.config\u002Fralphex\u002Fconfig 中\nexternal_review_tool = custom\ncustom_review_script = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\n```\n\n**脚本接口：**\n\n您的脚本接收一个参数：包含审查指令的提示文件路径。脚本将发现结果输出到 stdout，ralphex 将其传递给 Claude 进行评估和修复。\n\n```bash\n#!\u002Fbin\u002Fbash\n# 示例：~\u002F.config\u002Fralphex\u002Fscripts\u002Fmy-review.sh\nprompt_file=\"$1\"\n\n# 读取提示（包含差异指令、目标、审查重点）\nprompt=$(cat \"$prompt_file\")\n\n# 调用您的 AI 工具（OpenRouter、本地 LLM 等）\n# 以 curl 调用 OpenRouter 为例：\ncurl -s https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions \\\n  -H \"Authorization: Bearer $OPENROUTER_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d \"{\n    \\\"model\\\": \\\"anthropic\u002Fclaude-3.5-sonnet\\\",\n    \\\"messages\\\": [{\\\"role\\\": \\\"user\\\", \\\"content\\\": $(echo \"$prompt\" | jq -Rs .)}]\n  }\" | jq -r '.choices[0].message.content'\n```\n\n**预期输出格式：**\n\n- 将发现结果以结构化列表形式写入 stdout\n- 格式为：`文件:行 - 问题描述`\n- 如果没有问题，则输出 `NO ISSUES FOUND`\n\n**迭代行为：**\n\n外部审查循环默认最多运行 `max(3, max_iterations\u002F5)` 次迭代。可通过 `max_external_iterations` 配置选项或 `--max-external-iterations` CLI 标志进行覆盖（0 = 自动）。\n\n提示中的 `{{DIFF_INSTRUCTION}}` 变量会根据每次迭代调整：\n- **第一次迭代**：`git diff main...HEAD`（功能分支中的所有更改）\n- **后续迭代**：`git diff`（仅包含上次修复后的未提交更改）\n\n这样可以让审查工具专注于修复后剩余的问题。\n\n### 通知\n\nralphex 可在执行完成或失败时发送通知。通知为可选，默认关闭，且为尽力而为的服务——失败会被记录，但绝不会影响退出代码。\n\n```ini\n\n# 在 ~\u002F.config\u002Fralphex\u002Fconfig 或 .ralphex\u002Fconfig 中\nnotify_channels = telegram, webhook\nnotify_telegram_token = 123456:ABC-DEF\nnotify_telegram_chat = -1001234567890\nnotify_webhook_urls = https:\u002F\u002Fhooks.example.com\u002Fnotify\n```\n\n支持的通道：`telegram`、`email`、`slack`、`webhook`、`custom`（脚本）。配置错误的通道会在启动时被检测到。\n\n请参阅[通知文档](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fnotifications.md)，了解设置指南、消息格式示例以及自定义脚本集成方法。\n\n**提示自定义：**\n\n通过自定义 `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_review.txt` 来修改发送给您的脚本的提示。可用变量：\n- `{{DIFF_INSTRUCTION}}` - 当前迭代适用的 git diff 命令\n- `{{GOAL}}` - 正在实现的内容的人类可读描述\n- `{{PLAN_FILE}}` - 计划文件的路径\n- `{{PROGRESS_FILE}}` - 包含先前评审迭代的进度日志文件路径\n- `{{DEFAULT_BRANCH}}` - 检测到的默认分支（main、master 等）\n- `{{PREVIOUS_REVIEW_CONTEXT}}` - 上一次评审上下文（首次迭代为空，后续会填充）\n\n通过自定义 `~\u002F.config\u002Fralphex\u002Fprompts\u002Fcustom_eval.txt` 来修改 Claude 如何评估您工具的输出。\n\n**Docker 注意事项：**\n\n在 Docker 中运行 ralphex 时，您的脚本必须在容器内可访问：\n- 挂载您的脚本目录：`-v ~\u002F.config\u002Fralphex\u002Fscripts:\u002Fhome\u002Fapp\u002F.config\u002Fralphex\u002Fscripts:ro`\n- 确保脚本依赖项可用（curl、jq 等包含在基础镜像中）\n- 必须将环境变量（API 密钥）传递给容器：`-e OPENROUTER_API_KEY`\n\n### 使用替代提供商进行 Claude 阶段\n\n`claude_command` 和 `claude_args` 配置选项允许您用任何能产生兼容 `stream-json` 输出的 CLI 替换 Claude Code。这意味着 codex、Gemini CLI、本地 LLM 或其他工具都可以驱动任务执行和评审阶段——您只需要一个能够转换工具输出格式的包装脚本。\n\n提供了一个可用示例：[`scripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fcodex-as-claude\u002Fcodex-as-claude.sh) 包装了 codex，以生成与 Claude 兼容的事件。要使用它：\n\n```ini\n# 在 ~\u002F.config\u002Fralphex\u002Fconfig 或 .ralphex\u002Fconfig 中\nclaude_command = \u002Fpath\u002Fto\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\n将 `claude_args` 设置为空是可选的。请注意，由于配置回退行为，默认的 Claude 标志（`--dangerously-skip-permissions`、`--output-format stream-json`、`--verbose`）仍可能被传递。包装脚本应优雅地忽略未知标志——附带的脚本通过其 `*) shift ;;` 通配符来实现这一点。\n\n该包装脚本支持以下环境变量：\n- `CODEX_MODEL` - 要使用的 codex 模型（默认：codex 默认模型）\n- `CODEX_SANDBOX` - 沙盒模式（默认：`danger-full-access`）\n- `CODEX_VERBOSE` - 设置为 `1` 可以将命令执行输出包含在流中（默认：`0`，仅显示代理消息）\n\n请参阅[自定义提供商文档](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md)，获取编写其他提供商包装脚本的详细指南。\n\n### 可配置的 VCS 后端\n\nralphex 可以通过 `vcs_command` 配置选项和自定义提示文件与 Mercurial 仓库配合使用。\n\n```ini\n# 在 ~\u002F.config\u002Fralphex\u002Fconfig 或 .ralphex\u002Fconfig 中\nvcs_command = ~\u002F.config\u002Fralphex\u002Fscripts\u002Fhg2git.sh\n```\n\n参考转换脚本位于 [`scripts\u002Fhg2git\u002Fhg2git.sh`](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fscripts\u002Fhg2git\u002Fhg2git.sh)。它将 ralphex 内部使用的约 15 个 git 子命令映射到 Mercurial 的等效命令，并采用基于阶段的提交逻辑（草稿阶段修正，公开阶段提交）。需要 bash 4.0+（用于解析差异统计信息的关联数组）。\n\n您还需要自定义提示文件，以替换 Claude 在评审期间作为 bash 命令执行的 git 命令。请参阅[Mercurial 支持文档](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fhg-support.md)，获取完整的设置说明、提示替换示例、`.hgignore` 设置以及已知限制。\n\n\u003Cdetails markdown>\n\u003Csummary>\u003Cb>常见问题解答\u003C\u002Fb>\u003C\u002Fsummary>\n\n**我安装了 ralphex，接下来该怎么办？**\n\n在 `docs\u002Fplans\u002F` 目录下创建一个计划文件（格式请参阅[快速入门](#quick-start)），然后运行 `ralphex docs\u002Fplans\u002Fyour-plan.md`。ralphex 将自动创建分支、执行任务并进行评审。\n\n**为什么有两个评审阶段？**\n\n第一次评审是全面的（默认 5 个代理），第二次是最终检查，只关注关键或重大问题（2 个代理）。请参阅[工作原理](#how-it-works)。\n\n**如何使用我自己的 Claude Code 代理？**\n\n在提示文件中直接按名称引用它们，例如 `qa-expert - \"Review for bugs\"`。请参阅[自定义](#customization)。\n\n**如果未安装 codex 怎么办？**\n\ncodex 是可选的。如果未安装，codex 评审阶段将自动跳过。\n\n**我可以只运行评审而不执行任务吗？**\n\n可以，使用 `--review` 标志来对当前分支上的更改运行完整的评审流程（第 2 阶段 → 第 3 阶段 → 第 4 阶段）。这适用于由任何工具所做的更改——无论是 Claude Code 的内置模式、手动编辑，还是其他代理等。切换到功能分支，提交您的更改，然后运行 `ralphex --review`。详情请参阅[仅评审模式](#review-only-mode)。\n\n**我可以在非 git 目录中运行 ralphex 吗？**\n\n不能直接运行，但 ralphex 通过 `vcs_command` 配置选项和一个转换脚本支持 Mercurial 仓库。请参阅[可配置的 VCS 后端](#configurable-vcs-backend)了解设置方法。\n\n**如果我的仓库没有提交怎么办？**\n\n当仓库为空时，ralphex 会提示您创建初始提交。这是必需的，因为 ralphex 需要分支来进行功能隔离。回答“y”让 ralphex 暂存所有文件并创建初始提交，或者先手动创建一个初始提交，使用 `git add . && git commit -m \"initial commit\"`。\n\n**我应该在 master 分支还是功能分支上运行 ralphex？**\n\n对于完整模式，从 master 分支开始——ralphex 会根据计划文件名自动创建分支。对于 `--review` 模式，首先切换到您的功能分支——评审会使用 `git diff master...HEAD` 与 master 进行比较。\n\n**如何在自定义后恢复默认代理？**\n\n运行 `ralphex --reset` 可以交互式地重置全局配置。选择要重置的组件（配置、提示、代理）。或者，您可以手动删除 `~\u002F.config\u002Fralphex\u002Fagents\u002F` 下的所有 `.txt` 文件。要将更新后的默认值智能合并到自定义文件中（同时保留您的更改），可以使用 `\u002Fralphex-update` Claude Code 技能，或者使用 `ralphex --dump-defaults \u003Cdir>` 提取默认值以便手动比较。\n\n**如何禁用默认代理？**\n\n从 `~\u002F.config\u002Fralphex\u002Fagents\u002F` 中删除某个代理文件并不会禁用它——嵌入的默认代理会作为备用。要禁用特定代理，请编辑提示文件（`review_first.txt`、`review_second.txt`），并移除该代理的 `{{agent:name}}` 引用。\n\n**本地 .ralphex\u002F 配置如何与全局配置交互？**\n\n优先级：CLI 标志 > 本地 `.ralphex\u002Fconfig` > 全局 `~\u002F.config\u002Fralphex\u002Fconfig` > 内置默认值。每个本地设置会覆盖对应的全局设置——无需复制整个文件。对于代理：按文件回退（本地 → 全局 → 内置），与提示相同。只需覆盖一个代理，而无需复制所有其他代理。\n\n**如果 ralphex 失败，未提交的更改会怎样？**\n\nRalphex 在每个任务完成后都会提交。如果执行失败，已完成的任务已经提交到特性分支。失败任务中的未提交更改仍保留在工作目录中，供手动检查。\n\n**如果 ralphex 在执行过程中被中断怎么办？**\n\n已完成的任务已经提交到特性分支。要继续执行，重新运行 `ralphex docs\u002Fplans\u002F\u003Cplan>.md`。Ralphex 通过计划中的 `[x]` 复选框检测已完成的任务，并从第一个未完成的任务开始继续。对于评审会话，只需重新启动即可。评审会从迭代 1 开始重新运行，但之前迭代中的修复仍然保留在代码库中。\n\n**在 ralphex 运行时，我可以调整计划或改变方向吗？**\n\n可以，具体方法取决于情况：\n\n1. **编辑 CLAUDE.md** — 用于行为上的更改（编码风格、库、约束）。每个任务都在一个新的 Claude Code 会话中运行，该会话会在启动时读取 CLAUDE.md，因此更改会在下一个任务或迭代中自动生效。无需停止 ralphex。\n\n2. **停止、编辑计划、重新运行** — 用于结构上的更改（重新排序任务、添加\u002F删除任务、更改需求）。按下 Ctrl+C 停止后，编辑计划文件（取消勾选 `[x]` → `[ ]` 以重新执行任务、添加新任务、修改描述），然后重新运行 `ralphex docs\u002Fplans\u002F\u003Cplan>.md`。Ralphex 会从第一个未完成的任务开始，并根据更新后的计划进行调整。\n\n**进度文件和计划文件有什么区别？**\n\n进度文件（`.ralphex\u002Fprogress\u002Fprogress-*.txt`）是实时执行日志——可以通过 `tail` 命令监控。计划文件记录任务状态（`[ ]` 对比 `[x]`）。要继续执行，只需在计划文件上重新运行 ralphex；它会自动找到未完成的任务。\n\n**在运行 ralphex 之前，我需要先提交更改吗？**\n\n这取决于具体情况。如果只有计划文件未提交，ralphex 会在创建特性分支后自动提交，并继续执行。如果还有其他文件未提交，ralphex 会显示一条有用的错误信息，并提供以下选项：暂时暂存（`git stash`）、先提交（`git commit -am \"wip\"`）或使用仅评审模式（`ralphex --review`）。\n\n**代理和提示之间有什么区别？**\n\n代理定义了要检查的内容（评审指令）。提示则定义了工作流如何运行（执行步骤、信号处理）。\n\n**可以在所有任务完成之前或之后运行自定义步骤吗？**\n\n可以。自定义 `prompts\u002Ftask.txt` 文件，以便在任务生命周期的任何阶段插入额外的步骤。一种常见的模式是在所有任务完成后、但在发出完成信号之前添加一个“门控步骤”。例如，在最后一个任务完成后运行代码异味检查：\n\n```txt\n步骤 3 - 完成（验证通过后）：\n- ...现有步骤...\n- 如果整个计划中不再有 [ ] 复选框，则进入步骤 4\n\n步骤 4 - 风格检查（仅当所有任务完成时）：\n- 使用 \u002Fsmells 技能分析此分支上所有已更改的文件\n- 修复所有报告的风格和代码质量问题\n- 再次运行测试和 linter 以验证修复效果\n- 如果有任何修复，则提交：fix: 解决代码异味问题\n- 输出内容为：\u003C\u003C\u003CRALPHEX:ALL_TASKS_DONE>>>\n```\n\n之所以可行，是因为 ralphex 只会检查 `ALL_TASKS_DONE` 信号——它并不关心前面有多少步骤。同样的方法适用于任何工具或技能：安全扫描、格式化、文档生成等。将其放置在 `~\u002F.config\u002Fralphex\u002Fprompts\u002Ftask.txt` 中以供全局使用，或放在 `.ralphex\u002Fprompts\u002Ftask.txt` 中以供特定项目使用。\n\n**我可以使用 Claude Pro 方案来运行 ralphex 吗？**\n\n可以。Pro 方案更容易遇到速率限制。使用 `--wait` 参数可以让 ralphex 自动暂停并重试，而不是直接退出：\n\n```bash\nralphex --wait 1h docs\u002Fplans\u002Ffeature.md\n```\n\n当检测到速率限制时，ralphex 会等待指定的时间后再重试。虽然执行时间会更长，但可以无人值守地完成。你也可以在配置中设置 `wait_on_limit = 1h`，使其成为默认设置。\n\n**我可以使用 Cursor CLI 而不是 Claude Code 吗？**\n\n可以。[Cursor CLI](https:\u002F\u002Fcursor.com\u002Fcli) 经社区测试，可作为直接替代品。在 `~\u002F.config\u002Fralphex\u002Fconfig` 中进行配置：\n\n```ini\nclaude_command = agent\nclaude_args = --force --output-format stream-json\n```\n\n关键区别在于：使用 `agent` 命令（而非 `claude`），以及 `--force` 标志（而非 `--dangerously-skip-permissions`）。流式格式和信号兼容。*注意：这是经过社区测试的方案，并非官方支持。兼容性取决于 Cursor 是否保持与 Claude Code 的兼容性。*\n\n**我可以使用 codex（或其他模型）来执行任务，而不是 Claude 吗？**\n\n可以。使用附带的包装脚本，将 codex 的输出转换为 Claude 的 stream-json 格式：\n\n```ini\nclaude_command = \u002Fpath\u002Fto\u002Fcodex-as-claude.sh\nclaude_args =\n```\n\n设置 `CODEX_MODEL` 环境变量以选择模型。请参阅【使用替代提供商】和【自定义提供商文档】（https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fblob\u002Fmaster\u002Fdocs\u002Fcustom-providers.md），以了解如何为其他工具编写包装器。\n\n**如何使用多个 Claude 账户？**\n\n设置 `CLAUDE_CONFIG_DIR` 环境变量，指向备用的 Claude 配置目录：\n\n```bash\nCLAUDE_CONFIG_DIR=~\u002F.claude2 ralphex docs\u002Fplans\u002Ffeature.md\n```\n\n这是 Claude Code 本身使用的环境变量。在 Docker 中，包装脚本会挂载指定的目录，并根据路径推导出正确的 macOS Keychain 服务名称。如果没有 Docker，该环境变量会直接传递给子进程 Claude Code。每个 Claude 安装都会根据其配置目录存储在唯一的 Keychain 条目下。无需额外配置——只需将 `CLAUDE_CONFIG_DIR` 指向正确的目录即可。\n\n**可以在所有阶段完成后运行某些操作吗？（如通知、变基提交等）？**\n\n可以。在配置中启用最终步骤，设置 `finalize_enabled = true`。它会在评审阶段成功完成后运行一次（尽力而为——失败会被记录，但不会阻止成功）。默认的 `finalize.txt` 提示会变基到默认分支，并可选择将提交压缩成逻辑组。自定义 `~\u002F.config\u002Fralphex\u002Fprompts\u002Ffinalize.txt` 以执行其他操作，如发送通知、推送到远程仓库或运行自定义脚本。\n\n\u003C\u002Fdetails>\n\n\n\n## Web 仪表板\n\n`--serve` 标志会启动一个基于浏览器的仪表板，用于实时监控计划的执行情况。\n\n```bash\nralphex --serve docs\u002Fplans\u002Ffeature.md\n# web 仪表板：http:\u002F\u002Flocalhost:8080\n```\n\n### 功能特性\n\n- **实时流式传输** - 使用 SSE 连接实现实时输出更新\n- **阶段导航** - 按全部\u002F任务\u002F评审\u002FCodex 阶段进行筛选\n- **可折叠区块** - 输出内容有序组织，支持展开\u002F折叠\n- **文本搜索** - 支持高亮显示搜索结果（键盘：`\u002F` 聚焦，`Escape` 清除）\n- **自动滚动** - 自动跟随输出内容，点击可关闭\n- **中途加入支持** - 新客户端可接收完整历史记录\n\n仪表板采用深色主题，并为不同阶段分配与终端输出相匹配的颜色。使用 `--serve` 时，所有文件和标准输出日志记录均保持不变。\n\n### 多会话模式\n\n通过 `--watch` 标志可同时监控多个 ralphex 会话：\n\n```bash\n# 监控特定目录中的进度文件\nralphex --serve --watch ~\u002Fprojects\u002Ffrontend --watch ~\u002Fprojects\u002Fbackend\n\n# 在配置文件中设置监控目录\n# watch_dirs = \u002Fhome\u002Fuser\u002Fprojects, \u002Fvar\u002Flog\u002Fralphex\n```\n\n多会话功能：\n- **会话侧边栏** - 列出所有已发现的会话，点击即可切换（键盘：`S` 切换）\n- **活动检测** - 通过文件锁机制为正在运行的会话显示脉冲指示\n- **自动发现** - 新会话启动时会自动显示\n\n## Claude Code 集成（可选）\n\nralphex 可以独立在终端中运行。您也可以选择将斜杠命令添加到 Claude Code 中，以获得更一体化的体验。\n\n### 可用命令\n\n| 命令       | 描述                           |\n|------------|--------------------------------|\n| `\u002Fralphex` | 启动并监控 ralphex 执行，支持交互模式和计划选择 |\n| `\u002Fralphex-plan` | 通过引导式上下文收集创建结构化实施计划 |\n| `\u002Fralphex-update` | 将更新后的嵌入默认值智能合并到自定义提示词\u002F代理中 |\n\n### 安装\n\nralphex CLI 是主要界面。Claude Code 技能（`\u002Fralphex`、`\u002Fralphex-plan` 和 `\u002Fralphex-update`）是可选的便捷命令。\n\n**通过插件市场安装（推荐）**\n\n```bash\n# 添加 ralphex 插件市场\n\u002Fplugin marketplace add umputun\u002Fralphex\n\n# 安装插件\n\u002Fplugin install ralphex@umputun-ralphex\n```\n\n优势：当插件市场刷新时（Claude Code 启动时），插件会自动更新。\n\n**手动安装（替代方案）**\n\n斜杠命令的定义托管在以下地址：\n- [`\u002Fralphex`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex.md)\n- [`\u002Fralphex-plan`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex-plan.md)\n- [`\u002Fralphex-update`](https:\u002F\u002Fralphex.com\u002Fassets\u002Fclaude\u002Fralphex-update.md)\n\n要安装，您可以要求 Claude Code “安装 ralphex 斜杠命令”，或者手动将这些文件复制到 `~\u002F.claude\u002Fcommands\u002F` 目录下。\n\n### 使用方法\n\n安装完成后：\n\n```\n# 在 Claude Code 对话中\n\u002Fralphex-plan add user authentication    # 交互式创建计划\n\u002Fralphex docs\u002Fplans\u002Fauth.md              # 启动执行\n“check ralphex”                          # 获取状态更新\n```\n\n`\u002Fralphex` 命令会在后台运行 ralphex，并根据请求提供状态更新。`\u002Fralphex-plan` 命令则会引导您完成结构化的计划创建，包括上下文发现和方案选择。\n\n> **注意：** ralphex 会自动从子进程中移除 `CLAUDECODE` 环境变量，从而允许它在 Claude Code 内部运行。不过，为了获得最佳体验，仍建议在独立终端中运行。如果遇到嵌套会话错误，ralphex 会通过错误模式匹配检测到该问题，并优雅地退出。\n\n## 针对 LLMs 的说明\n\n有关针对 LLM 优化的文档，请参阅 [llms.txt](llms.txt)。\n\n## 许可证\n\nMIT 许可证 - 请参阅 [LICENSE](LICENSE) 文件。","# Ralphex 快速上手指南\n\nRalphex 是一个独立的命令行工具，旨在让 Claude Code 自主执行开发计划。它无需 IDE 插件或云服务，即可在终端中自动完成任务执行、代码审查、提交和分支管理，解决长会话中上下文溢出导致模型质量下降的问题。\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows (部分交互功能如 `Ctrl+\\` 在 Windows 上不可用)。\n*   **Git 仓库**：当前项目必须初始化为 Git 仓库。\n*   **核心依赖**：\n    *   **Claude Code**：必须已安装并配置好 API Key。Ralphex 依赖它来执行具体编码任务。\n    *   **Go 语言环境** (仅源码安装时需要)。\n*   **可选依赖**：\n    *   **Docker**：如果需要隔离运行环境。\n    *   **fzf**：用于计划创建时的交互式选择（非必需，有降级方案）。\n\n## 安装步骤\n\n你可以选择以下任一方式进行安装：\n\n### 方式一：使用 Go 安装（推荐）\n如果你已安装 Go 环境：\n```bash\ngo install github.com\u002Fumputun\u002Fralphex\u002Fcmd\u002Fralphex@latest\n```\n\n### 方式二：使用 Homebrew (macOS)\n```bash\nbrew install umputun\u002Fapps\u002Fralphex\n```\n\n### 方式三：下载二进制文件\n访问 [Releases 页面](https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Freleases) 下载对应系统的二进制文件，解压后将其放入 `$PATH` 目录中。\n\n### 方式四：使用 Docker\n下载官方包装脚本并赋予执行权限：\n```bash\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Fumputun\u002Fralphex\u002Fmaster\u002Fscripts\u002Fralphex-dk.sh -o \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fralphex\n```\n*注：国内用户若下载脚本缓慢，可手动下载脚本内容后保存为 `\u002Fusr\u002Flocal\u002Fbin\u002Fralphex`。*\n\n## 基本使用\n\n### 1. 创建计划文件\n在项目根目录下创建 `docs\u002Fplans\u002F` 文件夹，并新建一个 Markdown 格式的计划文件（例如 `my-feature.md`）。\n\n文件内容示例：\n```markdown\n# Plan: My Feature\n\n## Validation Commands\n- `go test .\u002F...`\n\n### Task 1: Implement feature\n- [ ] Add the new functionality\n- [ ] Add tests\n```\n\n### 2. 执行计划\n在终端运行以下命令启动 Ralphex：\n\n```bash\nralphex docs\u002Fplans\u002Fmy-feature.md\n```\n\n**执行流程：**\n1.  **自动建支**：根据文件名创建新的 Git 分支。\n2.  **任务执行**：调用 Claude Code 逐个完成未勾选的任务，并在每步后运行验证命令（如测试）。\n3.  **自动提交**：每完成一个任务自动提交代码。\n4.  **多阶段审查**：启动多个 Agent 并行审查代码质量、实现逻辑和测试覆盖率，并自动修复问题。\n5.  **归档**：全部完成后，将计划文件移至 `completed\u002F` 文件夹。\n\n### 3. 交互式创建计划（可选）\n如果你还没有计划文件，可以使用 `--plan` 标志让 Ralphex 辅助生成：\n\n```bash\nralphex --plan \"add health check endpoint\"\n```\nRalphex 会分析代码库，通过终端提问澄清需求，生成完整的计划文件，并询问是否立即执行。\n\n### 4. 实时监控\n执行过程中，终端会实时流式输出带时间戳和颜色的日志。如需在浏览器中查看实时仪表盘，可添加 `--serve` 标志：\n```bash\nralphex docs\u002Fplans\u002Fmy-feature.md --serve\n```","某后端团队需要在周末紧急为微服务架构添加一套复杂的支付回调处理逻辑，涉及数据库变更、API 接口开发及多场景单元测试。\n\n### 没有 ralphex 时\n- 开发者必须全程“保姆式”盯着 Claude Code，每执行一步都要手动确认，耗时数小时无法离开座位。\n- 随着会话上下文不断堆积，模型逐渐“遗忘”早期的架构约定，导致后期生成的代码风格不一致甚至出现逻辑幻觉。\n- 缺乏自动化的多轮代码审查机制，人工复查容易疲劳漏看，往往在合并后才发现问题，返工成本高。\n- 任务中断或报错后需人工介入重试，难以利用夜间或碎片时间自主推进复杂功能的落地。\n\n### 使用 ralphex 后\n- 开发者只需编写包含验证命令的计划文件并启动 ralphex，即可放心离开，工具会自动按序执行任务并提交代码。\n- ralphex 确保每个子任务都在全新的 Claude Code 会话中运行，保持上下文极简，让模型始终维持高精度的代码输出。\n- 内置的\"5 代理编码 +2 代理审查”流水线自动对每步产出进行多轮互检，显著降低低级错误率，确保代码质量。\n- 支持断点续传与自动重试，配合 Web 仪表盘实时监控进度，即使跨夜运行也能在次日清晨交付完整可用的功能分支。\n\nralphex 将原本需要人工全程陪护的交互式编码，转化为可信赖的无人值守自动化交付流程，极大释放了开发者的时间价值。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fumputun_ralphex_74eb72f7.png","umputun","Umputun","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fumputun_f431469f.png",null,"USA","umputun@gmail.com","https:\u002F\u002Fumputun.dev","https:\u002F\u002Fgithub.com\u002Fumputun",[81,85,89,93,97,101,105,109],{"name":82,"color":83,"percentage":84},"Go","#00ADD8",75,{"name":86,"color":87,"percentage":88},"Python","#3572A5",9.3,{"name":90,"color":91,"percentage":92},"Shell","#89e051",5.8,{"name":94,"color":95,"percentage":96},"JavaScript","#f1e05a",4.3,{"name":98,"color":99,"percentage":100},"HTML","#e34c26",3.3,{"name":102,"color":103,"percentage":104},"CSS","#663399",2.1,{"name":106,"color":107,"percentage":108},"Makefile","#427819",0.2,{"name":110,"color":111,"percentage":112},"Dockerfile","#384d54",0.1,940,76,"2026-04-08T16:08:00","MIT","Linux, macOS","未说明",{"notes":120,"python":118,"dependencies":121},"该工具是基于 Go 语言编写的 CLI 工具，非 Python AI 模型，因此无 GPU、Python 版本或特定显存需求。核心依赖是外部的 'Claude Code' 服务（需单独安装并配置 API Key）。支持通过 Docker 运行以实现隔离。Windows 系统不支持部分交互功能（如 Ctrl+\\ 暂停\u002F中断信号）。",[122,123,124,125],"Go (编译语言)","Claude Code (外部依赖)","Git","Docker (可选)",[13],[128,129,130,131,132,133],"automation","claude-code","codex","ralph-loop","ralph-wiggum","review","2026-03-27T02:49:30.150509","2026-04-09T09:31:51.112228",[137,142,147,152,156,160,164],{"id":138,"question_zh":139,"answer_zh":140,"source_url":141},25791,"如何在 ralphex 中使用 Gemini 或其他自定义 AI 工具进行代码审查，而不是默认的 Codex？","可以通过配置 `external_review_tool` 选项来实现。将其设置为 `custom`，并指定 `custom_review_script` 指向一个包装脚本。该脚本接收提示文件路径作为参数，将审查结果输出到 stdout，ralphex 会将其传递给 Claude 进行评估和修复。\n\n配置示例：\n```ini\nexternal_review_tool = custom\ncustom_review_script = \u002Fpath\u002Fto\u002Fyour\u002Fwrapper.sh\n```\n\n启动时使用 `--external-only` (或 `-e`) 标志。脚本内部可以利用提示文件中的 `{{DIFF_INSTRUCTION}}` 变量来获取差异内容（首次迭代使用 `git diff main...HEAD`，后续使用 `git diff`）。\n注意：不建议在 Agent 提示中直接调用外部 CLI，因为这会增加延迟、成本并导致输出处理复杂化；直接使用自定义脚本包装器是更优方案。","https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fissues\u002F59",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},25792,"为什么 Web 仪表板在多项目监控模式下折叠侧边栏后无法恢复，且找不到键盘快捷键提示？","这是一个已知的界面问题。当侧边栏折叠时，切换按钮因为位于具有 `opacity: 0` 的容器内而不可见，且 `position: fixed` 无法使其逃逸出父容器，导致面板折叠后无法恢复。\n此外，键盘快捷键（如 `s` 或 `p`）缺乏明显的提示，仅在搜索框附近有小字说明。\n解决方案包括：\n1. 修改 CSS 使切换按钮在侧边栏折叠时依然可见（例如固定在屏幕边缘）。\n2. 在头部添加一个可见的 `?` 按钮以展示快捷键帮助。\n3. 在多项目时间排序视图中，确保显示会话所属的项目路径，以免混淆。","https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fissues\u002F14",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},25793,"审查提示中缺少 `git add` 步骤导致提交失败或遗漏更改，如何解决？","默认的审查提示（如 `review_first.txt` 和 `review_second.txt`）仅指示执行 `git commit`，而未先执行 `git add`。当 AI 通过编辑工具修改文件时，这些更改处于未暂存状态，导致提交捕获不到任何内容或仅包含之前暂存的文件。\n\n解决方法是修改提示文件，将提交步骤从：\n`# 3. Commit fixes: git commit -m \"fix: address code review findings\"`\n更改为：\n`# 3. Stage and commit fixes: git add -A && git commit -m \"fix: address code review findings\"`\n\n这样可以确保所有修改的文件在提交前被正确暂存，避免自动化工作流因未暂存的更改而中断。","https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fissues\u002F185",{"id":153,"question_zh":154,"answer_zh":155,"source_url":146},25794,"如何在 Web 仪表板中区分不同项目的会话，特别是在按时间排序时？","在使用 `--serve --watch` 监控多个项目时，如果会话按时间排序而非按项目分组，界面上可能不会显示会话所属的项目路径，导致仅看到计划名称而产生混淆。\n\n建议在仪表板的顶部栏或会话列表项中明确显示项目路径（Project Path）。目前顶部栏通常只显示计划名称（Plan）和分支（Branch），缺少源目录信息。增强显示项目完整路径可以帮助用户在多项目环境下快速识别会话来源。",{"id":157,"question_zh":158,"answer_zh":159,"source_url":151},25795,"为什么在运行测试时会收到真实的 Telegram 通知消息？","正常情况下，所有通知测试都应该是完全模拟（mocked）的，不会发送真实的 API 请求。如果在运行 `go test .\u002F...` 时收到了真实的 Telegram 消息，可能是因为某些集成测试调用 `run()` 时加载了真实配置文件（`config.Load(\"\")`），而没有覆盖 `ConfigDir`。\n\n当 `~\u002F.config\u002Fralphex\u002Fconfig` 中包含真实的 Telegram 凭证时，`notify.New()` 会创建真实通道。如果测试立即取消上下文导致 runner 失败，`executePlan()` 可能会通过 `context.Background()` 发送失败通知。\n\n修复方法是确保受影响的测试（如 `TestAutoModeSkippedForReviewModes` 等）在调用 `run()` 时传入 `ConfigDir: t.TempDir()`，以隔离配置文件。",{"id":161,"question_zh":162,"answer_zh":163,"source_url":146},25796,"Web 仪表板是否支持导出会话以便离线查看？","是的，Web 仪表板支持将会话导出为独立的 HTML 文件以供离线查看。用户可以通过仪表板界面的导出功能保存当前会话。\n导出的 HTML 文件包含了完整的会话记录，即使在没有网络连接或 ralphex 服务停止后也能随时回顾。使用方法是在命令行启动服务：\n```bash\nralphex --serve docs\u002Fplans\u002Fmy-plan.md\n```\n然后在浏览器中访问仪表板并使用导出功能。",{"id":165,"question_zh":166,"answer_zh":167,"source_url":168},25797,"如何为 ralphex 添加对 Token 使用量的追踪和导出？","为了分析和控制成本，可以实施端到端的 Token 使用量追踪。这包括扩展执行器结果以包含元数据（如 `input_tokens`, `output_tokens`, `total_tokens`, `cache_read_input_tokens` 等）。\n系统应解析来自 Claude 的 `stream-json` 事件以及 Codex\u002F自定义输出的 JSON\u002FNDJSON 中的用量数据。这些数据可以记录在文本日志中，导出为 JSONL 格式以便机器读取，并在 Web 仪表板上提供汇总视图，帮助用户按阶段和工具分析使用情况。","https:\u002F\u002Fgithub.com\u002Fumputun\u002Fralphex\u002Fissues\u002F253",[170,175,180,185,190,195,200,205,210,215,220,225,230,235,240,245,250,255,260,265],{"id":171,"version":172,"summary_zh":173,"released_at":174},163119,"v0.26.2","**改进**\n- 更新 README.md，添加快速入门中创建计划的链接 #261 @ksenks\n- 在 Docker 镜像中添加 jq afdfb47\n","2026-03-31T17:18:31",{"id":176,"version":177,"summary_zh":178,"released_at":179},163120,"v0.26.1","**改进**\n- 统一 .gitignore 的处理方式，并修复写入错误报告 #252 @vkazmirchuk\n- 统一启动时的头部和完成时的尾部显示 9af32cd\n- 恢复从 coveralls 切换回 codecov，再切换回 coveralls 63d8a7f\n\n**修复**\n- 使用 .ralphex\u002F.gitignore，而非修改根目录下的 .gitignore #260 @rsolmano\n","2026-03-30T18:59:43",{"id":181,"version":182,"summary_zh":183,"released_at":184},163121,"v0.26.0","**新功能**\n- 为 Claude 会话添加空闲超时 #250 @umputun\n- 通过 SIGQUIT 实现任务暂停与恢复 #249 @umputun\n- 添加 InitLocal API 和 --init CLI 标志，用于本地配置设置 #245 @vkazmirchuk\n\n**改进**\n- 将 github.com\u002Ffatih\u002Fcolor 从 1.18.0 升级到 1.19.0 #243 @app\u002Fdependabot\n\n**修复**\n- 防止在 Claude 分析文本中出现误报的模式匹配 #251 @umputun","2026-03-25T06:49:57",{"id":186,"version":187,"summary_zh":188,"released_at":189},163122,"v0.25.0","**新功能**\n- 添加 commit_trailer 配置选项，用于在提交中添加署名尾注 #242 @umputun\n- 为代理加载实现按文件的回退机制 #239 @umputun\n\n**Bug 修复**\n- 在 ralphex-dk.sh 中使用 Optional[] 语法，以兼容 Python 3.9 #241 @alkk\n- 修复 Codex 执行时 Windows 命令行长度限制问题 #233 @stanurkov\n","2026-03-23T08:14:41",{"id":191,"version":192,"summary_zh":193,"released_at":194},163123,"v0.24.4","**错误修复**\n- 修复浅色终端的默认颜色以提高可读性 #237 @umputun\n","2026-03-21T23:19:28",{"id":196,"version":197,"summary_zh":198,"released_at":199},163124,"v0.24.3","**改进**\n- 添加 RALPHEX_DOCKER_NETWORK 环境变量和 --network CLI 标志 #230 @umputun\n\n**Bug 修复**\n- 阻止计划任务部分中的不可自动化的复选框 #228 @umputun\n","2026-03-18T17:35:40",{"id":201,"version":202,"summary_zh":203,"released_at":204},163125,"v0.24.2","**已修复**\n\n- 在正常退出时杀死孤立的子进程 #227 @umputun\n","2026-03-18T06:40:21",{"id":206,"version":207,"summary_zh":208,"released_at":209},163126,"v0.24.1","**错误修复**\n- 修复 wrapText 在续行时使用缩小后的宽度，而非整个终端宽度的问题\n","2026-03-18T01:56:00",{"id":211,"version":212,"summary_zh":213,"released_at":214},163127,"v0.24.0","**新功能**\n- 添加 session_timeout 配置选项，用于防止会话挂起的安全机制 #225 @umputun\n\n**Bug 修复**\n- 防止复选框位于任务区域之外时出现无限循环 #222 @romrigger\n- 修复进度输出文本换行问题及代码异味 #226 @umputun\n","2026-03-18T01:28:13",{"id":216,"version":217,"summary_zh":218,"released_at":219},163128,"v0.23.0","**新功能**\n\n- 支持在容器中挂载主机的 Docker Socket，以适应依赖 Docker 的工作流 #223 @umputun\n\n**改进**\n\n- 代码异味清理：结构和规范优化 #217 @umputun\n- 将 golang.org\u002Fx\u002Fterm 版本从 0.40.0 升级到 0.41.0 #219 @app\u002Fdependabot\n- 将 github.com\u002Fcharmbracelet\u002Fglamour 版本从 0.10.0 升级到 1.0.0 #218 @app\u002Fdependabot\n\n**修复**\n\n- 通过 stdin 传递 Claude 提示，以规避 Windows cmd.exe 的长度限制 #220 @stanurkov\n","2026-03-17T02:24:05",{"id":221,"version":222,"summary_zh":223,"released_at":224},163129,"v0.22.0","**New Features**\n- Dry run flag for docker wrapper script #213 @bronislav\n- Introduce gemini-as-claude wrapper #212 @korjavin\n- Externalize codex review prompt as configurable template #216 @umputun\n- Add codex_review.txt template file and config wiring\n- Add {{PREVIOUS_REVIEW_CONTEXT}} variable and refactor buildCodexPrompt to use template\n\n**Improvements**\n- Reorganize scripts\u002F into functional subdirectories #210 @umputun\n- Show progress log path at completion #204 @DmitriyAlergant\n- Deduplicate local config detection when it matches global dir\n- Document worktree mode limitations and review workaround\n\n**Bug Fixes**\n- Use --output instead of --format for aws export-credentials #203 @bronislav\n- Pass progress file to external review prompts for iteration history\n","2026-03-15T22:23:58",{"id":226,"version":227,"summary_zh":228,"released_at":229},163130,"v0.21.3","**Bug Fixes**\n- Use sentinel error to prevent infinite retry on I\u002FO failures in plan draft review\n- Output invalid selection warnings to stdout instead of log for consistent interactive flow\n- Fix test name mismatch\n\nRelated to #201","2026-03-12T04:39:50",{"id":231,"version":232,"summary_zh":233,"released_at":234},163131,"v0.21.2","**Improved**\n- Harden workflows, upgrade actions, fix caching #184 @paskal\n- Revert golangci-lint pinning to latest\n\n**Fixed**\n- Retry invalid selections in plan draft review #202 @umputun","2026-03-12T04:27:54",{"id":236,"version":237,"summary_zh":238,"released_at":239},163132,"v0.21.1","**New Features**\n- add opencode-as-claude wrapper and opencode-review scripts #199 @mschedrin\n\n**Improvements**\n- add python tests for docker wrapper script\n\n**Bug Fixes**\n- prevent false positive pattern matching on clean codex\u002Fcustom exit #200 @umputun\n- prevent custom review output duplication in progress log #198 @umputun\n- ensure test creates temp claude config dir for Linux CI","2026-03-11T23:25:15",{"id":241,"version":242,"summary_zh":243,"released_at":244},163133,"v0.21.0","**New Features**\n- Add AWS Bedrock support for Docker wrapper (#169) @bronislav\n\n**Improved**\n- Refactor docker wrapper to use argparse for CLI parsing (#183) @bronislav\n- Update default codex model to gpt-5.4\n- Bump golang.org\u002Fx\u002Fsys from 0.41.0 to 0.42.0 (#190) @app\u002Fdependabot\n- Bump docker\u002Fbuild-push-action from 6 to 7 (#189) @app\u002Fdependabot\n- Bump docker\u002Fsetup-buildx-action from 3 to 4 (#188) @app\u002Fdependabot\n- Bump docker\u002Flogin-action from 3 to 4 (#187) @app\u002Fdependabot\n- Add FAQ entry for custom gate steps in task prompt\n- Fix broken relative links in README for MkDocs site\n\n**Fixed**\n- Commit pending changes after external review loop early exit (#186) @umputun\n- Isolate integration tests from global config\n- Exclude gosec G118 from lint config\n- Use compact date format in goreleaser version string","2026-03-10T23:39:40",{"id":246,"version":247,"summary_zh":248,"released_at":249},163134,"v0.20.0","**New Features**\n\n- Add RALPHEX_EXTRA_ENV support for passing environment variables to Docker (#179) @bronislav\n- Implement manual break command (SIGQUIT\u002FCtrl+\\) for external review loop\n- Add review patience: terminate external review after N consecutive unchanged rounds (stalemate detection)\n\n**Improved**\n\n- Fix slow tests and use t.Context() instead of context.Background()\n- Update playwright-go to v0.5700.1\n- Update go dependencies and github actions\n- Use env: mapping for head_branch in docker workflow (#174) @paskal\n\n**Fixed**\n\n- Isolate TestTasksOnlyModeBranchCreation from global config (#177) @bronislav\n- Show dirty file list in uncommitted changes error (#175) @umputun\n","2026-03-04T02:43:11",{"id":251,"version":252,"summary_zh":253,"released_at":254},163135,"v0.19.0","**New Features**\n\n- Add wait-on-limit mode: automatic retry on rate limits with configurable duration (#168) @umputun\n\n**Improved**\n\n- Add FAQ entry about using ralphex with Claude Pro plan\n- Document wait-on-limit feature\n\n**Fixed**\n\n- Fix worktree mode rejecting non-main\u002Fmaster default branches (#165) @umputun","2026-03-01T04:32:57",{"id":256,"version":257,"summary_zh":258,"released_at":259},163136,"v0.18.0","**New Features**\n- Add configurable VCS command with Mercurial support (#162) @paskal\n- Add configurable iteration limit for external review phase (#160) @umputun\n- Add max_iterations as config file option\n\n**Fixed**\n- Fix broken \"Available images\" anchor link in README\n","2026-02-26T09:19:03",{"id":261,"version":262,"summary_zh":263,"released_at":264},163137,"v0.17.0","**New Features**\n\n- Add git worktree isolation for parallel plan execution (#158) @umputun\n\n**Improved**\n\n- Bump goreleaser\u002Fgoreleaser-action from 6 to 7 (#148) @app\u002Fdependabot\n- Add codecov config to ignore mock directories\n- Replace coveralls with codecov for coverage reporting\n- Add worktree isolation documentation\n- Add coverage for worktree and ensureGitIgnored paths\n\n**Fixed**\n\n- Make web dashboard reachable from host in Docker (#152) @nnemirovsky\n- Handle nested claude session error instead of silent loop\n- Auto-detect host timezone in Docker wrapper","2026-02-25T00:11:09",{"id":266,"version":267,"summary_zh":268,"released_at":269},163138,"v0.16.0","**New Features**\n- add extra volume mount support to Docker wrapper #142 @alkk\n\n**Bug Fixes**\n- fix dashboard task numbering on mid-run plan edits #147 @umputun\n- adapt review prompts for codex multi-agent flow #143 @krajcik\n","2026-02-22T04:22:32"]