grok-plugin-codex

Chinese | English

A plugin that uses Grok directly in Codex.
You still talk to Codex. Reviews, hard bug fixes, proposals, design docs, PR babysitting, docs / images / videos — hand those to your local Grok Build.

Not an official xAI / OpenAI product. Current version 0.6.0. Apache-2.0. Derived from stdevMac/grok-in-codex.

What this is

Codex stays the foreman: you talk to it, it breaks down tasks and tracks progress.
This repo is just a very thin MCP plugin — it doesn't replace Codex, and it doesn't embed the Grok model into Codex. It calls the grok CLI you already have installed locally.

Good for: adding a second capable agent inside Codex; getting a structured review before merging; following a "proposal → design → implementation" flow; or using Grok's image / video / document capabilities (which Codex doesn't have).
Not needed for: one-line fixes, renames, or chit-chat that never touches the repo.

Related MCP server: Grok-in-Codex

What it can do

Don't cram bigger product work into one giant rescue:

Artifacts land in the project directory (gitignore recommended): .grok-plans/ .grok-designs/ .grok-reviews/ .grok-docs/ .grok-media/ .grok-workflows/.

Environment

• Node.js 18.18+

• Grok Build CLI (grok) on PATH, commonly at ~/.grok/bin/grok

• grok login

• Grok Build ≥ 1.0.5 recommended (0.2.118 still starts; specific flags are gated by capability detection)

• gh only needed if you want to post comments on PRs

This plugin doesn't ship a model and won't log you into Grok for you.

Installation

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

Open a new Codex session for the MCP tools to load. Then:

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

Or have Codex call grok_setup.

Codex may launch the plugin from its install cache. Pass the real project path as cwd on every tool call so tasks and artifacts land in that repo:

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

Getting started

Just say it in Codex:

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

MCP example:

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"

Tool overview

Control parameters for long tasks: sandbox (workspace, read-only, strict, devbox, off; the old alias workspace-write normalizes to workspace), planMode / permissionMode, agent, noSubagents, memory / noMemory, allow / deny, disableWebSearch, forkSession, maxTurns.

Aligned with Grok CLI 1.0.x: if the CLI has no --check / --best-of-n, they aren't force-passed. check=true is written into the prompt. Write tasks that only read for many turns without writing files are stopped on execution drift.

Usage notes

Rescue — writable by default. readOnly=true for troubleshooting only. worktree=true for safer changes.

Plan / design / execute — artifacts go to .grok-plans/ and .grok-designs/. latest=true picks the newest design. dryRun=true is read-only.

Review — never applies patches. With postPending=true on a PR, it only posts PENDING GitHub comments when it finds something.

Media — files are copied into .grok-media/ to stay within the project path contract.

Jobs — background=true returns a job id. Multiple Grok tasks can run at once. Track them with grok_status / grok_result / grok_cancel.

CLI posture — uses a denylist (--disallowed-tools) rather than an allowlist. Media, dry-run / validate-only, and babysit list are read-only (no yolo). Reviews default to --sandbox read-only and don't strip shell tools (Grok 1.0.x needs them to produce task results).

Environment variables

Default state directory: ~/.grok/codex-plugin/state/. Not shared with the Claude plugin state.

Task control

• No global single-task lock. Prefer background=true for long tasks.

• Status follows the text stream and thought stream; still shows running on whitespace-only tokens. Status also records the most recent tool and whether a write tool has run.

• Plan results prefer harvesting plan.md. Completed tasks store config, usage, artifacts (v3).

• Reaper: pid dead and result.json complete → completed; pid dead but result truncated → failed (never stuck on running forever).

• Background result.json is written atomically (tmp + rename).

• PR post-pending also runs when background jobs finish; empty / oversized diffs fail closed, findings go to .grok-reviews/.

Development

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

Version numbers in package.json, plugins/grok/.codex-plugin/plugin.json, and .agents/plugins/marketplace.json must match.

License

Apache-2.0. See LICENSE and NOTICE.

This project is derived from stdevMac's stdevMac/grok-in-codex.