grok-skills

Run Grok from Claude Code or Codex (the ChatGPT desktop coding surface) as a second pair of hands: review, reason, implement directly in your tree (default) or in an isolated worktree, verify. Not affiliated with xAI.

Works on whatever repo you point it at. The install location of this package is not the repo under review.

Plugin name: grok. Claude Code and Codex both install the same package; they
invoke skills differently (table below).

Division of labor: Claude Code or Codex = orchestrator. Grok (via this
plugin) = sandboxed second mind - especially grok-engineer-coder for
implementation directly in your tree (default) or in an isolated worktree.
How edits land is mode-aware:
plugin/references/integration-modes.md.

First 5 minutes

1. Install Grok CLI, log in, confirm grok --version works
   (macOS for live modes; Python 3 + Node on PATH). Any working Grok CLI
   build is accepted - there is no exact version lock.

2. Add the marketplace and install the plugin (no manual clone needed):

   # Claude Code (in-session or CLI)
   /plugin marketplace add sfourdrinier/grok-skills
   /plugin install grok@grok-skills
   

   # Codex CLI
   codex plugin marketplace add sfourdrinier/grok-skills
   codex plugin add grok@grok-skills
   

   Full URL https://github.com/sfourdrinier/grok-skills.git works too; GitHub
   shorthand is equivalent. Then /reload-plugins (Claude) or start a new session
   (Codex agents materialize on SessionStart - no manual setup).

3. Optional readiness check (agents already auto-install on SessionStart):

   /grok:setup
   

   For background completion signals (OS toast / webhook when a job finishes
   while you are not watching), enable auto and run live skills in the background
   with the execution-context env set by the skill (see
   execution-context.md):

   /grok:setup --notification-mode auto
   

   Defaults stay off (no toast). Use --notification-mode webhook plus
   --notification-webhook-url <https-url> for SSH/CI/Windows (native toast is
   macOS/Linux desktop only). Full smoke:
   manual-smoke.md.

4. Before promising implementer success on the live tree, record integration
   consent or opt into isolation (canonical matrix:
   integration-modes.md):

   /grok:setup --integration direct
   # or isolation without live land:
   /grok:setup --integration auto
   # or:
   /grok:setup --integration review
   

   First direct landing without setup consent fails closed. /grok:implement
   always forces an isolated worktree + verify-only handoff (never live lands).

5. Try a review or ask the host to use grok-engineer-coder for implementation.

You should see one JSON envelope on stdout with "status": "success" for live
modes. Use /grok:jobs / /grok:result --pretty (Claude) or the equivalent
skill names on Codex for later job output.

Claude Code vs Codex: how you invoke things

Same engine either way: Node companion → hardened Python wrapper → one JSON envelope.

Codex trust honesty: on Codex, plugin hooks (the optional stop-review gate and the SubagentStop handoff nudge) stay dormant until you trust them via /hooks. That is the honest default posture - install alone does not enable those hooks. Skills and SessionStart agent materialization still work without hook trust. SubagentStop is mode-aware: peer never routes through /grok:handoff; code direct (edits already live) differs from worktree/auto handoff paths.

How to use it

Before anything else

You need all of these:

1. macOS for live modes (Seatbelt). Linux/Windows stop with probe-required until a sandbox profile is validated for them.
2. Python 3 and Node.js on your PATH (stdlib only; no pip/npm packages for this tool).
3. Grok CLI installed and logged in (grok --version works). Any working
   Grok CLI is accepted. plugin/wrapper/accepted-version.json is last
   maintainer-validated evidence only (advisory) - not a runtime allowlist.

You do not need a manual clone for normal use. Claude Code and Codex both install from this GitHub repo as a plugin marketplace (they clone it, then copy plugin/ into their install cache).

Claude Code

From a Claude Code session (preferred - install straight from GitHub):

/plugin marketplace add sfourdrinier/grok-skills
/plugin install grok@grok-skills

CLI equivalent:

claude plugin marketplace add sfourdrinier/grok-skills
claude plugin install grok@grok-skills

