grok-plugin-codex — Grok inside Codex

At a glance

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

Problem

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.

Solution

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.

Impact

Public Codex plugin · 0.2 with a typed MCP contract and explicit workspace roots · Grok review and rescue inside Codex · bounded second-agent workflow

My contribution

Codex plugin exposing Grok MCP tools: check, models, run, continue, 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 0.2 typed MCP contract keeps session listing and export as explicit evidence surfaces, while deliberately still avoiding any claim of a Codex-to-Grok transfer path
0.2 release changes: breaking typed MCP contract, explicit workspace roots, restart-safe background workers, atomic job lifecycle, private prompt staging over fd3, and stricter path, symlink, env, session, and cancel boundaries

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: prompts do not receive Codex hidden context, tool output, secrets, or Grok auth tokens; private runtime path requests are rejected unless explicitly allowed
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 point is not that one more model can speak. The point is a safer workflow: ask for a second opinion, keep the main assistant in charge, and verify every claim before changing code.

Bounded Grok collaboration

grok_check confirms the local Grok CLI first. grok_run handles bounded tasks, while grok_review, grok_rescue, and grok_adversarial_review keep second-agent work framed as findings or diagnosis rather than uncontrolled ownership.

Background jobs are deliberately conservative: partial logs are treated as process evidence only, and a result is trusted only after the plugin sees both successful completion and final text.