# Claude Code Subagent MCP

[English](README_EN.md) | 简体中文

## 项目简介

Claude Code Subagent MCP 是一个用户级 stdio MCP server，让 Codex Desktop 或 Codex CLI
可以调用 Claude Code CLI 作为实现者。Codex 负责协调任务、展示 Claude 的回复，并审核目标仓库的变更。
server 将经解析、目录验证且确认为 Git 仓库的 `workspacePath` 用作 Git 和 Claude Code 子进程的
`cwd`；这只是工作目录设置，不是操作系统级文件系统沙箱。

## 工作流程

1. 先使用状态工具检查目标工作区。
2. 通过显式的 `workspacePath` 将实现任务委派给 Claude Code。
3. 审核 server 返回的 Git 状态和未暂存差异摘要，再自行检查 `git diff`、`git diff --cached`，并逐个
   打开 `git status --short` 列出的未跟踪文件，确认完整变更后再决定是否接受结果。

## 环境要求

- Node.js 18 或更高版本
- Git
- Claude Code CLI
- Codex Desktop 或 Codex CLI

安装前请检查本地环境：

```text
node --version
git --version
claude --version
```

本项目没有运行时 npm 依赖，因此不需要执行 `npm install`。

## 安装

### Windows PowerShell

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex-tools" | Out-Null
git clone https://github.com/ltxzs/claude-subagent-mcp.git "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
Set-Location "$env:USERPROFILE\.codex-tools\claude-subagent-mcp"
node --check src/server.mjs
npm test
```

### macOS / Linux

```bash
mkdir -p ~/.codex-tools
git clone https://github.com/ltxzs/claude-subagent-mcp.git ~/.codex-tools/claude-subagent-mcp
cd ~/.codex-tools/claude-subagent-mcp
node --check src/server.mjs
npm test
```

## 注册到 Codex

将相应配置添加到全局 Codex 配置文件。Windows 的配置文件是
`%USERPROFILE%\.codex\config.toml`；macOS 和 Linux 的配置文件是 `~/.codex/config.toml`。

可参考 [examples/config.example.toml](examples/config.example.toml) 中的完整配置模板。模板中的
`REPLACE_WITH_ABSOLUTE_PATH_TO_SRC_SERVER_MJS` 必须替换为当前电脑上的实际路径。

`args` 必须写入 `src/server.mjs` 的实际绝对路径。不要指望 TOML 中的 `%USERPROFILE%` 或 `~`
被展开。

### Windows

```toml
[mcp_servers.claude_subagent]
command = "node"
args = ["C:\\Users\\alice\\.codex-tools\\claude-subagent-mcp\\src\\server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"
```

### macOS

```toml
[mcp_servers.claude_subagent]
command = "node"
args = ["/Users/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"
```

### Linux

```toml
[mcp_servers.claude_subagent]
command = "node"
args = ["/home/alice/.codex-tools/claude-subagent-mcp/src/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"
enabled_tools = ["get_claude_subagent_status", "delegate_to_claude"]

[mcp_servers.claude_subagent.env]
NODE_ENV = "production"
```

## 验证 MCP server

保存配置后重启 Codex，再确认下列两个工具可见：

```text
claude_subagent.get_claude_subagent_status
claude_subagent.delegate_to_claude
```

也可独立于 Codex，在项目目录向 server 进程发送 `initialize` JSON-RPC 请求，以验证进程本身。
这不能替代重启 Codex 和检查工具注册。响应必须包含 `claude-code-subagent`。

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}\n' | node src/server.mjs
```

```powershell
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}' | node src/server.mjs
```

## 使用方法

### 检查目标仓库

先调用 `claude_subagent.get_claude_subagent_status`：

```json
{
  "workspacePath": "C:\\path\\to\\repo"
}
```

### 委派实现任务

再调用 `claude_subagent.delegate_to_claude`，传入具体实现要求：

```json
{
  "task": "实现具体需求并运行相关测试",
  "workspacePath": "C:\\path\\to\\repo",
  "allowDirty": false,
  "timeoutMs": 1200000
}
```

### 审核返回结果

Claude 返回后，server 在结构化结果的 Git 部分包含审核相关字段 `statusShort`、`diffStat` 和
`diffNameOnly`，分别来自 `git status --short`、`git diff --stat` 和 `git diff --name-only`；结果还包含
`changedFiles` 和 `errors`（可能为空），但不提供完整 diff。后两个
命令与 `git diff` 一样，默认只覆盖未暂存变更；暂存变更需另行检查 `git diff --cached`。Codex 或用户
还必须逐个打开 `git status --short` 列出的未跟踪文件检查其内容，确认未暂存、暂存和未跟踪变更后再决定
是否接受实现结果。

## 工具参数

`delegate_to_claude` 接受以下参数：

| 参数 | 要求 |
| --- | --- |
| `task` | 必填，非空字符串。 |
| `workspacePath` | 必填，非空目录路径，且必须是 Git 仓库。 |
| `allowDirty` | 可选布尔值，默认 `false`。 |
| `resumeSessionId` | 可选的非空 Claude Code 会话 ID。 |
| `timeoutMs` | 可选整数，单位为毫秒；默认 `1200000`，且不得小于 `1000`。 |

`get_claude_subagent_status` 要求传入指向 Git 仓库的非空 `workspacePath`。

## 为什么必须传 workspacePath

这是全局 MCP server，不属于任何应用仓库。显式指定 `workspacePath` 后，server 会解析并验证该目录，
确认它是 Git 仓库，再将其用作 Git 和 Claude Code 子进程的 `cwd`，避免默认在 MCP server 目录或其他
误选目录运行。这不会限制子进程对其他文件系统路径的访问，也不构成操作系统级沙箱，因此只应传入可信仓库。

## 工作树有未提交改动

默认 `allowDirty=false`。当 `git status --short` 非空时，委派会停止，避免 Claude Code 在未经审核的
改动上叠加修改。只有在审核过现有改动并明确接受其作为上下文后，才将 `allowDirty` 设为 `true`。

## 继续 Claude Code 会话

将此前 Claude Code 结果中的非空 `session_id` 作为 `resumeSessionId` 传入，即可继续该会话。server 会以
`claude --resume <session_id>` 调用 Claude Code。

## 安全说明

- server 从不使用 `--dangerously-skip-permissions`。
- Claude Code 默认允许的工具仅限文件读写，以及 server 列出的常用 Git、测试和构建命令。
- `workspacePath` 只用作子进程的 `cwd`，不是文件系统访问边界。只传入可信仓库，并保留 Claude Code 的
  权限审批和人工审核。
- server 自身不执行 commit 或 push；附加系统提示会要求 Claude 不 commit、不 push，但默认允许的
  `Bash(git:*)` 仍可执行 Git 命令。这是行为约束，不是技术 denylist 或强制拦截。
- 接受任何实现前，必须保留审批并检查 `git status --short`、`git diff`、`git diff --cached`，以及每个
  未跟踪文件的内容。

## 常见错误排查

### Git 不可用

安装 Git，并在 Codex 使用的同一终端环境中确认 `git --version` 成功。

### Claude Code CLI 不可用

安装 Claude Code CLI，并在 Codex 使用的同一终端环境中确认 `claude --version` 成功。

### workspacePath 不是 Git 仓库

请传入目标项目根目录，并确保在那里执行 `git rev-parse --is-inside-work-tree` 成功。必要时使用
`git init` 初始化项目。

### 工作树有未提交改动

检查 `git status --short`、适用的 `git diff` 和 `git diff --cached`，并逐个打开未跟踪文件。清理或
提交无关改动；只有在这些改动本就应作为上下文时，才明确设置 `allowDirty` 为 `true`。

### Claude Code 超时

默认超时为 20 分钟。对于确定耗时较长的任务可增大 `timeoutMs`，或将任务拆分为更小的请求。

### Codex 中看不到工具

确认全局配置使用绝对 `args` 路径，重启 Codex，并确认 server 名称为 `claude_subagent`。

## 开发验证

```bash
npm run check
npm test
```

## 许可证

本项目采用 [MIT License](LICENSE) 授权。