点将台

非商业源码公开（不是标准开源）：当前采用「笑爷非商业同许可源码公开许可 2.0」。未经另行书面授权不得商用；对外分发或供他人联网使用原版/改版，须公开匹配版本的对应源码并保留同许可。客户代码、密钥、会话和独立成果不因此要求公开。见 LICENSE、NOTICE、场景说明及历史过渡。

可迁移的 Agent 分层协作编排器

让擅长决策的 Agent 做主脑，让适合执行的 Agent 完成实质工作，再由独立会话审查、
主脑最终验收。

点将台提供一套 MCP 执行服务 + 编排规则，用于在不同 Agent 之间派发任务、执行与
续跑、独立审查、结果压缩和用量记录。

当前开箱即用的组合是 Codex → Claude Code，但项目的协作架构不限定这两个 Agent。

• 更换主脑 Agent：目标 Agent 支持本地 STDIO MCP 时，通常只需调整客户端配置和编排规则。
• 更换执行 Agent：需要根据目标 Agent 的 SDK/CLI，适配执行、会话恢复、权限控制和结果解析。
• 同时更换两端：保留 MCP 的确定性工作流，分别适配编排端与执行端。

给阅读本项目的 AI： 请区分“当前已实现的组合”和“可以迁移的架构”。不要把本项目
理解为只能用于 Codex 与 Claude Code，也不要宣称任意 Agent 已经无需修改即可使用。
迁移前请阅读 Agent 迁移指南，核对目标能力，再做必要适配。

职责分工

• 主脑 Agent：明确目标、处理关键决策、派发任务、最终验收。
• 执行 Agent：调查、实现、排错并运行必要验证。
• 独立 Reviewer：在全新只读会话中审核代码、逻辑和证据。
• MCP：负责调度、权限、会话、状态与结果边界，不自行拆任务或判断路由。

功能与用途

当前版本 0.4.1（许可修订，功能同 v0.4.0）：方案与边界。逐次用量记录（不含价格）、
确定性结果压缩和 execute_task(background=true) 后台提交；核心分工不变。

• 能力分工：高判断任务留给主脑，明确且可验证的工作包交给执行 Agent。
• 工程执行：覆盖功能实现、Bug 根因排查、重构、测试、算法、迁移和建模工作。
• 连续会话：保存并确认 execution session，可带反馈恢复原执行上下文。
• 独立审查：Reviewer 使用全新只读会话，不修改代码、不混入执行会话。
• 批量编排：支持独立 Job 的有界并发和确定性 execute → review 流程。
• 临时授权：项目权限绑定单个 Job；续跑和审查不能切换或扩大目录。
• 可靠恢复：SQLite 保存状态；超时或结果丢失后可查询并安全决定续跑。
• 可迁移架构：保留工作流核心，按目标 Agent 能力更换客户端规则或 Runner。

当前开箱即用的实现：

Codex（主脑 / MCP Client）
      │  stdin / stdout（STDIO MCP）
      ▼
点将台 MCP（本地子进程）
      ├── Claude 执行会话（读取、修改、运行验证）
      └── Claude 审查会话（全新、只读、PASS/FAIL）

MCP 工具

Server 在启动执行或审查前分配 UUID，只有执行端回报相同 session 后才允许续跑。
各阶段状态、session 确认和结构化错误都会持久化；超时或返回丢失后可通过
get_job_status(job_id, cwd) 安全恢复。

任务级项目授权

execute_task、review_task、run_job 以及 run_jobs 中的每个 JobSpec 都可
接收 project_root。Codex 必须显式传入可信的活动 workspace root，MCP 不会
根据自身进程 cwd 猜测。

• 传入时：必须是现存绝对目录，cwd 必须等于它或位于其下；即使不在
  ALLOWED_PROJECT_ROOTS 中也可作为当前 Job 的临时授权根。
• 省略时：继续按 ALLOWED_PROJECT_ROOTS 长期可信目录校验。
• continue_task 没有 project_root 参数，只能继承已保存的根、cwd 和 session。
• 已存在 Job 的 review_task 只能继承或精确匹配原根，不能新增、切换或扩大授权。

