CC 用「lockfile 发现 + IDE 充当 MCP server」把 CLI 接进编辑器，扩展自带 GUI 面板；Codex 用 app-server JSON-RPC 给官方 VS Code 扩展供电。两家在本快照中都未实现 ACP。

IDE / ACP 集成

结论

两家的 IDE 路线是镜像的。CC 的方向是 IDE→CLI：VS Code/JetBrains 扩展（插件）在编辑器内起一个 WebSocket/SSE 服务，往 ~/.claude/ide/<port>.lock 写发现文件；终端里的 claude CLI 扫描 lockfile、校验 workspace 与父进程谱系后，把 IDE 当作一个名为 ide 的 MCP server 连上——diff 展示、选区上下文都是这条 MCP 通道上的 RPC。Codex 的方向是 IDE←CLI：官方 VS Code 扩展（openai.chatgpt）是 codex app-server JSON-RPC 协议的客户端，agent 进程是服务方。换句话说，CC 把 IDE 做成 agent 的工具端点，Codex 把 agent 做成 IDE 的后端服务。ACP（Agent Client Protocol）本应是这两个相反方向的中立汇合层，但在两家本快照源码中均检索不到任何 ACP 实现——收敛尚未发生（详见 chapters/standards/acp.md）。

研究问题

CC CLI 和 IDE 扩展之间靠什么互相发现、用什么协议通信？diff/选区如何流转？
多窗口、多 IDE、WSL 这些脏场景 CC 怎么消歧？
Codex 的 IDE 故事是什么？app-server 在其中扮演什么角色？
ACP 是否已进入任何一家的代码库？harness 该不该押注 ACP？

各 Agent 设计与实现

Claude Code

两种使用形态。扩展本身已是 GUI 优先：VS Code 扩展提供原生面板（plan 审阅、auto-accept、@-mention 文件选区、多会话 tab），并且「The extension includes the CLI」[一手文档]（claude-code-docs/docs/vs-code.md，"native graphical interface... This is the recommended way"）。终端形态则是在 IDE 集成终端里跑 claude，靠下述发现机制接通。

发现机制：lockfile [一手源码]（CC 重构源码 src_2026-03-31/utils/ide.ts，以下行号同文件）：

