Code Worker MCP

Languages: English | 简体中文

Code Worker MCP for Codex. The host agent defines task boundaries and reviews results; the worker does the expensive code reading, editing, and checking through Claude Code plus a configured provider.

Repository:

• GitHub: HuangYuan360/code-worker-mcp
• GitLab: pk-skills/lab/code-worker-mcp

Why This Exists

This project is built to solve a specific Codex workflow problem:

• the main thread should not spend most of its budget reading code
• long coding tasks should be able to run quietly in the background
• the host should see compact facts, not large logs by default
• execution should support clear fast / think tiers

The goal is to save Codex main-thread tokens, not provider tokens.

What It Does

• runs real code work through Claude Code
• supports async worker jobs
• supports sync tiny patches
• returns compact status, checks, policy, and change summaries
• supports long-running quiet jobs with heartbeat and liveness signals
• supports execution_tier, task_label, and model_label

flowchart LR
    A["Codex host"] -->|"task / tier / boundary"| B["Code Worker MCP"]
    B -->|"start"| C["Claude Code worker"]
    C -->|"read / edit / check"| D["real workspace"]
    C -->|"compact status"| B
    B -->|"task_label / execution_tier / model_label / files_changed / checks_run"| A

Recommended Deployment

Recommended mode: source deployment.

git clone https://github.com/HuangYuan360/code-worker-mcp.git
cd code-worker-mcp
npm install
npm run mcp:doctor

Add this MCP to ~/.codex/config.toml:

[mcp_servers.code-worker]
command = "node"
args = ["/absolute/path/to/code-worker-mcp/src/code-worker-mcp.mjs"]

[mcp_servers.code-worker.env]
CODE_WORKER_API_KEY_FILE = "/Users/you/.codex/secrets/code_worker_api_key"
CODE_WORKER_BASE_URL = "https://your-provider-compatible-endpoint/v1"
CODE_WORKER_FAST_MODEL = "<provider-fast-model>"
CODE_WORKER_THINK_MODEL = "<provider-think-model>"
CODE_WORKER_PERMISSION_PRESET = "open"

Restart Codex after configuration.

Required Deployment Inputs

Do not guess these values:

• provider key source
• CODE_WORKER_FAST_MODEL
• CODE_WORKER_THINK_MODEL
• CODE_WORKER_PERMISSION_PRESET

Provide these when needed:

• CODE_WORKER_BASE_URL
• CLAUDE_BIN

Validation

Recommended checks:

npm run mcp:doctor
npm run mcp:smoke:tools

Usage

Example async task:

{
  "name": "code_worker_start_implementation",
  "arguments": {
    "cwd": "/absolute/project/path",
    "task": "Make the requested code change.",
    "task_label": "orders-import-fix",
    "execution_tier": "fast"
  }
}

Execution tiers:

• fast
• think
• auto for host orchestration only

Compact result shape:

{
  "task_label": "orders-import-fix",
  "execution_tier": "fast",
  "model_label": "flash"
}

Long-Running Jobs

• start long tasks with code_worker_start_implementation
• do not use code_worker_wait_for_job as the main loop
• prefer sparse code_worker_get_job
• trust heartbeat and liveness fields
• do not cancel only because the worker is quiet

Cancellation requires an explicit reason:

• user_requested
• obsolete
• unsafe

Installation Guide For Other AI Tools

Installing only the MCP is not enough. Also install the companion skill into local Codex at:

• ~/.codex/skills/code-worker-governance/SKILL.md

See:

• docs/INSTALL-FOR-AI.md
• docs/INSTALL-FOR-AI.zh-CN.md