# codex-mcp-opencode

[中文](#中文说明) | [English](#english)

> A project-local MCP bridge: Codex plans; OpenCode executes in the project.
>
> 项目内 MCP 桥接器：Codex 负责规划，OpenCode 在项目内执行。

```text
Codex Desktop  ->  codex-mcp-opencode  ->  OpenCode Server/SDK  ->  Current project
    planning          thin control plane       sessions/models         code and tools
```

## 中文说明

### 它解决什么问题

`codex-mcp-opencode` 让 Codex Desktop 作为项目的规划者和调度者，而 OpenCode 作为实际执行者。Codex 只需向 OpenCode 下达简短、具体的工作指令；OpenCode 从启动它的当前项目目录中自行读取代码、配置和已有上下文。

它不是第二个项目记忆系统，也不是 API Key 管理器，更不会向模型重复发送源码或项目摘要。模型、供应商和凭据始终由 OpenCode 自己管理。

### 核心特性

| 能力 | 说明 |
| --- | --- |
| 项目天然隔离 | MCP 从当前项目目录启动，不接受 `project_path` 一类参数。 |
| 短期会话复用 | 默认复用 24 小时内、同模型且空闲的主会话，减少重复加载上下文。 |
| 生命周期管理 | 可列出、取消、删除、清理过期会话；不会自动删除活动会话或子会话。 |
| 原生后台子代理 | 只使用 OpenCode 的后台 subagent 能力，不实现 worktree 或外部并行替代。 |
| MCP 长任务 | 通过 `opencode.task` 启动、查询、短连接等待或取消；任务本身无桥接器时限，不依赖宿主协商实验性 MCP Tasks。 |
| 跨会话恢复 | 每个项目复用一个本地、脱离 MCP 进程的 OpenCode server；异步任务 ID 和 server 端点均持久化，新的 MCP 进程可继续查询结果。 |
| 原生压缩 | 使用 OpenCode 的 token 统计；复用会话的估算上下文达到 550k 时，请求 OpenCode 原生摘要，以便在 600k 前完成压缩。 |
| 保守权限 | OpenCode 以 `ask` 权限启动；独立监视器持久化原生权限请求，可经 MCP 查询和响应。 |

### 前置条件

1. Node.js 20 或更高版本。
2. `opencode` 已安装并在 `PATH` 中可用，或通过 `OPENCODE_BIN` 指向其可执行文件；模型和凭据仍只在 OpenCode 内配置。
3. OpenCode 中必须开启原生压缩和裁剪：`compaction.auto: true`、`compaction.prune: true`。

桥接器使用 OpenCode 实际上报的模型上下文上限，不再要求所有供应商都伪装为同一个数值。对复用会话，它在下一次提示前检查 OpenCode 最近一次报告的上下文估算（输入 + 缓存读取 + 输出）；达到 **550k** 时调用 OpenCode 原生摘要，目标是在 **550k–600k** 窗口内完成压缩。模型压缩策略仍完全由 OpenCode 配置管理。

通用的 OpenCode 配置形状如下：

```json
{
  "compaction": { "auto": true, "prune": true }
}
```

### 给其他用户的安装与接入

本仓库当前可直接从 GitHub 安装，尚未发布到 npm。使用者不需要修改源码、填写 API Key，也不需要在工具调用中提供项目路径。

#### 方式一：直接在 Codex MCP 配置中使用 GitHub（推荐）

将以下命令配置为 Codex 的 stdio MCP 服务：

```text
command: npx
args:    --yes github:Ichikawashadow/codex-mcp-opencode
```

Codex 必须从当前打开的目标项目目录启动该命令。`npx` 从 GitHub 获取包时会运行 `prepare` 自动构建；之后 OpenCode 仍由 MCP 在当前项目内拉起。

#### 方式二：克隆后本地安装

```powershell
git clone https://github.com/Ichikawashadow/codex-mcp-opencode.git
cd codex-mcp-opencode
npm ci
npm run build
```

然后将下面的程序配置为 Codex 的 stdio MCP 服务：

```text
command: node
args:    <安装目录>/dist/index.js
```

这里的 `<安装目录>` 是 MCP 自身的本机安装位置，不是目标项目路径。它只应存在于用户自己的 Codex 配置中，不能写进本仓库、代码或工具参数。

无论选哪种方式，都要确认：

```powershell
opencode --version
```

能正常运行，并且 OpenCode 已在其自己的配置中完成模型/API 配置。

首次使用时：

1. 调用 `opencode.configure`，不传参数。
2. 从返回的模型列表中选择一个可用的 `<provider-id>/<model-id>`。
3. 再次调用 `opencode.configure`，将它作为 `defaultModel`。
4. 使用 `opencode.run` 向 OpenCode 发送简短工作指令。

日常使用时，Codex 可先调用 `opencode.sessions` 查看近期会话，再用 `opencode.run` 复用会话或启动新工作。`opencode.run(asynchronous: true)` 会返回持久 `taskId`；普通 `opencode.run` 若在 20 秒内完成则直接返回输出，若仍在执行会返回 `accepted`，若触发原生审批会返回 `input_required`，两者均携带可恢复的 `taskId`。对超过五分钟、半小时或数小时的工作，建议直接用 `opencode.task` 的 `start`。两种方式都可在新的 MCP 进程中用 `status` 或 `wait` 取回结果。任务开始后的 30 秒内建议每 2 秒查询一次，以便立即显示审批；之后前 10 分钟每 60 秒查询一次，随后每 5 分钟一次。`wait` 的 1-240 秒仅是单次 RPC 的安全窗口。取消会先拒绝该任务未回复的权限、再中止会话，且终态后桥接器不会再回传其输出。需要并行时，传入 `backgroundSubagents: true`；它只会启用 OpenCode 原生后台子代理。

### 工具参考

| 工具 | 何时使用 |
| --- | --- |
| `opencode.configure` | 首次配置、查看 OpenCode 可用模型、设置默认模型和复用/清理周期。 |
| `opencode.run` | 正常执行任务；设 `asynchronous: true` 时返回可跨 MCP 会话恢复的 `taskId`。 |
| `opencode.task` | 长任务管理：`start` 立即返回任务 ID 与建议查询间隔，`status` 查询，`wait` 仅进行最多 240 秒的单次 RPC 等待，`cancel` 取消。任务本身可持续数小时。 |
| `opencode.sessions` | `list`、`cancel`、`delete`、`cleanup`，或用 `permissions` / `respond_permission` 处理原生授权；`shutdown_server` 仅关闭无活动任务且由桥接器启动的 server。 |

### 会话和权限

本地注册表按工作目录隔离，只保存会话 ID、父会话 ID、模型 ID、时间戳及活动任务 ID。它不保存提示词、代码、Diff、日志、模型输出、路径、密钥或项目摘要。OpenCode 才是会话历史与输出的唯一来源。

标准 MCP 无法把 Codex Desktop 的实时逐命令审批状态传给服务器，因此无法承诺完全相同的动态权限。桥接器采取更严格的下限：`edit`、`bash`、`webfetch`、`external_directory` 和 `doom_loop` 均为 `ask`。当 OpenCode 请求操作许可时，用 `opencode.sessions` 查看并显式响应。

OpenCode server 为跨 MCP 会话恢复而保持脱离 stdio 运行。若需要移动或删除工作目录，请先确保没有活动 bridge task，再调用 `opencode.sessions(action: "shutdown_server")`；它只会终止由该桥接器显式记录为 managed 的 server，不会终止用户配置的外部 server 或旧版未标记 server。

### 开发

```powershell
npm test
npm run build
npm pack --dry-run
```

要对本机 OpenCode 和 MCP stdio 传输做显式集成验证（会消耗一次模型调用），在 PowerShell 中运行：

```powershell
$env:OPENCODE_E2E = '1'
npm run test:e2e
```

---

## English

### What it is for

`codex-mcp-opencode` makes Codex Desktop the planner and dispatcher for a project, while OpenCode is the execution agent. Codex sends short, specific work instructions; OpenCode reads code, configuration, and existing context directly from the project directory in which it was launched.

This is not a second project-memory system or an API-key manager. It never sends source trees or broad project summaries back through the bridge. Providers, models, and credentials remain entirely in OpenCode.

### Key capabilities

| Capability | Behavior |
| --- | --- |
| Project-local by default | The MCP starts in the current project directory and has no `project_path` argument. |
| Short-lived session reuse | By default, an idle primary session using the same model is reused for 24 hours. |
| Session lifecycle | List, cancel, delete, and clean expired sessions without automatically deleting active or child sessions. |
| Native background subagents | Uses only OpenCode background subagents; there is no worktree or external-parallel fallback. |
| Long-running tasks | `opencode.task` starts, checks, bounded-waits for, and cancels work without depending on experimental MCP Task negotiation. The task itself has no bridge-imposed duration limit. |
| Cross-session recovery | Each project reuses a local OpenCode server detached from the MCP process; async task IDs and the server endpoint are persisted so a new MCP process can retrieve results. |
| Native compaction | The bridge uses OpenCode token accounting and requests native summarization at 550k estimated context, keeping compaction ahead of 600k. |
| Conservative permissions | OpenCode starts with `ask` permissions; a detached monitor persists native permission requests for MCP inspection and response. |

### Prerequisites

1. Node.js 20 or later.
2. `opencode` available on `PATH`, or its executable supplied through `OPENCODE_BIN`; models and credentials remain configured in OpenCode.
3. Native OpenCode compaction enabled: `compaction.auto: true` and `compaction.prune: true`.

The bridge uses the context limit reported by OpenCode and does not require every provider to advertise an artificial common value. Before resuming a session, it checks OpenCode's latest estimated context (input + cache read + output) and requests native summarization at **550k**, so compaction occurs within the **550k-600k** window. Model compaction policy remains entirely in OpenCode configuration.

Use this portable OpenCode configuration shape:

```json
{
  "compaction": { "auto": true, "prune": true }
}
```

### Installation and connection for other users

This repository can currently be installed directly from GitHub; it has not been published to npm. Users do not need to edit source code, enter API keys, or provide project paths in tool calls.

#### Option 1: use GitHub directly in Codex MCP configuration (recommended)

Configure this command as a Codex stdio MCP server:

```text
command: npx
args:    --yes github:Ichikawashadow/codex-mcp-opencode
```

Codex must start the command from the currently opened target project directory. When `npx` obtains the package from GitHub it runs `prepare` to build it; the MCP still starts OpenCode inside the current project.

#### Option 2: clone and install locally

```powershell
git clone https://github.com/Ichikawashadow/codex-mcp-opencode.git
cd codex-mcp-opencode
npm ci
npm run build
```

Then configure this program as a Codex stdio MCP server:

```text
command: node
args:    <installation-directory>/dist/index.js
```

`<installation-directory>` is the user's local MCP installation, not the target project path. It belongs only in the user's Codex configuration, never in this repository, source code, or tool arguments.

With either option, confirm that:

```powershell
opencode --version
```

works and that OpenCode has its own model/API configuration.

First use:

1. Call `opencode.configure` with no arguments.
2. Select an available OpenCode model from the returned list.
3. Call `opencode.configure` again with that `<provider-id>/<model-id>` as `defaultModel`.
4. Use `opencode.run` to send short work instructions to OpenCode.

For daily work, Codex can call `opencode.sessions` to inspect recent sessions and then call `opencode.run` to reuse a session or start fresh work. `opencode.run(asynchronous: true)` returns a durable `taskId`; a normal `opencode.run` returns direct output when it completes within 20 seconds, otherwise returns `accepted`, and returns `input_required` when native approval is needed. Both non-completed cases include a recoverable `taskId`. For work that may take more than five minutes, half an hour, or several hours, prefer `opencode.task` with `start`. Either form can be recovered from a new MCP process with `status` or `wait`. Poll every 2 seconds for the first 30 seconds to surface approval promptly, every 60 seconds for the rest of the first 10 minutes, and every 5 minutes thereafter; a 1-240 second `wait` is only a safe single-RPC window. Cancellation rejects unresolved permissions before aborting the session, and the bridge never returns output for a cancelled task. For parallel work, pass `backgroundSubagents: true`; this only enables OpenCode native background subagents.

### Tool reference

| Tool | When to use it |
| --- | --- |
| `opencode.configure` | First-time setup, model discovery, and default model/reuse/cleanup settings. |
| `opencode.run` | Normal task execution; with `asynchronous: true`, returns a `taskId` recoverable across MCP sessions. |
| `opencode.task` | Long-running work: `start` returns a task ID and recommended poll interval immediately; `status` checks it; `wait` uses only a safe single-RPC window of up to 240 seconds; `cancel` stops it. The task can run for hours. |
| `opencode.sessions` | Use `list`, `cancel`, `delete`, or `cleanup`; use `permissions` and `respond_permission` for native authorization requests; `shutdown_server` stops an idle bridge-owned server only. |

### Sessions and permissions

The small local registry is isolated by launch directory. It stores only session IDs, parent session IDs, model IDs, timestamps, and active task IDs. It never stores prompts, code, diffs, logs, model output, paths, keys, or project summaries. OpenCode is the single source of truth for session history and output.

Standard MCP does not expose Codex Desktop's live per-command approval state to servers, so exact dynamic permission mirroring is impossible. The bridge takes the stricter floor: `edit`, `bash`, `webfetch`, `external_directory`, and `doom_loop` all start as `ask`. Use `opencode.sessions` to inspect and explicitly answer OpenCode permission requests.

The OpenCode server intentionally outlives stdio so tasks can recover across MCP calls. Before moving or removing a workspace, ensure there are no active bridge tasks and call `opencode.sessions(action: "shutdown_server")`. It terminates only a server explicitly recorded as bridge-managed; it never terminates a user-configured external server or an older unmarked runtime.

### Development

```powershell
npm test
npm run build
npm pack --dry-run
```

To explicitly test local OpenCode and the MCP stdio transport (this makes one model call), run in PowerShell:

```powershell
$env:OPENCODE_E2E = '1'
npm run test:e2e
```