grok-plugin-codex

中文 | English

在 Codex 里直接用 Grok 的插件。
人还是跟 Codex 说话。评审、修硬 bug、出方案、写设计、盯 PR、出文档 / 图 / 视频，交给本机 Grok Build。

非 xAI / OpenAI 官方产品。当前版本 0.6.0。Apache-2.0。衍生自 stdevMac/grok-in-codex。

这是什么

Codex 继续当工头：你跟它说话，它拆任务、盯进度。
本仓库只是一层很薄的 MCP 插件，不会替换 Codex，也不是把 Grok 模型嵌进 Codex。它调用的是你本机已经装好的 grok CLI。

适合： 想在 Codex 里再加一个能干活的第二智能体；合并前要一份结构化评审；走「方案 → 设计 → 落地」；或者要用 Grok 的图 / 视频 / 文档能力（Codex 本身没有这些）。
不必用： 一行就能改完的修复、重命名、或者根本不碰仓库的闲聊。

Related MCP server: Grok-in-Codex

能做什么

更大的产品工作不要塞进一次巨型 rescue：

产物会落到项目目录里（建议 gitignore）：.grok-plans/ .grok-designs/ .grok-reviews/ .grok-docs/ .grok-media/ .grok-workflows/。

环境

• Node.js 18.18+

• Grok Build CLI（grok）在 PATH 上，常见路径是 ~/.grok/bin/grok

• grok login

• 建议 Grok Build ≥ 1.0.5（0.2.118 仍能启动；具体 flag 按能力探测开关）

• 只有要往 PR 上发评论时才需要 gh

这个插件不自带模型，也不会替你登录 Grok。

安装

codex plugin marketplace add /path/to/grok-plugin-codex/.agents/plugins
codex plugin add grok@grok-plugin-codex

开一个新的 Codex 会话，MCP 工具才会加载。然后：

node plugins/grok/scripts/grok-companion.mjs setup

或者让 Codex 调用 grok_setup。

Codex 可能会从安装缓存启动插件。每次调用工具时把真实项目路径传给 cwd，任务和产物才会落在那个仓库：

grok_review cwd="/path/to/project" base=main
grok_status cwd="/path/to/project" json=true

上手

在 Codex 里直接说：

让 Grok 对照 main 评审这个分支。
用 Grok 规划一次鉴权重写。
让 Grok 出一份设计文档，然后 dry-run 执行最新方案。
给重试重构开一个后台 Grok rescue。
用 Grok 生成一张 16:9 发布 banner。
看看 Grok 任务状态。

MCP 示例：

grok_plan prompt="plan the auth rewrite" background=true
grok_design prompt="design multi-tenant billing" background=true
grok_execute_plan latest=true dryRun=true
grok_workflow action=list
grok_review base=main focus="auth, data loss, and race conditions"
grok_rescue prompt="investigate why npm test is failing" background=true
grok_babysit action=list
grok_document type=pdf prompt="one-pager for the launch"
grok_image aspect="16:9" prompt="Dark developer-tool launch banner"
grok_video image="./.grok-media/image/hero.png" duration="6" prompt="gentle camera push-in"
grok_status
grok_result jobId="plan-abc123"

工具一览

长任务的控制参数：sandbox（workspace、read-only、strict、devbox、off；旧别名 workspace-write 会归一成 workspace），planMode / permissionMode，agent，noSubagents，memory / noMemory，allow / deny，disableWebSearch，forkSession，maxTurns。

对齐 Grok CLI 1.0.x：CLI 没有 --check / --best-of-n 时不会硬传。check=true 会写进 prompt。只想/只读很多轮却不写文件的写任务，会按执行漂移停掉。

用法要点

Rescue — 默认可写。readOnly=true 只排查。worktree=true 改得更安全。

Plan / design / execute — 产物收到 .grok-plans/ 和 .grok-designs/。latest=true 选最新设计。dryRun=true 是只读。

Review — 永远不打补丁。postPending=true 加上 PR 后，有发现才会发 PENDING GitHub 评论。

Media — 文件会拷进 .grok-media/，保证还在项目路径契约里。

Jobs — background=true 会返回 job id。多个 Grok 任务可以同时跑。用 grok_status / grok_result / grok_cancel 跟踪。

CLI 姿态 — 用 denylist（--disallowed-tools）而不是 allowlist。媒体、dry-run / validate-only、babysit list 都是只读（不加 yolo）。评审默认 --sandbox read-only，不会摘掉 shell 工具（Grok 1.0.x 产出任务结果需要它）。

环境变量

默认状态目录：~/.grok/codex-plugin/state/。不和 Claude 插件状态共用。

任务控制

• 没有全局单任务锁。长任务优先 background=true。

• 状态会跟文本流和 thought 流；只有空白 token 时仍显示 running。状态还会记录最近一次工具、以及有没有跑过写工具。

• Plan 结果优先收割 plan.md。完成的任务会存 config、usage、artifacts（v3）。

• Reaper：pid 已死且 result.json 完整 → completed；pid 已死但结果被截断 → failed（不会永远卡在 running）。

• 后台 result.json 是原子写入（tmp + rename）。

• PR post-pending 在后台完成时也会跑；空 diff / 过大 diff 会 fail closed，发现写到 .grok-reviews/。

开发

npm test
node plugins/grok/scripts/grok-companion.mjs setup --json
node plugins/grok/mcp/server.mjs   # stdio NDJSON MCP server

package.json、plugins/grok/.codex-plugin/plugin.json、.agents/plugins/marketplace.json 里的版本号必须一致。

许可

Apache-2.0。见 LICENSE 和 NOTICE。

本项目衍生自 stdevMac 的 stdevMac/grok-in-codex。