Skip to content
Back to search

plane-codex-mcp

A Codex plugin that quietly captures meaningful project work and syncs it to Plane.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bene-2020--plane-codex-mcp/badge.svg)](/listings/bene-2020--plane-codex-mcp)

HTML

<a href="/listings/bene-2020--plane-codex-mcp"><img src="/api/listings/bene-2020--plane-codex-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. 准备 Plane

你需要:

- 一个可访问的 Plane Cloud 或自托管实例; - Workspace slug,例如 `https://app.plane.so/my-team/` 中的 `my-team`; - 一个有目标项目读写权限的 Plane Personal Access Token。

Plane 官方文档说明了 [API Key 的创建位置与使用方式](https://developers.plane.so/api-reference/introduction)。请把 API Key 当作密码保管。

2. 安装对应平台的插件包

下载形如 `ambient-project-layer-v0.1.4-<target>.zip` 的资产,解压到不会随意移动的目录。下文用 `<RELEASE_DIR>` 表示解压后的绝对路径;该目录应直接包含 `.agents/plugins/marketplace.json`。

codex plugin marketplace add "<RELEASE_DIR>"
codex plugin add ambient-project-layer@ambient
codex plugin list

Codex 官方将插件定义为可安装的技能、MCP Server 和可选 UI 组合;本地开发或独立分发的插件通过 local marketplace 安装。可参考 [Build plugins](https://learn.chatgpt.com/docs/build-plugins)。

安装后,打开 Codex 的 Hook 管理界面,逐一复核并信任当前版本的以下 Hook:

- `SessionStart` - `UserPromptSubmit` - `PostToolUse` - `Stop` - `SessionEnd`

插件显示 `enabled` 不等于 Hook 已获得信任。安装或升级后如果 Hook 显示 `modified`,需要重新信任。

3. 配置 Plane 连接

正式插件不读取仓库或项目目录中的 `.env`。Plane 配置保存在用户级 `~/.codex/config.toml` 中,并由 Codex 启动 `ambient-project` MCP Server 时注入。

先新建一次 Codex task,让 Hook 创建插件数据目录。随后把 MCP 的 `AMBIENT_DB_PATH` 指向同一个 `PLUGIN_DATA/ambient.sqlite`:

- macOS/Linux:`$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite` - Windows:`%USERPROFILE%\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite`

macOS/Linux 示例:

codex mcp add ambient-project \
  --env "AMBIENT_DB_PATH=$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite" \
  --env "PLANE_MODE=sdk" \
  --env "PLANE_TYPE_MODE=default" \
  --env "PLANE_BASE_URL=https://api.plane.so" \
  --env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" \
  --env "PLANE_API_KEY=replace-in-config-toml" \
  -- "<RELEASE_DIR>/plugins/ambient-project-layer/runtime/bin/ambient-node" \
     "<RELEASE_DIR>/plugins/ambient-project-layer/runtime/mcp/index.js"

Windows PowerShell 示例:

codex mcp add ambient-project `
  --env "AMBIENT_DB_PATH=$env:USERPROFILE\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite" `
  --env "PLANE_MODE=sdk" `
  --env "PLANE_TYPE_MODE=default" `
  --env "PLANE_BASE_URL=https://api.plane.so" `
  --env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" `
  --env "PLANE_API_KEY=replace-in-config-toml" `
  -- "<RELEASE_DIR>\plugins\ambient-project-layer\runtime\bin\ambient-node.cmd" `
     "<RELEASE_DIR>\plugins\ambient-project-layer\runtime\mcp\index.js"

然后编辑 `~/.codex/config.toml`,仅在 `[mcp_servers.ambient-project.env]` 中把占位值替换为真实 Workspace slug 和 API Key。不要把真实 Key 放进上面的命令、仓库、Issue、日志或截图中,以免进入 shell history 或公开记录。

`PLANE_TYPE_MODE` 控制工作项分类策略:

- `default`(默认,适合 Plane Free):不访问付费的 Work Item Types 目录,创建时使用 Plane 默认类型,并把语义分类写入标题前缀,例如 `[Bug]-登录失败`、`[Decision]-采用 SQLite`。 - `custom`(适合 Plane Pro / Business):为 Task、Bug、Decision、Idea、Risk、Milestone 解析或创建对应的自定义 Work Item Type。类型目录只在创建工作项且映射缺失时读取,普通刷新、计数和状态更新不会访问它。

修改 `PLANE_TYPE_MODE` 后必须完全重启 Codex。不同模式不会自动重写已有工作项。

升级到 v0.1.4 后,后台同步 Worker 会为每个终态失败批次提供一次自动恢复机会,包括升级前遗留的历史失败。多个 MCP Worker 通过 SQLite 共享同一节流队列:Plane 请求默认间隔 2 秒,自动恢复批次至少间隔 10 秒;遇到 429 时按服务端重置时间暂停全局队列,限流等待不消耗业务重试次数。恢复仍失败的批次会继续保持终态;之后可在 Panel 中人工 Retry、Correct 或 Dead-letter。

自托管 Plane 用户还需要把 `PLANE_BASE_URL` 换成实例的 API Base URL。

在本机检查 MCP 配置:

codex mcp get ambient-project

该命令的输出可能包含 Plane API Key。不要把输出复制到 Issue、日志、聊天或截图中;对外排查问题时只提供已经移除凭据的内容。

完成后完全退出并重新启动 Codex,再新建一个 task。已经运行的 MCP 进程不会自动读取修改后的配置。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 260 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Ambient Project Layer
  2. 中文 | [English](README_EN.md)
  3. 让 Codex 在工作过程中安静地整理项目进展,并将任务、Bug、决定、风险和里程碑同步到 Plane。
  4. [Plane](https://plane.so/open-source) 是一款采用 AGPL-3.0 许可证的开源项目管理平台,既可以免费自行部署 Community Edition,也提供免费的云端方案。其自托管 Community Edition 不限制用户数,云端 Free 方案目前支持最多 12 名用户,因此非常适合个人开发者、一人公司(OPC)和小团队使用;具体额度以 [Plane 官方定价页](https://plane.so/pricing) 为准。
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  6. [![Version](https://img.shields.io/badge/version-v0.1.4-4f6bed.svg)](CHANGELOG.md)
  7. Ambient Project Layer 是一个 Codex 插件。它从当前工作回合中捕获真正有项目价值的事件,先可靠写入本地 SQLite Outbox,再异步同步到 Plane。你可以继续在 Plane 中做完整的项目管理,也可以在 Codex 内通过轻量 Panel 查看最近工作项并修改状态。
  8. 开发工作已经在 Codex 中发生,但任务、决定和风险往往要靠人再次整理到项目管理工具中。Ambient Project Layer 把这段重复劳动压缩成一个安静、可审查的后台流程。
  9. ## 产品界面
  10. ![在 Codex 对话中打开 Ambient Project Panel 并拖动工作项](docs/assets/ambient-project-panel.gif)
  11. Panel 默认展示最多 5 个相关工作项,支持按 Backlog、Todo、In Progress 和 Done 筛选,并可通过状态菜单或拖拽更新状态。完整创建、编辑、归档和项目管理仍在 Plane 中完成。
  12. Panel 的 UI 直接沿用 Plane 开源产品的视觉风格,包括配色、状态标签、卡片层级和交互方式,让用户在 Codex 与 Plane 之间获得一致的使用体验。该界面由本项目实现,并非 Plane 官方组件。
  13. ## 主要能力
  14. - 自动识别任务、Bug、决定、想法、风险、里程碑、计划、进展和完成事件。
  15. - 使用本地 SQLite Outbox 保证事件先落盘,再异步同步到 Plane。
  16. - 首次进入项目目录时列出真实 Plane 项目,由用户明确选择绑定目标。
  17. - 在 Codex 内提供轻量 Inline Panel,查看相关工作项、同步状态并跳转 Plane。
  18. - 不保存完整对话、源码、终端输出或 Plane API Key。
  19. - 每个平台的 Release 包自带 Node.js 22.22.1,无需用户另装 Node、pnpm 或 bun。
  20. ## 支持平台
  21. 从 [GitHub Releases](https://github.com/Bene-2020/plane-codex-mcp/releases/latest) 下载与机器匹配的压缩包:
  22. | Release 目标 | 系统 | 架构 |
  23. | --- | --- | --- |
  24. | `darwin-arm64` | macOS | Apple Silicon |
  25. | `darwin-x64` | macOS | Intel |
  26. | `linux-x64` | Linux | x86_64 |
  27. | `linux-arm64` | Linux | ARM64 / aarch64 |
  28. | `win32-x64` | Windows | x86_64 |
  29. 不确定架构时,可在 macOS/Linux 运行 `uname -m`:`arm64` 或 `aarch64` 选择 ARM64,`x86_64` 选择 x64。当前不提供 Windows ARM64 安装包。
  30. ## 安装
  31. ### 1. 准备 Plane
  32. 你需要:
  33. - 一个可访问的 Plane Cloud 或自托管实例;
  34. - Workspace slug,例如 `https://app.plane.so/my-team/` 中的 `my-team`;
  35. - 一个有目标项目读写权限的 Plane Personal Access Token。
  36. Plane 官方文档说明了 [API Key 的创建位置与使用方式](https://developers.plane.so/api-reference/introduction)。请把 API Key 当作密码保管。
  37. ### 2. 安装对应平台的插件包
  38. 下载形如 `ambient-project-layer-v0.1.4-<target>.zip` 的资产,解压到不会随意移动的目录。下文用 `<RELEASE_DIR>` 表示解压后的绝对路径;该目录应直接包含 `.agents/plugins/marketplace.json`。
  39. ```bash
  40. codex plugin marketplace add "<RELEASE_DIR>"
  41. codex plugin add ambient-project-layer@ambient
  42. codex plugin list
  43. ```
  44. Codex 官方将插件定义为可安装的技能、MCP Server 和可选 UI 组合;本地开发或独立分发的插件通过 local marketplace 安装。可参考 [Build plugins](https://learn.chatgpt.com/docs/build-plugins)。
  45. 安装后,打开 Codex 的 Hook 管理界面,逐一复核并信任当前版本的以下 Hook:
  46. - `SessionStart`
  47. - `UserPromptSubmit`
  48. - `PostToolUse`
  49. - `Stop`
  50. - `SessionEnd`
  51. 插件显示 `enabled` 不等于 Hook 已获得信任。安装或升级后如果 Hook 显示 `modified`,需要重新信任。
  52. ### 3. 配置 Plane 连接
  53. 正式插件不读取仓库或项目目录中的 `.env`。Plane 配置保存在用户级 `~/.codex/config.toml` 中,并由 Codex 启动 `ambient-project` MCP Server 时注入。
  54. 先新建一次 Codex task,让 Hook 创建插件数据目录。随后把 MCP 的 `AMBIENT_DB_PATH` 指向同一个 `PLUGIN_DATA/ambient.sqlite`:
  55. - macOS/Linux:`$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite`
  56. - Windows:`%USERPROFILE%\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite`
  57. macOS/Linux 示例:
  58. ```bash
  59. codex mcp add ambient-project \
  60. --env "AMBIENT_DB_PATH=$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite" \
  61. --env "PLANE_MODE=sdk" \
  62. --env "PLANE_TYPE_MODE=default" \
  63. --env "PLANE_BASE_URL=https://api.plane.so" \
  64. --env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" \
  65. --env "PLANE_API_KEY=replace-in-config-toml" \
  66. -- "<RELEASE_DIR>/plugins/ambient-project-layer/runtime/bin/ambient-node" \
  67. "<RELEASE_DIR>/plugins/ambient-project-layer/runtime/mcp/index.js"
  68. ```
  69. Windows PowerShell 示例:
  70. ```powershell
  71. codex mcp add ambient-project `
  72. --env "AMBIENT_DB_PATH=$env:USERPROFILE\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite" `
  73. --env "PLANE_MODE=sdk" `
  74. --env "PLANE_TYPE_MODE=default" `
  75. --env "PLANE_BASE_URL=https://api.plane.so" `
  76. --env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" `
  77. --env "PLANE_API_KEY=replace-in-config-toml" `
  78. -- "<RELEASE_DIR>\plugins\ambient-project-layer\runtime\bin\ambient-node.cmd" `
  79. "<RELEASE_DIR>\plugins\ambient-project-layer\runtime\mcp\index.js"
  80. ```
  81. 然后编辑 `~/.codex/config.toml`,仅在 `[mcp_servers.ambient-project.env]` 中把占位值替换为真实 Workspace slug 和 API Key。不要把真实 Key 放进上面的命令、仓库、Issue、日志或截图中,以免进入 shell history 或公开记录。
  82. `PLANE_TYPE_MODE` 控制工作项分类策略:
  83. - `default`(默认,适合 Plane Free):不访问付费的 Work Item Types 目录,创建时使用 Plane 默认类型,并把语义分类写入标题前缀,例如 `[Bug]-登录失败`、`[Decision]-采用 SQLite`。
  84. - `custom`(适合 Plane Pro / Business):为 Task、Bug、Decision、Idea、Risk、Milestone 解析或创建对应的自定义 Work Item Type。类型目录只在创建工作项且映射缺失时读取,普通刷新、计数和状态更新不会访问它。
  85. 修改 `PLANE_TYPE_MODE` 后必须完全重启 Codex。不同模式不会自动重写已有工作项。
  86. 升级到 v0.1.4 后,后台同步 Worker 会为每个终态失败批次提供一次自动恢复机会,包括升级前遗留的历史失败。多个 MCP Worker 通过 SQLite 共享同一节流队列:Plane 请求默认间隔 2 秒,自动恢复批次至少间隔 10 秒;遇到 429 时按服务端重置时间暂停全局队列,限流等待不消耗业务重试次数。恢复仍失败的批次会继续保持终态;之后可在 Panel 中人工 Retry、Correct 或 Dead-letter。
  87. 自托管 Plane 用户还需要把 `PLANE_BASE_URL` 换成实例的 API Base URL。
  88. 在本机检查 MCP 配置:
  89. ```bash
  90. codex mcp get ambient-project
  91. ```
  92. 该命令的输出可能包含 Plane API Key。不要把输出复制到 Issue、日志、聊天或截图中;对外排查问题时只提供已经移除凭据的内容。
  93. 完成后完全退出并重新启动 Codex,再新建一个 task。已经运行的 MCP 进程不会自动读取修改后的配置。
  94. ## 第一次使用
  95. 1. 在一个真实项目目录中新建 Codex task。
  96. 2. Ambient Project Layer 会列出当前 Plane Workspace 中的项目并询问绑定目标。
  97. 3. 明确选择一个项目;插件不会根据目录名或 Git remote 自动猜测。
  98. 4. 继续正常使用 Codex。发生有意义的项目变化时,事件会先进入本地 Outbox,再同步到 Plane。
  99. 5. 对 Codex 说“打开项目面板”,即可查看相关工作项和同步状态。
  100. 如果暂时不想选择,可以回复“稍后再说”;本次 task 不会重复询问。如果明确要求某个目录以后不再询问,插件会只在本地保存这一偏好,之后也可以要求恢复绑定。
  101. Ambient Plane 绑定只使用宿主工具 `mcp__ambient_project__list_projects` 的本轮真实返回;用户明确请求 Codex Projects 时,`codex_app__list_projects` 仍可正常使用,但不能作为 Plane 绑定证据。绑定提示中的每个 bullet 只接受精确的 `identifier | name` 成对格式(允许字段分别使用 Markdown 粗体、下划线粗体或行内代码),不会接受前后缀、额外字段、`path`、`projectKind`、`hostId` 或本地项目名。
  102. ## 数据、权限与隐私
  103. Ambient Project Layer 的数据边界如下:
  104. | 数据 | 保存位置 | 说明 |
  105. | --- | --- | --- |
  106. | 工作项和项目状态 | Plane | 用户可见项目数据的最终来源 |
  107. | 项目绑定、Outbox、精简缓存和 Hook 审计 | 本地 SQLite | 默认位于插件的 `PLUGIN_DATA` 目录 |
  108. | Plane API Key | Codex 用户级配置与 MCP 进程内存 | 不写入 SQLite、Panel 或 Hook 输出 |
  109. | Panel 临时令牌 | 当前 MCP 进程内存 | 每次进程启动重新生成 |
  110. 插件不会把完整 Codex transcript、源码、终端输出、附件或 API Key 保存到本地数据库,也不会把 Plane API Key 发送到浏览器 Panel。运行时对外只需要访问你配置的 Plane API。
  111. 插件需要 Plane 项目读写权限,用于读取项目与工作项、创建捕获到的工作项、写入进展评论和更新状态。它不提供自动删除、跨项目移动或人员分配工具。
  112. ## 升级
  113. 1. 从 Releases 下载同一平台的新版本,用新内容替换原来的稳定 Release 目录。
  114. 2. 从同一个 local marketplace 重新安装插件:
  115. ```bash
  116. codex plugin add ambient-project-layer@ambient
  117. ```
  118. 3. 确认 `ambient-project` MCP 仍指向稳定的 Release 目录和原有 SQLite 文件。
  119. 4. 在 Hook 管理界面重新复核并信任五个 Hook。
  120. 5. 完全退出并重启 Codex,再用新 task 验证绑定、同步和 Panel。
  121. 升级时不要删除或切换已有 SQLite 文件,否则本地绑定、Outbox 和来源引用不会自动迁移到新文件。
  122. ## 卸载
  123. ```bash
  124. codex plugin remove ambient-project-layer@ambient
  125. codex plugin marketplace remove ambient
  126. codex mcp remove ambient-project
  127. ```
  128. 这些命令不会替你删除 Plane 中已经同步的工作项。若确定不再需要本地绑定和 Outbox,可在备份后手动删除对应的 `ambient.sqlite`;保留数据库不会影响 Plane 数据。
  129. ## 常见问题
  130. ### 插件已启用,但新 task 没有项目引导
  131. 先检查五个 Hook 是否已被当前版本信任。若显示未信任或 `modified`,重新信任并新建 task;已错过的 `SessionStart` 不会在旧 task 中补跑。
  132. ### `mcp__ambient_project__list_projects` 返回认证错误或没有项目
  133. 检查 `PLANE_MODE=sdk`、Base URL、Workspace slug、API Key 以及 Token 对目标 Workspace 的权限。修改配置后必须完全重启 Codex。
  134. ### MCP 工具正常,但 Panel 暂时不可用
  135. 重新调用“打开项目面板”。MCP 进程重启后,旧 Panel 的临时会话会失效;新调用会创建新的 Panel 会话。
  136. ### 工作项显示“待同步”
  137. 本地事件已经落盘,但 Plane 同步失败。检查网络、API Key 和 Plane 服务状态;恢复后 Outbox 会继续处理,不要通过删除 SQLite 来“重试”。
  138. ### 项目根目录为什么没有 `.env`?
  139. 正式插件使用 `~/.codex/config.toml`,不需要项目级 `.env`。只有从源码运行独立开发入口时才复制 `.env.example` 为 `.env`。
  140. ### 它会上传我的代码或完整对话吗?
  141. 不会。插件只记录经过归纳的项目事件、短来源摘录和同步所需元数据;不保存完整 transcript、源码或终端输出。
  142. ## 从源码构建
  143. 开发环境需要 Node.js 22、Corepack 和 Git。
  144. ```bash
  145. git clone https://github.com/Bene-2020/plane-codex-mcp.git
  146. cd plane-codex-mcp
  147. corepack enable pnpm
  148. pnpm install --frozen-lockfile
  149. cp .env.example .env
  150. pnpm test
  151. pnpm lint
  152. pnpm build
  153. pnpm validate:plugin
  154. pnpm smoke:plugin
  155. ```
  156. `.env.example` 默认使用隔离的 `PLANE_MODE=fake`,适合本地测试。连接真实 Plane 时,请只在本地 `.env` 中填写凭据,不要提交 `.env`。
  157. 构建全部五个平台的插件目录:
  158. ```bash
  159. pnpm run build:packages
  160. pnpm run build:apps
  161. pnpm package:plugin -- --all
  162. node scripts/validate-plugin-runtime.mjs dist/plugins/ambient-project-layer --all
  163. ```
  164. 产物位于 `dist/plugins/ambient-project-layer/<target>/`。当前机器会真实执行本机架构的 sidecar;其他平台只做结构验证,最终 Release 还应在对应平台的 CI Runner 上完成原生 smoke test。
  165. ## 参与项目
  166. - 提交代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
  167. - 安全问题请按 [SECURITY.md](SECURITY.md) 私下报告,不要公开提交含漏洞细节的 Issue。
  168. - 版本变化记录在 [CHANGELOG.md](CHANGELOG.md)。
  169. - 第三方组件许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
  170. ## 许可证
  171. Copyright © 2026 Wenyan Wei。
  172. 本项目使用 [MIT License](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.