grok plugin for Claude Code

Use the local grok CLI from inside Claude Code for code reviews or to delegate tasks to grok.

This plugin mirrors the command surface of the Codex plugin (openai/codex-plugin-cc) but is built on grok's native headless features, so it stays thin: no background broker, no app-server runtime, just grok plus a small companion script that tracks jobs across turns.

What You Get

• /grok:review for a read-only implementation review of your local git state
• /grok:adversarial-review for a steerable challenge review with optional focus text
• /grok:rescue to hand grok a write-capable fix or an investigation
• /grok:status, /grok:result, /grok:cancel to manage background jobs
• /grok:setup to check that grok is installed and authenticated

Requirements

• The grok CLI, installed and logged in (grok login). The plugin shells out to your local grok; nothing runs in the cloud on the plugin's behalf.
• Node.js 18.18 or later (the companion script is plain ESM, no dependencies).

Install

Add the marketplace in Claude Code from GitHub:

/plugin marketplace add kwunlokng/grok-plugin-cc

Or from a local checkout:

/plugin marketplace add ~/grok-plugin-cc

Install the plugin:

/plugin install grok@grok-tools

Restart Claude Code so the commands load, then run /grok:setup to confirm grok is ready.

Usage

/grok:review

Read-only review of your current git state. Working tree by default, or a branch diff with --base <ref>.

/grok:review              # asks wait vs background based on size
/grok:review --wait       # run in the foreground
/grok:review --background # run detached, check /grok:status
/grok:review --base main  # review this branch against main

grok returns a structured verdict (approve or needs-attention), a summary, findings with file and line references, severity, confidence, and a concrete fix per finding. The command returns grok's output verbatim and never edits your code.

/grok:adversarial-review

Same target selection as /grok:review, but framed as a challenge to the approach: what assumptions it depends on and where the design fails under stress. Takes optional focus text after the flags.

/grok:adversarial-review --wait
/grok:adversarial-review --base main focus on the retry and idempotency paths

/grok:rescue

Delegate a task to grok. Write-capable by default (grok can edit files), or investigation-only with --read-only.

/grok:rescue fix the failing auth test in src/auth
/grok:rescue --read-only why does the importer drop the last row?
/grok:rescue --resume        # continue the most recent grok rescue in this repo
/grok:rescue --model grok-4  # pin a model

/grok:status

Show active and recent grok jobs for this repository as a compact table. Pass a job id for the full record, or --all for every repository.

/grok:result

Show the stored final output for a finished job. Pass a job id, or omit it for the most recent job in this repository. Includes the grok session id, so you can pull the full transcript with grok export <session>.

/grok:cancel

Cancel a running background job (kills the tracked grok process). Pass a job id, or omit it to cancel the most recent running job in this repository.

/grok:setup

Check that grok is installed and authenticated. If not, it tells you to run grok login.

Typical Flows

Review before shipping

/grok:review --wait

Read the findings, fix what matters, review again.

Hand a problem to grok

/grok:rescue the checkout total is off by a cent on multi-item carts, find and fix it

grok investigates and edits in place; the output comes back verbatim.

Start something long-running

/grok:review --background
# ...keep working...
/grok:status
/grok:result <id>

How It Works

Everything grok can do on its own stays native:

• Reviews call grok -p "<prompt>" --output-format json, with the review schema and the git diff embedded in the prompt. Reviews run with --disallowed-tools Write,Edit,NotebookEdit,Bash, so they cannot modify your code.
• Rescue calls grok -p "<task>" --always-approve for a write-capable run, and --resume continues the most recent rescue session for the repo.
• Each job is assigned a known grok session id (--session-id), so results and transcripts (grok export <session>) are addressable.

The only thing grok cannot do by itself is track jobs across separate Claude Code turns. That is the entire job of plugins/grok/scripts/grok-companion.mjs: a thin wrapper that runs grok, captures its output, and maintains a small job log at ~/.grok/claude-jobs/ (outside any repository, so runtime state is never committed). /grok:status, /grok:result, and /grok:cancel read that log.

Note: grok's --json-schema flag does not hard-constrain output, so the companion embeds the schema in the prompt and extracts and validates the JSON itself (structured output first, then a fenced or bare JSON block from the model's text).

Development

npm test        # node --test over tests/*.test.mjs
npm run selftest # run the companion's built-in job-log + parser checks

To iterate after installing: edit the plugin under plugins/grok/, then claude plugin update grok@grok-tools. Claude Code runs the installed copy in its plugin cache, not this working tree, until you update.

License

MIT. See LICENSE.