扩展把服务信息写进 ~/.claude/ide/<port>.lock（目录由 getClaudeConfigHomeDir()+'ide' 给出，:462-463；WSL 下还会扫 Windows 侧 /mnt/c/Users/*/.claude/ide，:469-514）。
lockfile 是 JSON：{ workspaceFolders, pid, ideName, transport: 'ws'|'sse', runningInWindows, authToken }（LockfileJsonContent，:73-80）；端口编码在文件名里（12345.lock → 12345，:374-378）。
连接 URL 由 transport 决定：ws://host:port 或 http://host:port/sse（:794-798）——即 IDE 扩展开的是 WebSocket 或 SSE 形态的 MCP 端点。

校验与归属：CLI 不会乱连。有效性判定按优先级：env CLAUDE_CODE_SSE_PORT（扩展给集成终端注入的端口）直接匹配（:671-700）；否则 cwd 必须落在 lockfile 的 workspaceFolders 内（含 NFC 规范化处理 macOS NFD 路径，:676-678）；再加 PID 谱系检查——lockfile 里的 IDE 进程必须是当前 CLI 的祖先，用于多窗口同 workspace 消歧（:764-783）[一手源码]。stale lockfile 按 pid 存活 + 端口连通性双重判定后删除（cleanupStaleIdeLockfiles，:522-581）。

通信协议：IDE 即 MCP server。连上后 IDE 在 MCP client 列表中就叫 ide（:843-844、:1182-1185）；diff 能力的判定就是「存在名为 ide 的已连接 MCP client」（hasAccessToIDEExtensionDiffFeature，:838-845）；提交新 prompt 时通过 callIdeRpc('closeAllDiffTabs', ...) 关掉所有 diff 标签页（:1270-1279）[一手源码]。选区上下文由 IDE 自动共享，且 Read deny 规则可阻止匹配文件的选区上送 [一手文档]（jetbrains.md:26）。

自动安装：在受支持的 IDE 终端里启动时，CLI 会用 code --force --install-extension anthropic.claude-code 自动装/升扩展（:879-905），JetBrains 不支持自动装、引导去 marketplace（:907-910）。支持的 IDE 表硬编码 18 种（vscode 系：VS Code/Cursor/Windsurf；JetBrains 系：IDEA/PyCharm/WebStorm/GoLand/Rider/Android Studio 等，supportedIdeConfigs，:130-257）[一手源码]。

--ide flag：「Automatically connect to IDE on startup if exactly one valid IDE is available」[一手文档]（cli-reference.md:77）；交互内对应 /ide 选择器，findAvailableIDE() 轮询 30 秒、仅在恰好一个匹配时自动连（ide.ts:626-657）。终端类型识别走环境探测（isSupportedVSCodeTerminal/isSupportedJetBrainsTerminal，:271-285），还可用 FORCE_CODE_TERMINAL 强制。

plan 审阅是扩展独有交互 [一手文档]：Plan mode 下「VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins」；在 diff 视图里直接改 Claude 的提案后接受，「Claude is told that you modified it」（vs-code.md Use the prompt box / Review changes 两节）——这两类 UI 反馈通道是纯 CLI 没有的，说明 IDE 集成不只是「显示层」，而是多了一条人改 AI 提案的回路。

WSL2 已知断点：JetBrains + WSL2 组合下「No available IDEs detected」通常是 WSL2 NAT 网络或 Windows 防火墙拦了 WSL→Windows 宿主的连接（jetbrains.md:111）[一手文档]；源码侧对应大量 WSL 路径转换与 Windows 侧 lockfile 扫描逻辑（ide.ts:469-514,709-735）。

Codex CLI

app-server 是 IDE 集成的全部。README 第一句：「codex app-server is the interface Codex uses to power rich interfaces such as the [Codex VS Code extension](marketplace openai.chatgpt)」[一手源码]（codex-rs/app-server/README.md:3）。协议为省略 jsonrpc 头的 JSON-RPC 2.0，transports：stdio（默认）、websocket（实验、带 /readyz//healthz 探针与 Origin 403 防护）、unix socket（$CODEX_HOME/app-server-control/app-server-control.sock，配 codex app-server proxy 转发）（README.md:24-46）。背压：入口饱和时回 -32001 "Server overloaded; retry later."（README.md:55-58）。

协议面覆盖 thread/turn/item 生命周期、审批（Approvals）、认证端点（Auth endpoints）、Skills、Apps 等完整章节（README.md 目录），方法如 review/start（app-server-protocol/src/protocol/common.rs:812）、guardian 审批通知 item/autoApprovalReview/started|completed（common.rs:1541-1542）。generate-ts/generate-json-schema 导出版本对齐的类型——IDE 扩展即靠这个 schema 生成客户端 [一手源码]。实验性 API 需显式 opt-in（README "Experimental API Opt-in" 节），给协议演进留了灰度通道。

daemon 化趋势：仓库里另有 app-server-daemon、app-server-client、app-server-transport 等 crate（codex-rs/ 目录列表），加上 unix socket 的 control-plane 设计，方向是单 daemon 服务多客户端（IDE + CLI + SDK 共享会话），而非每个前端各起一个 agent 进程 [推断]（基于 crate 拆分与 app-server proxy 的存在）。

与 CC 的结构性差异：Codex 没有「CLI 去发现 IDE」的机制——没有 lockfile、没有进程谱系检查；扩展直接 spawn/连接 codex app-server，agent 是被动服务方。VS Code 扩展本体闭源不在本仓库（README 仅链接 marketplace，codex/README.md:6）[一手文档]。

ACP：双双缺席

在 codex-rs（@ b89ce9a）与 CC 重构源码（src_2026-03-31）中 grep agent-client-protocol / acp 均无命中 [一手源码-缺失证据]。即：截至各自快照日期，两家都没有把 ACP 作为 IDE 对接层。Zed 生态的 claude-code-acp 适配器属第三方包装（本仓库无源码，[推断]）。ACP 协议本体、registry 现状与 Yoda 是否实现 ACP client 的完整论证见 chapters/standards/acp.md，本章不重复。

差异矩阵

维度	Claude Code	Codex CLI
方向	IDE 扩展开服务，CLI 作为客户端连入	agent 开服务（app-server），IDE 扩展作为客户端
发现机制	`~/.claude/ide/<port>.lock` + `CLAUDE_CODE_SSE_PORT` + PID 谱系	无发现机制；扩展直连/直起 app-server
通信协议	MCP（ws / SSE），IDE 即名为 `ide` 的 MCP server	私有 JSON-RPC（无 `jsonrpc` 头），stdio/ws/uds
diff 查看	MCP 通道 RPC（`closeAllDiffTabs` 等），扩展内嵌 diff 面板	扩展自有 UI 消费 item/patch 事件
选区上下文	IDE 自动共享，受 `Read` deny 规则约束	扩展侧实现（闭源，本仓库不可见）[推断]
协议 schema	私有，无导出	`generate-ts` / `generate-json-schema` 官方导出
多 IDE 支持	18 种硬编码（VS Code 系 + JetBrains 系），JetBrains 有独立插件	官方仅 VS Code 系扩展（Cursor/Windsurf 同款）
扩展自动安装	CLI 自动 `code --install-extension anthropic.claude-code`	无（用户从 marketplace 装）
人改提案回路	plan 文档 inline 评论 + diff 内直接编辑（"you modified it" 回告）	扩展侧实现，本仓库不可见 [推断]
ACP	未实现（grep 无命中）	未实现（grep 无命中）

最小复现

# CC：查看 IDE 扩展写下的发现文件
ls ~/.claude/ide/
# 58234.lock
cat ~/.claude/ide/58234.lock
# {"workspaceFolders":["/Users/me/proj"],"pid":12345,"ideName":"Cursor","transport":"ws","authToken":"..."}

# CC：在 IDE 集成终端中自动连接（扩展会注入 CLAUDE_CODE_SSE_PORT）
echo $CLAUDE_CODE_SSE_PORT   # 58234
claude --ide

# CC：跳过 workspace 校验强连（调试用，ide.ts:697-698 的逃生门）
CLAUDE_CODE_IDE_SKIP_VALID_CHECK=1 claude --ide

# Codex：起 IDE 同款协议服务并导出 schema
codex app-server --listen stdio://
codex app-server generate-json-schema --out ./schema

# Codex：ws transport 自带健康探针（实验）
codex app-server --listen ws://127.0.0.1:8090 &
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8090/readyz   # 200

Harness 接入建议（Yoda 实践）

Yoda 是桌面 harness（Electron + PTY），与 IDE 扩展是同类竞争面而非宿主：不需要实现 CC 的 lockfile 协议（那是给「CLI 跑在编辑器终端里」的场景用的）。但有一个低成本可薅点——CC 的 lockfile 格式简单且稳定，Yoda 若想给「在 Yoda 内嵌终端里跑 claude」的用户提供 diff 面板，可以自己写一个 <port>.lock 并实现 ide MCP server 的最小方法集（diff 展示 + 选区上送），CLI 会把 Yoda 当成一个 IDE。注意 PID 谱系检查要求 Yoda 是 claude 进程的祖先——PTY spawn 天然满足；再给 PTY 注入 CLAUDE_CODE_SSE_PORT 可直接跳过 workspace 匹配（ide.ts:699-700 的快速通道）。
Codex 侧正路是 app-server：Yoda 想做 Codex 的富 UI（审批按钮、patch 预览）就实现 app-server 客户端，schema 用 generate-ts 生成保证版本对齐；这与 sdk 章建议的「结构化双轨」是同一条管道。
不建议 Yoda 现在实现 ACP server/client 押注收敛——两家头部 runtime 都还没上 ACP（本章缺席证据），先观望 registry 生态（结论与 chapters/standards/acp.md 对齐）。

失效条件

任一家合入 ACP 支持（关注 codex-rs 新 crate 与 CC changelog），「双双缺席」结论立即过期
CC lockfile 格式新增字段或迁移目录（现为 ~/.claude/ide/），自实现 ide MCP server 的方案需回归
CC 重构源码滞后线上约 2 个月：--ide/lockfile 行为以 docs 与实测为准，源码仅作架构参考
Codex app-server websocket transport 标注「experimental / unsupported」，转正或移除都影响接入选型
app-server-daemon 若落地为默认形态（单 daemon 多客户端），「扩展直起 app-server」的描述需更新

参考资料

CC 源码（重构）：claude-code-source-code/src_2026-03-31/utils/ide.ts（lockfile/发现/MCP 连接全流程）、hooks/useIDEIntegration.tsx
CC 文档：claude-code-docs/docs/vs-code.md、jetbrains.md、cli-reference.md:77
Codex 源码：codex-rs/app-server/README.md、app-server-protocol/src/protocol/common.rs（@ b89ce9a）
交叉章节：chapters/standards/acp.md（ACP 协议全量分析）、chapters/workflow/sdk.md（app-server 即 Python SDK 底座）
Codex VS Code 扩展（闭源，marketplace openai.chatgpt）：https://developers.openai.com/codex/ide

IDE / ACP 集成

On this page