Skip to content

maozhen520/codex-plugin-cursor

BranchesTags

Repository files navigation

Cursor Companion for Codex

在 Codex 里调用本机 Cursor Agent CLI，完成只读审查、任务委托、后台任务管理，以及把当前 Codex 会话交给可恢复的 Cursor 聊天继续。

这是独立集成，不是 OpenAI 或 Cursor 的官方产品。

反向方向（在 Cursor 里调用 Codex）见姊妹项目本地路径：~/Documents/cursor-plugin-codex（Codex Companion for Cursor）。

你能得到什么

Skill 用途
$cursor-setup 检查 Node、Cursor Agent CLI、登录状态与 review-gate
$cursor-review 对工作区 / 分支变更做只读审查
$cursor-adversarial-review 可聚焦的对抗性只读审查（结构化结论）
$cursor-task 把调查 / 实现任务交给 Cursor（可选可写、后台、续跑）
$cursor-transfer 把当前 Codex 会话导入可 agent resume 的 Cursor 聊天
$cursor-status 查看本仓库后台任务
$cursor-result 读取已完成任务的完整结果
$cursor-cancel 取消进行中的后台任务

环境要求

  1. Codex（CLI 或桌面端，需支持 Plugins）
  2. Node.js 18.18+
  3. Git（审查流程会读仓库状态）
  4. Cursor Agent CLI 已安装并登录

安装 Cursor Agent CLI：

# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash

# 确认
agent --version
agent login

确保 ~/.local/bin 在 PATH 中（zsh 示例）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

安装插件

下面任选一种方式。推荐本地开发用 方式 A；分享给别人用 Git 仓库用 方式 B。

方式 A：本地目录 marketplace（推荐）

  1. 克隆或放置本仓库到任意目录，例如：
git clone <this-repo-url> ~/codex-plugin-cursor
cd ~/codex-plugin-cursor
  1. 把该仓库注册为 Codex marketplace，并安装插件：
codex plugin marketplace add "$(pwd)"
codex plugin add cursor-companion@cursor-companion-dev
  1. 确认已安装并启用：
codex plugin list | rg cursor-companion

期望看到类似：

cursor-companion@cursor-companion-dev  installed, enabled  0.1.0  ...
  1. 重启 Codex（CLI 新开会话，或重启 ChatGPT / Codex 桌面端），然后在任意 Git 仓库中运行：
$cursor-setup

状态应为 ready，且 Cursor CLI / auth 检查通过。

说明：仓库根目录的 .agents/plugins/marketplace.json 把插件源指向 ./（本仓库根）。Codex 会把插件缓存到
~/.codex/plugins/cache/cursor-companion-dev/cursor-companion/<version>/。

方式 B：从 Git 远程 marketplace 安装

若仓库已推送到 GitHub 等远程，且保留 .agents/plugins/marketplace.json：

codex plugin marketplace add owner/repo
# 或
codex plugin marketplace add https://github.com/owner/repo.git

codex plugin add cursor-companion@cursor-companion-dev

marketplace 名称以仓库内 .agents/plugins/marketplace.json 的 name 字段为准（当前为 cursor-companion-dev）。

方式 C：开发时强制同步缓存副本

修改 skills / scripts 后，若桌面端仍读旧缓存，可重新安装或同步：

codex plugin remove cursor-companion@cursor-companion-dev
codex plugin add cursor-companion@cursor-companion-dev

# 或在开发机上手动同步到缓存目录（版本号以 list 输出为准）
rsync -a --delete \
  --exclude '.git/' --exclude 'node_modules/' --exclude 'docs/e2e-logs/' --exclude 'docs/e2e-fixture/.git/' \
  "$(pwd)/" \
  "$HOME/.codex/plugins/cache/cursor-companion-dev/cursor-companion/0.1.0/"

卸载

codex plugin remove cursor-companion@cursor-companion-dev
# 可选：移除 marketplace
codex plugin marketplace remove cursor-companion-dev

可选清理本插件产生的任务状态（不会删除 ~/.codex 登录信息）：

rm -rf ~/.codex/cursor-companion

快速开始

  1. 安装 Cursor Agent CLI 并 agent login
  2. 按上文安装本插件
  3. 进入某个 Git 仓库，在 Codex 中执行：
$cursor-setup
$cursor-review --scope working-tree --wait
  1. 委托实现任务：
$cursor-task --write 用最小改动修复刚才 review 提到的问题并跑相关测试
  1. 长时间任务可后台跑，再用 status / result / cancel：
$cursor-task --background --write 重构解析器并补测试
$cursor-status
$cursor-result
$cursor-cancel <job-id>

使用说明

$cursor-setup

检查 Node、Cursor CLI、认证、会话运行时，以及可选的 stop review-gate。

