Grok in Codex

Use Grok from inside Codex for code reviews, delegated coding tasks, background investigations, image generation, and video generation.

Codex stays the orchestrator. This plugin exposes a small MCP server that calls the local Grok CLI through a shared companion runtime.

Using Claude Code instead? Use the sibling plugin: grok-in-claude.

What You Get

Codex tool	Purpose
grok_setup	Check Grok CLI and authentication
grok_rescue	Delegate investigation or fixes; write-capable by default
grok_review	Structured read-only review of a tree, branch, or PR
grok_adversarial_review	Challenge design, tradeoffs, and assumptions
grok_image	Generate or edit images into .grok-media/image/
grok_video	Generate short videos into .grok-media/video/
grok_status	Show active and recent Grok jobs
grok_result	Read final stored output for a job
grok_cancel	Cancel a background job
grok_transfer	Build context-transfer guidance for Grok

Skills included:

• grok-routing for deciding when to delegate
• grok-cli-runtime for companion runtime rules
• grok-prompting for strong rescue prompts
• grok-brand-media for image/video recipes

Requirements

• Node.js 18.18 or later
• Grok CLI on your PATH
• Grok authentication via grok login
• GitHub CLI (gh) only for grok_review with pull requests

Typical Grok CLI locations:

~/.grok/bin/grok
~/.local/bin/grok

Install

From GitHub:

codex plugin marketplace add stdevMac/grok-in-codex
codex plugin add grok@grok-in-codex

Then start a new Codex thread so the plugin skills and MCP tools are loaded.

Install Locally

From this repository:

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

Then start a new Codex thread so the plugin skills and MCP tools are loaded.

Run setup:

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

Or ask Codex to call grok_setup.

Quick Start

Ask Codex naturally:

Ask Grok to review this branch against main.
Use Grok to investigate why the auth tests are flaky.
Start a background Grok rescue job for the retry redesign.
Generate a 16:9 launch banner with Grok.
Show Grok job status.

Direct MCP tool examples:

grok_review base=main focus="auth, data loss, and race conditions"
grok_rescue prompt="investigate why npm test is failing" background=true
grok_status
grok_result jobId="task-abc123"
grok_image aspect="16:9" prompt="Dark developer-tool launch banner for Grok in Codex"
grok_video image="./.grok-media/image/hero.png" duration="6" prompt="gentle camera push-in"

Usage Notes

Rescue

grok_rescue is write-capable by default. Use readOnly: true for diagnosis only, and worktree: true for risky edits.

Useful options:

• background: true for long-running work
• model: "fast" for quick passes
• model: "deep", effort: "high" for harder problems
• worktree: true to isolate edits
• check: true to ask Grok to verify before returning
• bestOfN: 3 to run parallel attempts and select the best
• resume: true, resumeSession, or fresh for session control

Review

grok_review is read-only and returns structured findings when parsing succeeds.

Examples:

grok_review
grok_review base=main
grok_review pr=123 focus="security and data-loss risks"
grok_adversarial_review focus="challenge this caching design"

Media

Images and videos are copied into project-local output folders:

.grok-media/image/
.grok-media/video/

Examples:

grok_image aspect="1:1" prompt="Simple geometric app icon, no text"
grok_image edit="./assets/logo.png" prompt="Make it monochrome with tighter padding"
grok_video refs=["shot1.png","shot2.png"] aspect="16:9" duration="6" prompt="product launch cutdown"

Video resolution is limited by the Grok model tier, commonly 480p.

Job Control

Background jobs can run concurrently. Use explicit job ids when more than one job is active.

grok_status
grok_status jobId="task-abc123"
grok_result jobId="task-abc123"
grok_cancel jobId="task-abc123"

How It Works

Codex
  -> Grok MCP tool
    -> node plugins/grok/mcp/server.mjs
      -> node plugins/grok/scripts/grok-companion.mjs <command>
        -> grok -p ... --output-format json|streaming-json

Job metadata is stored under:

~/.grok/codex-plugin/state/<repo-slug-hash>/

Set CODEX_PLUGIN_DATA to override the plugin data directory when running in custom environments.

Security

• grok_rescue defaults to full tool auto-approval through Grok CLI write mode.
• Use readOnly: true when you only want analysis.
• Use worktree: true for higher-risk changes.
• Reviews are read-only.
• Media commands write under .grok-media/ and Grok session folders.

Development

npm test
node plugins/grok/scripts/grok-companion.mjs setup
node plugins/grok/scripts/grok-companion.mjs review --base main
node plugins/grok/scripts/grok-companion.mjs task --worktree --check "fix the failing test"
node plugins/grok/mcp/server.mjs