grok-cli

name

grok-cli

description

Use when the user says to use Grok, wants a Grok review, wants a second opinion from Grok, or asks to delegate a task to Grok. Also use for getting an independent code review from Grok, having Grok reason about an architecture or debugging question, having Grok implement code (live tree by default, or opt-in isolated worktree), or having Grok independently verify someone else's implementation. Trigger phrases include "use grok", "grok review", "second opinion from grok", and "delegate to grok".

Grok CLI companion agent

This skill wraps the authenticated grok CLI in a deterministic Python wrapper (scripts/grok_agent.py) so Grok 4.5 can act as a capable companion agent for review, reasoning, implementation, and independent verification, under authority scoped tighter than an interactive session. The wrapper owns process isolation, private authentication, sandboxing, and result reporting. It never trusts a Grok narrative in place of verified evidence.

Every subcommand prints exactly one JSON result envelope to stdout, success or failure alike. Exit code is 0 when the envelope's status is "success" or "running" (in-flight status polls); otherwise 1.

Hard rule: copy the command lines exactly

Never reconstruct a command line for this wrapper from memory or prose. The exact set of flags, their order, and their exact spelling are part of the safety guarantee this wrapper provides (fail-closed argument parsing, no shell evaluation of task text, a fixed C6 invocation baseline underneath every mode). Copy a command from this file or from references/workflow-patterns.md, then substitute only the placeholder values (<...>). If none of the documented commands fit the task, stop and ask before improvising a new flag combination.

Every invocation has this shape:

python3 plugin/wrapper/scripts/grok_agent.py <mode> [flags...]

You can run from any cwd. Relative --target / paths resolve against the process cwd; the repository root is the git toplevel of the resolved target (not the wrapper install tree). Marketplace installs live outside the repo under review.

The verbatim relay rule

You must return the wrapper's stdout verbatim. No paraphrase, no summary, no added commentary layered on top. The wrapper is the only place orchestration and safety decisions are made; your job is to run the exact command and hand back exactly what it printed. If you want to explain the result in your own words, do that separately, clearly labeled as your own summary, AFTER relaying the raw envelope - never instead of it.

The eight subcommands: when to use each

preflight - readiness check, no task

Run this first in a session, or whenever something downstream looks wrong. It is read-only: it verifies the grok binary is runnable, the presence of ~/.grok/auth.json, a full private-home create/login/inspect/destroy cycle, sandbox policy resolution for every live mode, the state root permissions, and the stale-home audit. It never spawns a task-bearing Grok run.

python3 plugin/wrapper/scripts/grok_agent.py preflight

review - full-context, read-only code review

Use when local repository rules and surrounding source in a real workspace matter: reviewing an app, package, or subsystem before merging, or getting Grok's read on an existing area of the codebase. review walks the repository rules (AGENTS.md/CLAUDE.md) from repo root down to the target and includes them in the prompt; it can only read (read_file, grep, list_dir). Concurrent tree drift or change-shaped JSON keys become informational warnings (findings still returned); write escapes still fail on code/verify only.

python3 plugin/wrapper/scripts/grok_agent.py review \
  --target <workspace-relative-path> \
  --task-file <path-to-task-file>

Optional flags: --base <ref> (comparison framing only; does not force isolation), --isolated (opt-in: owned external worktree at HEAD with tracked dirty applied; setup failures fail closed as isolation-unavailable with no silent live-tree fallback), --web, --schema <path>, --model <id> (default grok-4.5), --timeout <seconds> (default 900), optional --max-turns <n> (default: unlimited - flag omitted unless set). --task <text> may replace --task-file for a short prompt; exactly one of --task / --task-file is required.

Default is the live checkout. Use --isolated when concurrent editor noise or a dirty tree would confuse the review; use --base alone when you only need branch-comparison framing. --isolated requires hardened mode (rejected under GROK_SKILLS_MODE=direct).

reason - isolated artifact reasoning, cold second opinion

Use for architecture or debugging consultation, plan/spec critique, comparing approaches, or reviewing explicitly-named files or diffs when full repository context is not required. The working directory is a fresh private temp dir OUTSIDE the repo and there is no automatic rule discovery - only files you name with --input or --rules-file are supplied. This is the cheapest, most deterministic mode; prefer it over review whenever the task does not depend on neighboring repo files or repo-wide rules.

python3 plugin/wrapper/scripts/grok_agent.py reason \
  --task-file <path-to-question-file> \
  --input <path-to-artifact>

--input and --rules-file may each be repeated. Optional flags: --web, --schema <path>, --model, --timeout (default 900), optional --max-turns (default: unlimited).

code - mode-aware implementation (worktree or live tree)

Use when Grok should actually write or modify code. Landing is mode-aware (--integration; see ../../references/integration-modes.md):

• Bare wrapper default (--integration omitted or worktree): creates and verifies an external git worktree (never the current checkout), requires the workspace's full build gate (build or typecheck+lint, plus test when present) to pass with exit 0, and keeps the worktree for inspection. Fail-closed isolation so an accidental bare python3 …/grok_agent.py code call cannot silently edit the operator checkout.
• --integration direct: hardened-direct live-tree edits under private auth home + sandbox write-confined to the repo root (+ private tmp) + post-run protected-path guards. Product companion/skills default to this with no setup consent (2.0.1+). No external worktree; no pre-apply dual-condition gate.
• Product alias modes auto / review map through the companion onto the worktree path (auto may apply a verified ready patch; review retains).

Nothing is ever committed, merged, pushed, or deleted automatically. ACP peer is a separate channel that is always external worktree with stop-time apply.

