codex-mcp-opencode

中文 | English

A project-local MCP bridge: Codex plans; OpenCode executes in the project.

项目内 MCP 桥接器：Codex 负责规划，OpenCode 在项目内执行。

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 配置形状如下：

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

给其他用户的安装与接入

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

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

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

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

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

方式二：克隆后本地安装

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

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

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

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

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

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。

开发

npm test
npm run build
npm pack --dry-run

要对本机 OpenCode 和 MCP stdio 传输做显式集成验证（会消耗一次模型调用），在 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:

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

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

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:

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:

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

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:

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