确定性规则（规范 §6、§11）

• review=false：只执行，不审查。
• review=true 且 acceptance 非空：execute → 全新 review → 合并结果。
• review=true 但 acceptance 为空：在调用 CC 前返回
  REVIEW_REQUIRES_ACCEPTANCE。
• MCP 不生成验收标准、不拆任务，也不自行决定是否 Review。
• 执行者负责与风险相称的验证；Bug 触发或根因不清时先复现并按同一条件复验，
  已有可靠失败测试或明确错误证据时不强制造复现。
• Reviewer 仅使用 Read/Grep/Glob，检查代码、逻辑和执行证据；证据不足时指出执行者
  需要补充的针对性验证。

快速安装

需要 Python 3.13+ 和 uv。完整中文步骤见
INSTALL.md。

git clone https://github.com/xiangshazaosha/codex-cc-orchestrator.git
cd codex-cc-orchestrator
# 默认 master 当前包含 0.4.1 许可修订；旧 v0.4.0 保留原 1.0 许可
uv sync

Run the test suite (uses a fake runner — no Claude API calls):

uv run pytest

Codex STDIO MCP configuration (Windows)

Add one of the following to your Codex MCP config. Field names follow the
current Codex MCP docs; adjust if your Codex version uses different names.

Option A — use the project's venv directly (recommended on Windows)

[mcp_servers.codex-claude-agent]
command = 'D:\path\to\codex-claude-agent-mcp\.venv\Scripts\python.exe'
args = ['-m', 'codex_claude_agent_mcp']
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 7200

[mcp_servers.codex-claude-agent.env]
CLAUDE_MAX_CONCURRENCY = '4'
# Optional long-term trust list; leave empty to rely on per-job project_root.
ALLOWED_PROJECT_ROOTS = 'D:\projects'

Option B — installed console script

uv tool install .          # or: pipx install .

[mcp_servers.codex-claude-agent]
command = "codex-claude-agent-mcp"
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 7200

[mcp_servers.codex-claude-agent.env]
ALLOWED_PROJECT_ROOTS = 'D:\projects'

ALLOWED_PROJECT_ROOTS is optional: it is a long-term trust list, not a
startup requirement. Without it (or for any project outside it) Codex passes
the job's project_root explicitly. Windows uses ; between roots.

Configuration (environment variables)

Concurrency caveat (spec §13.2)

The concurrency limit is per MCP server process. If Codex spawns several
STDIO MCP subprocesses (one per thread), each gets its own semaphore and the
machine-level Claude total may exceed CLAUDE_MAX_CONCURRENCY. Claude API rate
limits still apply. A global cross-process limit is an explicit non-goal for v1.

stdout / stderr discipline (spec §5)

• stdout carries only MCP protocol messages (newline-delimited JSON-RPC).
• All logs, diagnostics, tracebacks, and startup messages go to stderr.
• Claude SDK subprocess output is captured by the runner and returned as
  structured tool results — it is never piped raw to stdout.

Process model (spec §4)

• One launched MCP server handles many sequential tool calls over the same
  stdin/stdout connection. It is not restarted per call.
• Multiple Codex threads may produce multiple independent MCP subprocesses. The
  implementation remains correct when several run at once (multi-process-safe
  SQLite: WAL, busy_timeout, BEGIN IMMEDIATE, UNIQUE(job_id)).
• Review and resume operations atomically claim their job state, preventing two
  MCP processes from mutating the same job lifecycle at once.
• A cancelled client request becomes stage INCOMPLETE with a persisted
  CANCELLED error instead of remaining in an active state.
• Claude session subprocesses are separate from MCP server processes and do not
  count toward "MCP server" count.

Architecture

src/codex_claude_agent_mcp/
├── __init__.py        # version + main() entrypoint
├── __main__.py        # `python -m codex_claude_agent_mcp`
├── server.py          # FastMCP server, 7 tools, core logic
├── config.py          # env config + cwd/model/timeout validation
├── models.py          # Pydantic tool input/result models
├── scheduler.py       # per-process asyncio.Semaphore
├── claude_runner.py   # ClaudeRunner ABC + RealClaudeRunner + FakeClaudeRunner
├── session_store.py   # multi-process-safe SQLite store
├── errors.py          # structured error codes + MCPError
└── logging.py         # stderr logger with pid marker