# bare wrapper: safe worktree default
python3 plugin/wrapper/scripts/grok_agent.py code \
  --target <workspace-relative-path> \
  --base <committed-revision> \
  --task-file <path-to-spec-file>

# live-tree path (product default; setup --integration direct only persists prefs)
python3 plugin/wrapper/scripts/grok_agent.py code \
  --integration direct \
  --target <workspace-relative-path> \
  --base <committed-revision> \
  --task-file <path-to-spec-file>

Optional flags: --web, --model, --timeout (default 3600), optional --max-turns (default: unlimited), optional --contract-file <path> (operator-trusted JSON: writeScopes + requiredValidation argv arrays; trust model operator-contract-trusted-no-os-sandbox - no OS FS sandbox claim), --integration direct|worktree (wrapper-native; bare default worktree). If the task depends on uncommitted changes in the current checkout and the run uses the worktree path, code fails closed rather than approximating them

• commit what the task needs first.

After Grok on the worktree path, the wrapper always attempts phase-1 patch

• phase-2 implementation-handoff.json under the run dir (even on classified failure when forensics are possible). Parents integrate only via handoff --run-id for retained worktrees; live-tree direct already landed source edits.

handoff - read-only verified implementation handoff (1.6.0+)

Use after a code run to decide whether the retained worktree's immutable patch is integration-ready. Never spawns Grok, never creates jobs, never applies patches. Observed ready requires: valid ready manifest + success terminal envelope for the same runId + patch rehash.

python3 plugin/wrapper/scripts/grok_agent.py handoff --run-id <run-id>

verify - independent verification, no source edits

Use to have Grok independently inspect and test a change - your own or someone else's - in an EXISTING worktree, typically one a prior code run produced. Source-editing tools are absent; the run always ends with a machine-readable pass / fail / inconclusive verdict plus evidence. verify is version 1's independent-verification path (the CLI's own --check verifier surface is deferred; see references/workflow-patterns.md recipe 13).

python3 plugin/wrapper/scripts/grok_agent.py verify \
  --worktree <absolute-path-to-worktree> \
  --task-file <path-to-verification-task-file>

Optional flags: --model, --timeout (default 1800), optional --max-turns (default: unlimited). verify never accepts --web - independent verification stays hermetic by design.

status - read-only inspection of a prior run

Reads back a run's stored envelope and progress stream by run id. It never writes to the run it inspects. Top-level status is a projection of the target lifecycle (running / success / failure); exit 1 with a valid status envelope means the target failed or was interrupted, not that status itself failed to inspect.

python3 plugin/wrapper/scripts/grok_agent.py status --run-id <run-id>

cleanup - report or remove a run's owned state

Without --confirm this is a dry run: it reports the owned session state and (for code/verify) the worktree and branch it WOULD remove. With --confirm it actually removes them, refusing a dirty worktree rather than forcing it. When the run has integration.ready === true handoff artifacts, cleanup warns factually that removal is permanent and the plugin cannot know whether the implementation was integrated (no "unacknowledged" wording).

python3 plugin/wrapper/scripts/grok_agent.py cleanup --run-id <run-id>

python3 plugin/wrapper/scripts/grok_agent.py cleanup --run-id <run-id> --confirm

--task-file over --task

Prefer --task-file for anything beyond a short one-line prompt. It avoids shell-quoting hazards, keeps the task text auditable as a plain file, and is the only practical way to hand Grok a multi-paragraph spec, a full plan document, or a review rubric. --task and --task-file are mutually exclusive; the wrapper never evaluates task text as shell syntax either way.

--web: opt-in web access

Web tools are OFF by default in every mode, for review determinism (decision D-WEB). Pass --web on review, reason, or code when the task genuinely depends on current practices, current software or library versions, or living/external documentation that the repository's own rules and code cannot answer - for example "does this match the latest stable API for library X" or "what's the current recommended pattern for Y". When set, the envelope records policy.webAccess: true.

verify never accepts --web. Independent verification stays hermetic in every case; do not attempt to add web access to a verify run.

Accepted residual risk and platform gate (read before any live run)

• Secret-read residual (decision D-SECRETREAD). Grok 0.2.101 cannot deny reads of credential or external-secret paths through any sandbox profile - only WRITES are confined. The wrapper mitigates this with per-run private HOME isolation (so ~ expansions never reach your real home) and by isolating the copied auth.json, but a Grok child can still read any host-readable file by absolute path. Only run live modes against trusted inputs. Full evidence: references/authority-policies.md and references/cli-reference.md.
• Platform probe gate (decision D-PORT). Live modes (review, reason, code, verify) fail closed with error class probe-required on any platform without a captured Grok sandbox probe report. macOS (Seatbelt) and Linux (Landlock) are probed; Linux also requires bwrap (bubblewrap) on PATH. Windows stays blocked until its own probe suite is committed. Evidence: scripts/tests/fixtures/probe-report.md and scripts/tests/fixtures/probe-report-linux.md.

Reference material

• references/authority-policies.md - per-mode capability tables (tools, sandbox, cwd, network, subagents, web) and what every C4 error class means for you as the operator.
• references/cli-reference.md - last-validated Grok CLI evidence (advisory), the C6 invocation baseline, sandbox and permission-mode evidence, auth file names, and how maintainers refresh the stamp after a probe suite.
• references/workflow-patterns.md - the tested recipes: which mode to use for full-context review, cross-file review, isolated diff review, multi-angle review, architecture consultation, plan critique, code implementation, test generation, plan-conformance review, independent verification, structured judgments, and handing a retained worktree to a developer or to Codex - plus what is excluded or deferred in version 1.