Other accepted sources: full git URL (https://github.com/sfourdrinier/grok-skills.git), or pin a ref with sfourdrinier/grok-skills@main. Then /reload-plugins (or restart). Type /grok: and confirm autocomplete.

Typical session:

/grok:preflight
/grok:review --target src/my-lib --task "Find correctness bugs and unsafe error handling"
/grok:code --target src/my-lib --base main --task "Fix the off-by-one in the paginator"
/grok:status --run-id <runId from code envelope>
/grok:handoff --run-id <runId>
# Integrate per mode (one-shot code): direct = edits already live; auto =
# companion may apply; review = parent applies after ready. ACP peer is always
# worktree-isolated and lands only at peer-stop (see integration-modes.md).
/grok:verify --worktree /path/to/retained-worktree --task "Confirm the fix builds and tests pass"

Local path is only for hacking on a checkout:

# marketplace from a clone
claude plugin marketplace add /absolute/path/to/grok-skills
claude plugin install grok@grok-skills

# or load the plugin tree without a marketplace
claude --plugin-dir /absolute/path/to/grok-skills/plugin

You do not need GROK_AGENT_WRAPPER for a normal install. The engine lives inside the plugin tree (plugin/wrapper/…), so the install cache still finds it.

Full interactive checklist: plugin/references/manual-smoke.md.

Codex CLI

Preferred - marketplace from GitHub:

codex plugin marketplace add sfourdrinier/grok-skills
# optional pin: codex plugin marketplace add sfourdrinier/grok-skills --ref main
codex plugin add grok@grok-skills
codex plugin list   # expect grok@grok-skills installed, enabled

Also accepted: https://github.com/sfourdrinier/grok-skills.git, SSH URLs, or a local clone path for development.

Skills ship with the plugin. Invoke them the way your Codex build exposes plugin skills (skill picker / $skill style, depending on version). Prefer each skill’s self-locating run.mjs (Skill base directory); custom agents get an absolute agents/run.mjs path on SessionStart - do not invent cache paths by hand.

After install, start a new Codex session (or reload) so SessionStart can write managed grok-*.toml agents (default: ~/.codex/agents/; or <cwd>/.codex/agents/ after setup --codex-agents-scope project). Then spawn grok-engineer-coder / grok-rescue, or run skills the same way you would in Claude. Prefer tasks via --task-file / stdin heredoc so nothing shell-expands. On Codex, plugin hooks remain dormant until trusted via /hooks (stop gate and SubagentStop nudge); agent materialization does not require that trust step.

ChatGPT desktop (Codex)

Same package as the CLI (marketplace name grok-skills, plugin grok).

1. Prefer adding the marketplace from git the same way as Codex CLI
   (sfourdrinier/grok-skills or the HTTPS URL).
2. Open Plugins → Grok Skills marketplace → install grok.
3. Restart / open a new session so SessionStart can install Codex agents.
   Trust hooks only if you enable the optional stop gate (/hooks in CLI).
   Leave the gate off unless you want that. No separate setup skill is required.

If the desktop build only offers “open as project,” open a clone of this repo once
so it discovers .agents/plugins/marketplace.json, then install grok from there.
CLI path is always available: codex plugin marketplace add sfourdrinier/grok-skills
then codex plugin add grok@grok-skills.

Private repo / no public access

If the repository or your fork is private, git install only works for accounts that can clone it. Use a path or SSH remote you already have access to:

claude plugin marketplace add /absolute/path/to/grok-skills
codex plugin marketplace add [email protected]:sfourdrinier/grok-skills.git

What each skill does

Agents (orchestrator host + Grok worker)

• Claude Code: agents ship in the plugin (plugin/agents/). Reload plugins after install.
• Codex: agents auto-install on SessionStart with an absolute
  GROK_AGENT_RUN → agents/run.mjs (Codex cannot register plugin agents
  natively yet - openai/codex#18988).
  Default dest is personal ~/.codex/agents/; setup --codex-agents-scope project
  persists workspace prefs and installs into <cwd>/.codex/agents/ instead
  (SessionStart honors the same prefs; see
  Codex subagents).
  Managed files refresh on plugin upgrade (at most 3 managed *.bak* kept;
  user-owned TOML is never pruned or overwritten unless setup --force-codex-agents).
  If agents are missing after install, open a new session or run optional
  setup --force-codex-agents (hook failures are non-blocking so they never stall
  host startup). Nicknames: Grok Coder / Grok Rescue.
• Codex hooks stay dormant until trusted: the stop-review gate and the
  mode-aware SubagentStop handoff nudge are skipped on Codex until you approve
  them via /hooks (peer never via handoff; code direct vs worktree handoff
  differ). Skills and agent materialization do not depend on that trust step.
• Transparent skills + agents: skills use $SKILL_BASE/run.mjs; Claude/Codex
  agents use agents/run.mjs (self-locating). See
  plugin-root.md.
• Remove managed Codex agents: disable/uninstall the plugin first, then
  setup --remove-codex-agents (or delete managed grok-*.toml under the active
  scope dir).

Run modes (security posture)

Two postures, same skills. This is the security axis (runMode), not how
edits land - both axes use the word "direct"; disambiguate in
integration-modes.md.

Integration modes (how edits land)

Orthogonal to run mode (security). Default product name is direct. For
one-shot code that means edit this working tree under hardened-direct;
the first direct run without recorded consent fails closed with a trust
summary. /grok:implement always forces an isolated worktree + verify-only
handoff and never lands live (even when the workspace default is
direct/auto) - see integration-modes.md.
ACP peer always uses an external worktree and only applies at ready
peer-stop (direct still needs that same consent; auto applies without it;
review retains). Accept once:

node "$SKILL_BASE/run.mjs" setup --integration direct

Or opt into isolation: --integration auto (worktree + apply-on-ready) or
--integration review / worktree (worktree + manual parent apply). Settings
userConfig.integrationMode / env CLAUDE_PLUGIN_OPTION_INTEGRATIONMODE are a
default hint only - they do not satisfy consent; only setup does.

Canonical matrix (modes, honesty, two "direct" axes, ACP):
plugin/references/integration-modes.md.

On Claude Code, plugin userConfig (Settings) can also set the default run mode,
integration mode, and notification prefs. The host exports them as
CLAUDE_PLUGIN_OPTION_* env vars. Precedence: /grok:setup workspace prefs >
userConfig env > built-in defaults (invalid env values are ignored). Job state
prefers absolute CLAUDE_PLUGIN_DATA when the host provides it. Details:
plugin/references/README.md.

# Prefer skill runner after Skill tool load:
node "$SKILL_BASE/run.mjs" setup --run-mode direct
node "$SKILL_BASE/run.mjs" setup --run-mode hardened
node "$SKILL_BASE/run.mjs" setup --integration direct
# Or from a known install:
node "${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}/scripts/grok-companion.mjs" setup --run-mode hardened

Implementation handoff (1.6.0+) - peer multi-agent integrate API

After a hardened /grok:code run (with or without --contract-file), the wrapper
writes under the state root:

• runs/<runId>/artifacts/implementation.patch (immutable git binary full-index)
• runs/<runId>/implementation-handoff.json

Parents (Claude Code / Codex) must call /grok:handoff --run-id <runId> before
integrating isolated (auto/review) results. Dual-condition ready is true only
when the manifest says ready, a success terminal envelope exists for that
runId, and the patch re-hashes. Completion notifications are not ready -
they only mean a terminal attempt finished.

Integrate is mode-aware and channel-aware (canonical:
integration-modes.md):

• code direct: source edits already live in your tree (protected paths
  rolled back if touched); no patch gate required for the edit to exist
• code auto: companion may auto-apply a dual-condition-ready patch after
  apply-time revalidation (patch integrity + shared dirty-guard spine)
• code review: never auto-applies; parent apply is manual (git apply --check --binary then explicit apply)
• ACP peer: always external worktree during the session; at ready
  peer stop, direct/auto apply the verified patch (direct needs consent),
  review retains; handoff refuses peer runIds

This plugin never auto-commits, merges, cherry-picks, or pushes in any mode.
Handoff checklist: implementation-handoff.md.

--contract-file is operator-trusted (operator-contract-trusted-no-os-sandbox):
argv arrays only, cwd confined to the worktree, no OS filesystem sandbox claim.
runMode direct (setup --run-mode direct) rejects --contract-file (fail closed);
handoff/status/cleanup always use the hardened wrapper even if prefs say direct.

Completion notifications (optional, 1.5.0+)

Default is off. Turn on for background jobs:

/grok:setup --notification-mode auto

Skills set the execution-context env in their bash fences (foreground vs
background). You do not invent that env by hand for normal slash use; for a
background host task, the skill path uses background so auto can fire.
At-most-once attempt only (runs/<runId>/notified.json); details:
execution-context.md,
manual-smoke.md.

Useful flags (live modes)

• Exactly one of --task '…' or --task-file path (prefer a file for long prompts).
• --web only on review / reason / code when you need live docs or current APIs. Off by default. Never on verify.
• --model (default grok-4.5), --timeout (mode-dependent; often 900s), optional
  --max-turns (omit for unlimited - default). Defaults live in
  wrapper/SKILL.md and argparse; skills pass flags through.
  Incomplete Cancelled/turn-cap stops with real findings still return success + warning
  (see COMPATIBILITY.md).

Reading the result

Every run prints exactly one JSON envelope on stdout (success, failure, or
in-flight running). Exit code is 0 when "status" is "success" or
"running"; otherwise 1. For /grok:status, exit 1 can mean a successfully
inspected failed/interrupted target - still relay the JSON. Treat the
envelope as the source of truth; any prose after it is optional commentary.

For code, look for worktreePath / changedFiles in the envelope. For verify, look for the structured verdict.

Direct wrapper (no plugin)

Same engine the plugin shells to. Defaults differ from the product companion:
the companion/skills default to integration=direct after per-repo setup
consent; a bare wrapper code call without --integration intentionally
defaults to worktree (fail-closed isolation) so an un-consented bare call
cannot silently edit the live tree. Pass --integration direct only when you
mean the live-tree posture.

python3 plugin/wrapper/scripts/grok_agent.py preflight
python3 plugin/wrapper/scripts/grok_agent.py review \
  --target src/my-lib \
  --task-file task.md
# bare code: worktree isolation by default
python3 plugin/wrapper/scripts/grok_agent.py code \
  --target src/my-lib --base HEAD --task-file task.md
# explicit live-tree (same as product after consent):
python3 plugin/wrapper/scripts/grok_agent.py code \
  --integration direct --target src/my-lib --task-file task.md

Optional project config

No config required. For JS monorepos that need overrides, put .grok-skills.json at the target repo root (not in this package):

{
  "packageManager": "pnpm",
  "ruleFileParity": false,
  "neverBuildWorkspaces": {
    "@my/schemas": ["typecheck"],
    "@my/ui": ["typecheck", "lint"]
  }
}

• packageManager: pnpm / npm / yarn / bun, or null to skip the JS build gate.
• neverBuildWorkspaces: run listed scripts instead of build for named packages.
• ruleFileParity: when true, require matched AGENTS.md/CLAUDE.md pairs. Default is off (single CLAUDE.md is fine).

Non-JS repos skip the JS package-manager gate with a warning; review/reason/code/verify still work.

Security (short version)

This is a trusted-input tool for repos you are willing to let Grok read (and, in code/verify, run build/test scripts against). It is not a jail for a hostile model.

What it actually enforces:

• Private throwaway Grok home per run (your real credentials are not the run’s HOME)
• OS sandbox write confinement on the supported platform (verified after the run)
• Mode-aware write landing (see integration-modes.md):
  • One-shot code integration=direct (product default after per-repo consent):
    live-tree edits under hardened-direct (private home + sandbox write-confined to
    the repo root + private tmp + post-run protected-path guards). Not worktree
    isolation.
  • One-shot code auto / review / worktree: external worktree + escape
    checks; auto may apply a verified ready patch; review retains for parent apply.
  • Bare wrapper python3 …/grok_agent.py code without --integration: still
    defaults to worktree so an un-consented bare call cannot silently edit the
    live tree.
  • ACP peer: always external retained worktree during the session; at ready
    peer-stop, direct/auto apply (direct needs consent), review retains.
    Peer direct is stop-time apply, not one-shot code live-edit.
• One redacted JSON envelope on stdout (pattern scan + exact values from the injected auth.json)
• Build scripts that Grok rewrote are not executed (gate refused)

What it does not do:

• Block absolute-path reads of host secrets on the current Grok CLI
• Block network egress (Grok is online by design)
• Guarantee pattern redaction catches every secret shape
• Replace host tool-approval UX (Claude/Codex still prompt for Bash as usual)

Model invocation: skills allow host models to invoke them without a slash
command (disable-model-invocation is not set). That is intentional for dual-host
Skill-tool use; treat this plugin as trusted input for those hosts.

More: SECURITY.md, docs/OPEN-SECURITY-DECISIONS.md.

Layout

grok-skills/
  .claude-plugin/marketplace.json    # Claude Code marketplace
  .agents/plugins/marketplace.json   # Codex / ChatGPT marketplace
  plugin/                            # install unit (cache-safe)
    skills/                          # /grok:* definitions
    scripts/                         # companion, gate, relay, SessionStart
    wrapper/                         # Python engine (bundled)
    agents/                          # Claude: grok-engineer-coder, grok-rescue
    codex-agents/                    # Codex TOML templates (auto -> ~/.codex/agents)
    hooks/                           # SessionStart agent ensure + optional stop gate
    assets/
  docs/                              # security, provenance, compatibility

Compatibility notes and versions tested: docs/COMPATIBILITY.md.

Troubleshooting

Contributing

Tests, pin revalidation, and PR notes: CONTRIBUTING.md.

Cutting a release (version bump, tests, tag, GitHub Release, post-smoke):
docs/RELEASE.md.

cd plugin/wrapper/scripts && python3 -m unittest discover -s tests -q
cd plugin/scripts && node --test tests/*.test.mjs
claude plugin validate ./plugin --strict

Disclaimer

Not affiliated with, endorsed by, or sponsored by xAI. Grok is a trademark of xAI. This is an independent integration that calls the Grok CLI.