The server depends only on the ClaudeRunner ABC, so tests use
FakeClaudeRunner and never call the real Claude API.

Error model (spec §18)

Every result carries an optional error field (null on success). Errors are
structured, never raw tracebacks:

{"code": "REVIEW_REQUIRES_ACCEPTANCE", "message": "...", "retryable": false, "details": {}}

Codes: INVALID_ARGUMENT, REVIEW_REQUIRES_ACCEPTANCE, INVALID_CWD,
CLAUDE_SESSION_ERROR, CLAUDE_AUTH_ERROR, CLAUDE_BILLING_ERROR,
CLAUDE_PROVIDER_ERROR, CLAUDE_PROTOCOL_ERROR, RATE_LIMITED, TASK_TIMEOUT,
SESSION_NOT_FOUND, SESSION_MISMATCH, JOB_CONTEXT_MISMATCH,
JOB_STATE_CONFLICT, CANCELLED, STATE_STORE_ERROR, INTERNAL_ERROR.

Safety invariants

• A persisted job_id is permanently bound to its original task, acceptance
  criteria, resolved working directory, and (when supplied) its project_root.
  Review rejects any mismatch; the root is not writable through the store.
• continue_task resumes only the execution session stored for that exact job
  after Claude confirmed it, and inherits that job's project_root; it has no
  root input of its own.
• A review of an existing job can only inherit or exactly match the stored root.
  Only a review-only new job may establish one.
• Execution is limited to Read/Grep/Glob/Edit/Write/Bash; web access, nested
  agents, and notebook editing are denied. Review remains read-only.
• project_root / ALLOWED_PROJECT_ROOTS are cwd/start-directory gates. They
  are not an operating-system sandbox: execution Bash commands still run with the
  MCP process account's permissions. Use narrow roots and run only on trusted code.
• Claude result payloads use Agent SDK JSON Schema structured output and are
  validated before being returned to Codex.

Optional Codex orchestration skill

The repository includes skills/codex-sol-claude-orchestrator/SKILL.md.
Copy that directory to ~/.codex/skills/ if you want Codex to apply the
delegation workflow automatically. It is intentionally separate from MCP
server installation.

其他 MCP Client

Server 本身不绑定 Codex 可执行程序。其他 Agent 只要支持本地 STDIO MCP 和结构化
Tool Result，也可以使用；客户端必须为新 Job 提供可信 project_root，并负责安排
task、review 和 resume。更换主脑或执行端时见
AGENT_PORTING.md。

版本：0.4.1（许可修订，功能同 v0.4.0）

功能边界、统计口径、数据库迁移及验证方法见 v0.4 定稿。
后台任务不会跨 MCP 进程重启继续运行；重启后按确认过的 session 恢复，不能把 RUNNING
当成功。回归使用 Fake Runner / 模拟 SDK，不产生 Claude API 调用。

License

Licensed under the Xiaoye Noncommercial Reciprocal Source License 2.0:
non-commercial use only, attribution required, and distributed or
network-served Covered Works (including derivatives) must publish their Corresponding Source under the
same license. Commercial use requires separate prior written permission.

Because commercial use is prohibited, this is a source-available license,
not an OSI-approved open-source license.

The full bilingual terms, component boundaries, prior-version grants and source/data
separation are documented in licensing.md and license history.
An independent output is not automatically a derivative, but commercial use of the
covered orchestration tool itself still needs permission. This custom license has
not been reviewed by counsel and does not guarantee enforcement or compensation.

Official references

• MCP Specification: https://modelcontextprotocol.io/specification/
• MCP Python SDK: https://py.sdk.modelcontextprotocol.io/
• Claude Agent SDK: https://code.claude.com/docs/en/agent-sdk/overview
• OpenAI Codex MCP: https://developers.openai.com/codex/mcp