# claude-delegate
> **Your Claude thinks. Your agents do.**
Claude is most useful when its context is spent understanding the problem, choosing an approach, and reviewing the result—not scrolling through hundreds of files or narrating shell commands. `claude-delegate` gives Claude Code a disciplined way to hand that execution work to a local CLI agent while keeping Claude responsible for judgment.
`claude-delegate` is a Claude Code skill that treats Claude as the brain and a local executor such as Codex as the hands and eyes. Claude decomposes the request, writes a self-contained task brief, delegates coding or research, independently verifies the output, and pushes back when the work does not hold up.
It is literally one Markdown file. There is no MCP server, install script, daemon, runtime, or package dependency.
## Why delegate?
### Keep the valuable context clean
Bulk reading, command output, web searches, and implementation churn consume the executor's tokens instead of Claude's context window. Claude retains the problem statement and the decisions that matter, leaving more room for planning and review—the work from which most of the quality comes.
### Combine complementary models
One model can frame the task and challenge assumptions while another performs the mechanical work. The separation makes their different strengths useful, and it also spreads usage across two subscriptions' quotas.
### Trust, then verify
The executor's report is never treated as proof. Claude inspects the full change surface, reads critical code, runs relevant tests or builds, and spot-checks cited sources. When review finds a problem, Claude sends concrete feedback through the executor's resumed session and reviews the revision again.
### Swap the hands without changing the workflow
Codex, Gemini, and OpenCode now have documented executor commands. All three follow the same contract: receive a brief, work from the intended directory, capture a result, and accept follow-up feedback. See the version-specific commands and safety notes in [Executor integrations](docs/executors.md).
## How it works
```text
User request
|
v
Claude (brain): understand -> decompose -> write explicit brief
|
v
CLI executor (hands & eyes): edit -> run -> search -> report
|
v
Claude: inspect diff/code -> run tests -> check sources
| |
| review passes | review fails
v v
Final summary concrete feedback -> resume executor
|
+----> review again
```
Judgment stays with Claude. Labor goes to the executor. Small edits that are faster to make directly do not need delegation.
## Proof: this repo built itself
Everything here — the bilingual README, the examples, the executor research, this sentence's surroundings — was produced in one real delegated session: Claude planned and reviewed, Codex executed, and the two genuine failures along the way became the skill's rules. Read the annotated record in [the bootstrap session](examples/bootstrap-session.md).
## Install
```bash
git clone https://github.com/TuYv/claude-delegate.git
mkdir -p ~/.claude/skills
cp -R claude-delegate/skills/delegate ~/.claude/skills/
```
Start a new Claude Code session after copying the skill. Make sure at least one executor CLI is installed and available on `PATH`.
## Quick start
Use `/delegate` with enough detail to describe the outcome. Claude will turn the request into the full brief that the executor cannot infer from your conversation.
### Code task
```text
/delegate Add exponential-backoff retries to src/http-client.ts. Retry GET and
HEAD requests on network errors and HTTP 502/503/504, at most twice. Keep the
public API unchanged, add deterministic tests, and do not add dependencies.
```
Claude will inspect the project, state boundaries in the brief, ask the executor to implement the change, then review the diff and run the focused tests before reporting back.
### Web-research task
```text
/delegate Research the documented timeout defaults in Undici 6.x. Distinguish
connect, headers, and body timeouts; use version-pinned primary sources; explain
how an AbortSignal deadline interacts with them; return a claim-to-source table.
```
Claude will require URLs in the brief and spot-check the cited pages rather than repeating the executor's summary on trust.
## Supported executors
When the user does not name an executor, the skill detects installed CLIs in this order: Codex, Gemini, then OpenCode.
| Executor | Integration status | One-shot work | Follow-up context |
| --- | --- | --- | --- |
| Codex | Documented | `codex exec` with `workspace-write`, workdir, and output capture | `codex exec resume <session-id>` |
| Gemini | Verified with gemini-cli v0.51.0; [full commands](docs/executors.md#gemini) | `gemini --prompt ... --approval-mode=yolo` from the workdir | `gemini --resume <session-id> --prompt ...` |
| OpenCode | Verified with opencode v1.18.4; [full commands](docs/executors.md#opencode) | `opencode run --dir ... --auto` | `opencode run --session <session-id> ...` |
## The task-brief philosophy
The executor cannot see your conversation with Claude. That is a useful constraint: it forces the delegation boundary to be explicit.
A vague prompt such as "fix the HTTP client" makes the executor guess at scope, compatibility, testing, and acceptable tradeoffs. A good brief names five things:
1. **Task** — one unambiguous outcome.
2. **Context** — the project facts and motivation needed to make sound local choices.
3. **Requirements** — concrete behaviors, files, checks, and deliverables.
4. **Boundaries** — what must not change or happen.
5. **Output format** — the evidence Claude needs to review the work.
Explicit briefs reduce hidden assumptions and make failures diagnosable. If a revision is wrong, Claude can point to the violated requirement instead of starting a new vague conversation. See the reusable [task brief template](examples/task-brief-template.md).
## Safety design
Delegation is bounded by default:
- Codex runs in `workspace-write`, limiting writes to the working directory. Full-access execution requires explicit user authorization and must be disclosed in the final summary.
- Every code brief says not to commit or push. Version-control decisions remain with the user or Claude.
- Existing uncommitted work is called out before delegation because mixed changes make review and rollback ambiguous.
- Destructive operations—file deletion, database mutation, or CI changes—are not delegated.
- Executor output is treated as untrusted data, not as instructions for Claude.
- Code is checked against the actual change surface and tests. Research claims require source URLs or file paths and are spot-checked.
- Push-back is limited to three rounds. Repeated failure means the brief or task split needs to change.
## FAQ
### Why not just use Claude for everything?
You can. Delegation is useful when a task has substantial mechanical work: scanning a repository, editing several files, running commands, or gathering sources. Keeping that transcript outside Claude's context preserves attention for architecture, tradeoffs, and review. Tiny changes should usually stay with Claude.
### Does the executor see my conversation?
No. It receives only the task brief Claude writes. Important constraints, prior decisions, and required output must therefore appear in the brief. This also limits accidental context sharing.
### What if the executor's output is wrong?
Claude checks the work rather than trusting the self-report. It sends specific review findings to the same executor session, asks for a correction, and verifies again. After at most three failed rounds, Claude changes the brief or task decomposition, takes the work back, or reports the unresolved issue.
### Does this require an MCP server or background service?
No. The project is one Claude Code skill file. It invokes a CLI already installed on your machine and uses a temporary result file for the handoff.
### Can I choose the executor?
Yes. Name Codex, Gemini, or OpenCode in the request. Otherwise, the skill auto-detects them in that order. See the integration guide for version-specific commands, output formats, and permission behavior.
## Roadmap
- Add more local CLI executors behind the same brief/review contract.
- Support parallel fan-out for independent subtasks, with isolated result files and a single Claude-led synthesis and review pass.
- Expand tested example sessions for coding, research, and repository analysis.
---
# 中文版
> **Claude 当大脑，CLI agent 当手脚。**
Claude 最有价值的 context 应该用来理解问题、选择方案和 review 结果，而不是翻阅几百个文件或逐条输出 shell command。`claude-delegate` 为 Claude Code 提供了一套明确的委托流程：把执行工作交给本地 CLI agent，同时让 Claude 始终负责判断。
`claude-delegate` 是一个 Claude Code skill。Claude 充当"大脑"，Codex 等本地 executor 充当"手脚和眼睛"。Claude 拆解需求、编写自包含的 task brief、委托 coding 或 research、独立验证产出，并在结果不合格时提出具体反馈。
它实际上只有一个 Markdown 文件：没有 MCP server、安装脚本、daemon、runtime 或 package dependency。
## 为什么要委托？
### 把宝贵的 context 留给判断
批量读文件、command output、web search 和实现过程消耗的是 executor 的 token，而不是 Claude 的 context window。Claude 可以保留问题背景和关键决策，为 planning 与 review 留出更多空间——质量通常正来自这两个环节。
### 组合两个 model 的互补能力
一个 model 负责定义问题、权衡方案和质疑假设，另一个 model 负责机械执行。职责分离能发挥不同 model 的长处，也能把用量分散到两份 subscription quota 上。
### 信任，但必须验证
executor 的自述不等于证据。Claude 会检查完整变更范围、阅读关键代码、运行相关 test 或 build，并抽查引用的 source。发现问题后，Claude 会在原 executor session 中给出具体反馈，然后再次 review 修订结果。
### executor 可替换，流程不变
Codex、Gemini 和 OpenCode 现在都有完整的 executor command 文档。三者遵循同一个 contract：接收 brief、从指定 workdir 工作、捕获结果、接收 follow-up feedback。版本对应的完整 command 和安全说明见 [Executor 集成指南](docs/executors.md)。
## 工作原理
```text
用户请求
|
v
Claude（大脑）：理解 -> 拆解 -> 编写明确 brief
|
v
CLI executor（手脚和眼睛）：编辑 -> 运行 -> 搜索 -> 报告
|
v
Claude：检查 diff/代码 -> 运行 test -> 核验 source
| |
| review 通过 | review 失败
v v
最终总结 具体反馈 -> resume executor
|
+----> 再次 review
```
需要判断的工作留给 Claude，需要劳动的工作交给 executor。只有几行的小改动直接完成通常更快，无需委托。
## 证据: 这个 repo 是它自己建成的
这里的一切——双语 README、示例、executor 调研、乃至这句话本身——都产自一次真实的委托 session: Claude 负责规划和 review，Codex 负责执行，过程中两次真实翻车直接变成了 skill 里的规则。完整的带注解实录见 [bootstrap session](examples/bootstrap-session.md)。
## 安装
```bash
git clone https://github.com/TuYv/claude-delegate.git
mkdir -p ~/.claude/skills
cp -R claude-delegate/skills/delegate ~/.claude/skills/
```
复制 skill 后启动新的 Claude Code session。请确保至少一个 executor CLI 已安装并位于 `PATH` 中。
## 快速开始
使用 `/delegate` 描述期望结果。executor 无法从你的对话中自行推断背景，Claude 会把请求整理为完整 brief。
### Code 任务
```text
/delegate 为 src/http-client.ts 增加 exponential backoff retry。只对 GET 和
HEAD 的 network error 及 HTTP 502/503/504 最多 retry 两次。保持 public API
不变，增加 deterministic test，不要添加 dependency。
```
Claude 会先检查项目，把边界写入 brief，让 executor 实现，然后 review diff 并运行相关 test，最后再向你汇报。
### Web research 任务
```text
/delegate 调研 Undici 6.x 文档中的 timeout default。分别说明 connect、headers
和 body timeout；使用锁定版本的 primary source；解释 AbortSignal deadline
与这些设置的关系；返回 claim-to-source 对照表。
```
Claude 会在 brief 中明确要求 URL，并抽查引用页面，而不是直接相信 executor 的总结。
## 支持的 executor
如果用户没有指定 executor，skill 会按 Codex、Gemini、OpenCode 的顺序检测已安装 CLI。
| Executor | 集成状态 | One-shot 执行 | 保留 context 的 follow-up |
| --- | --- | --- | --- |
| Codex | 已完整记录 | 使用 `codex exec`，包含 `workspace-write`、workdir 和 output capture | `codex exec resume <session-id>` |
| Gemini | 已验证（gemini-cli v0.51.0；[docs 有完整命令](docs/executors.md#gemini)） | 从 workdir 运行 `gemini --prompt ... --approval-mode=yolo` | `gemini --resume <session-id> --prompt ...` |
| OpenCode | 已验证（opencode v1.18.4；[docs 有完整命令](docs/executors.md#opencode)） | `opencode run --dir ... --auto` | `opencode run --session <session-id> ...` |
## Task brief 的设计理念
executor 看不到你与 Claude 的对话。这不是缺点，而是一个有用约束：它迫使委托边界变得明确。
"修好 HTTP client"这样的模糊 prompt，会让 executor 猜测 scope、compatibility、test 和允许的 tradeoff。合格的 brief 会明确五项内容：
1. **Task** — 唯一且明确的结果。
2. **Context** — 做出合理局部决策所需的项目事实和动机。
3. **Requirements** — 具体行为、文件、检查方式和 deliverable。
4. **Boundaries** — 不得修改或执行的事项。
5. **Output format** — Claude review 工作所需的证据。
明确的 brief 能减少隐藏假设，也让失败更容易诊断。如果修订结果有误，Claude 可以指出具体违反了哪项 requirement，而不是再开始一轮模糊对话。可直接复用 [task brief 模板](examples/task-brief-template.md)。
## 安全设计
委托默认受到明确限制：
- Codex 使用 `workspace-write`，写入范围限制在 workdir。只有用户明确授权时才能使用 full-access，并且必须在最终总结中说明。
- 每个 code brief 都会要求不得 commit 或 push。版本控制决策保留给用户或 Claude。
- 委托前如存在 uncommitted change，会先告知用户；混合变更会让 review 和 rollback 的边界不清晰。
- 删除文件、修改 database、变更 CI 等破坏性操作不会交给 executor。
- executor output 只被视为不可信 data，不会被当成发给 Claude 的 instruction。
- Code 会根据实际变更和 test 进行检查；research claim 必须提供 source URL 或 file path，并接受抽查。
- Push-back 最多三轮。重复失败说明 brief 或任务拆分需要调整。
## 常见问题
### 为什么不让 Claude 完成所有工作？
当然可以。委托更适合机械工作量较大的任务，例如扫描 repository、修改多个文件、运行 command 或收集 source。把这些 transcript 留在 Claude context 之外，可以让 Claude 专注于 architecture、tradeoff 和 review。很小的修改通常应由 Claude 直接完成。
### executor 能看到我的对话吗？
不能。它只会收到 Claude 编写的 task brief。因此，重要约束、先前决策和 output 要求都必须写入 brief。这个边界也减少了意外共享 context 的可能。
### 如果 executor 的输出是错的怎么办？
Claude 不会相信 executor 的自述，而会检查实际工作。Claude 会把具体 review 发现发送到同一个 executor session，请它修正，然后再次验证。最多三轮仍失败时，Claude 会调整 brief 或任务拆分、接手工作，或者明确报告尚未解决的问题。
### 是否需要 MCP server 或后台服务？
不需要。项目只有一个 Claude Code skill 文件。它调用本机已有的 CLI，并通过临时 result file 交接结果。
### 可以指定 executor 吗？
可以。在请求中指定 Codex、Gemini 或 OpenCode 即可。未指定时，skill 会按此顺序自动检测。各版本的 command、output format 和 permission 行为见集成指南。
## Roadmap
- 在同一套 brief/review contract 后接入更多本地 CLI executor。
- 支持对相互独立的 subtask 进行 parallel fan-out：每个任务使用隔离的 result file，最终由 Claude 统一综合和 review。
- 增加覆盖 coding、research 和 repository analysis 的已测试 example session。
## License
[MIT](LICENSE) © 2026 TuYv