# Code Worker MCP

Languages: [English](README.md) | [简体中文](README.zh-CN.md)

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](https://github.com/HuangYuan360/code-worker-mcp)
- GitLab: [pk-skills/lab/code-worker-mcp](http://git.io.pkfare.com/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`

```mermaid
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**.

```bash
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`:

```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:

```bash
npm run mcp:doctor
npm run mcp:smoke:tools
```

## Usage

Example async task:

```json
{
  "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:

```json
{
  "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.md)
- [docs/INSTALL-FOR-AI.zh-CN.md](docs/INSTALL-FOR-AI.zh-CN.md)