grok-plugin-codex — Grok inside Codex

Project overview

Role Sole builder — Codex plugin packaging, MCP tool surface, Grok CLI orchestration, privacy boundary, background jobs, tests

Scenario

Grok can be useful as another engineering perspective, but switching tools manually makes scope, session history, and review ownership hard to control. The goal was to let Codex ask Grok for help while Codex still owns files, tests, git, and final judgment.

Product strategy

I exposed Grok CLI through Codex MCP tools with capability checks, bounded run/review/rescue wrappers, session listing/export, background status/result/cancel controls, and explicit safeguards around hidden context and private runtime paths.

Outcome and current stage

Public Codex plugin · 0.3.0, reporting contract version 3 over a typed MCP surface with explicit workspace roots · Grok review and rescue inside Codex · bounded second-agent workflow

My contribution

Codex plugin exposing thirteen Grok MCP tools: check, models, run, continue, finalize, rescue, review, adversarial review, sessions, export, status, result, and cancel
Bounded review and rescue helpers, so Grok can act as a second pair of eyes without becoming the owner of the change
Background Grok job management with status/result/cancel, so long-running reviews can be inspected before their output is trusted
The typed MCP contract makes session listing and export inspectable; the current collaboration path ends at those explicit evidence surfaces
0.3.0 built on that baseline: background dispatch became the default, grok_finalize joined the tool surface, every non-complete result carries a machine-readable recovery handle, and prompt staging moved off /dev/fd/3 — Linux resolved it through /proc/self/fd and could hand Grok an already-consumed, empty stream, so the prompt now goes through a 0600 FIFO in a private directory that is unlinked before Grok reads it

Technical evidence

Bundled stdio MCP server written in TypeScript, packaged as a Codex plugin with a plugin manifest, skill, MCP config, privacy policy, terms, and security policy
Grok CLI discovery, version check, optional model probing, foreground JSON runs, streaming background runs, job ledger, and conservative result-completion detection
Privacy boundary by design: Grok receives the task prompt and approved files; Codex hidden context, tool output, secrets, and auth tokens stay within their source, while private runtime paths require explicit permission
Verification scripts covering build, typecheck, unit tests, MCP smoke checks, documentation drift checks, and optional authenticated live Grok smoke

Why it exists

The practical use case is controlled collaboration. Codex may be deep in a repo and need another model to review a diff, diagnose a failure, or challenge an assumption. The plugin gives Grok a clear packet of work while keeping Codex responsible for scope, verification, and shipping decisions.

For non-technical readers, the practical value is a safer second-opinion workflow: Grok contributes another engineering perspective, Codex remains in charge, and each finding is checked before code changes.

Bounded Grok collaboration

grok_check confirms the local Grok CLI first. grok_run handles bounded tasks; grok_review, grok_rescue, and grok_adversarial_review return focused findings or diagnoses for Codex to verify.

A background result becomes available after the job completes successfully and returns final text; partial logs remain visible as progress evidence.