$cursor-setup
$cursor-setup --enable-review-gate
$cursor-setup --disable-review-gate

$cursor-review（只读）

对照工作区或分支做审查。不要用它改代码。

$cursor-review --wait --scope working-tree
$cursor-review --wait --scope branch --base main
$cursor-review --background --scope working-tree

常用参数：

  • --wait / --background：前台等待或后台任务
  • --base <ref>：分支审查基线
  • --scope auto|working-tree|branch

自定义关注点请用 $cursor-adversarial-review。

$cursor-adversarial-review（只读）

可带聚焦文本的对抗性审查，输出结构化 verdict / findings。

$cursor-adversarial-review --wait --scope working-tree
$cursor-adversarial-review --base main focus on auth and retry behavior

$cursor-task

把任务交给 Cursor Agent。默认只读；需要改文件时加 --write。

$cursor-task --write implement the approved cache invalidation change
$cursor-task --background --write refactor the parser and run its tests
$cursor-task --resume-last follow up by addressing the remaining failure
$cursor-task --fresh investigate this without changing files
$cursor-task --model <model-name> --write ...

常用参数：

  • --write：允许写工作区（CLI 侧会带 --force）
  • --wait / --background
  • --resume / --resume-last：续跑本会话最近完成的任务线程
  • --fresh：强制新 Cursor chat
  • --model <name>：指定 Cursor 模型

$cursor-transfer

把 Codex 会话导入 Cursor，便于在 Cursor CLI 继续。

$cursor-transfer
$cursor-transfer --source /absolute/path/to/rollout.jsonl

解析顺序：

  1. 显式 --source
  2. 环境变量 CODEX_CURSOR_SESSION_PATH
  3. 用 CODEX_CURSOR_SESSION_ID 在 ~/.codex/sessions/ 下查找

成功后会打印：

agent resume <chat-id>

$cursor-status / $cursor-result / $cursor-cancel

$cursor-status
$cursor-status task-abc123 --wait --timeout-ms 240000
$cursor-result task-abc123
$cursor-cancel task-abc123

后台任务状态默认写在：

~/.codex/cursor-companion/state/

测试或托管环境可用 CODEX_CURSOR_DATA_DIR 覆盖。

典型工作流

发版前审查

$cursor-review --wait --scope branch --base main
$cursor-adversarial-review --wait --base main focus on data loss and rollback

把难题交给 Cursor

$cursor-task --write 调查并修复 CI 里 flaky 的集成测试

长任务 + 交接

$cursor-task --background --write 完成迁移脚本并补文档
$cursor-status
$cursor-transfer
# 然后在另一个终端
agent resume <chat-id>

开发与验证

cd /path/to/codex-plugin-cursor
npm run check          # validate + tests
npm test               # node --test
npm run validate       # 校验 plugin.json 与 skills frontmatter

端到端真实截图与记录：

仓库结构要点：

.codex-plugin/plugin.json          # Codex 插件清单
.agents/plugins/marketplace.json   # 本地 marketplace 入口
skills/cursor-*/SKILL.md           # 用户可调用的 $cursor-* skills
scripts/cursor-companion.mjs       # 共享 Node 运行时
scripts/lib/                       # Cursor CLI / job / git / transfer

隐私与数据

  • 只调用本机 agent 可执行文件，使用你已有的 Cursor 登录态。
  • 任务元数据默认在 ~/.codex/cursor-companion/state/。
  • 不会把完整 transcript 正文写进操作日志。
  • Transfer 的示例 fixture 使用合成 JSONL，文档截图流程不依赖真实私人会话。

故障排除

$cursor-setup 显示 Cursor 不可用

agent --version
# 若找不到命令：重新安装并检查 PATH
curl https://cursor.com/install -fsS | bash

认证失败

agent login
agent status --format json

Skill 报找不到 PLUGIN_ROOT / cursor-companion.mjs

重新安装插件并重启 Codex：

codex plugin remove cursor-companion@cursor-companion-dev
codex plugin add cursor-companion@cursor-companion-dev

Transfer 找不到会话

$cursor-transfer --source /absolute/path/to/your-rollout.jsonl

路径一般在 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl。

后台任务卡住

$cursor-status
$cursor-cancel <job-id>

与 Cursor 侧姊妹插件配对

方向 项目 在哪用
Codex → Cursor 本仓库 codex-plugin-cursor Codex 里 $cursor-*
Cursor → Codex cursor-plugin-codex Cursor 里 /codex-*

两边可互相 review、委托任务，并用 transfer 把会话交给对方继续。

License

Apache-2.0。运行时模式参考自 openai/codex-plugin-cc。详见 LICENSE 与 NOTICE。

About

Use the local Cursor Agent CLI from Codex for reviews, delegated tasks, and session transfer.

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages