grokdrive

Unofficial — not affiliated with xAI. Best-effort; the Grok Build CLI's flags and output shape may change and can break dispatch.

Burn Grok credit on token-intensive work. Claude keeps full tool discretion.

Session-scoped "burn Grok credit" mode for Claude Code. When ON, prefer routing expensive work (large implementations, multi-file refactors, bulk exploration, long CI/test churn) to the Grok Build CLI's current default model (Grok 4.5 at time of writing), headless — so you spend Grok tokens instead of Claude tokens. Claude remains free to Write / Edit / Bash / MCP / sub-agents whenever that is the better call.

Default is soft routing + a dispatcher. Not a sandbox. Not an edit fence.

Optional hard fence for the old behavior: grokdrive on --strict.

How it works

Soft (default). grokdrive on arms routing doctrine for the session. Claude keeps every tool. Heavy work goes through:

grokdrive "<self-contained spec>"

which dispatches to Grok. Effort auto-tiers (HIGH for complex specs, MEDIUM for standard). Each dispatch writes a raw artifact; verify --gate "<cmd>" produces a GREEN / RED verdict marker.

Strict (opt-in). grokdrive on --strict also arms a PreToolUse hook that blocks direct Claude Write / Edit / MultiEdit / NotebookEdit on project files (trivial ≤20-line edits and harness paths still pass). Kill with grokdrive off or CLAUDE_GUARDS_OFF=1.

Soft vs strict

	Soft (default)	Strict (--strict)
Claude Write/Edit	Allowed	Blocked on project files
Prefer Grok for heavy work	Yes (doctrine)	Yes (doctrine + fence)
Bash / MCP / sub-agents	Always free	Always free (not a sandbox)

Requirements

Need	Notes
Claude Code	Session host
Grok Build CLI (grok)	On PATH; used for every dispatch
node	Runs the (optional) strict gate hook
python3	Settings JSON surgery + CLI helpers
bash	Installer and dispatcher

Install

git clone https://github.com/Rennlabs/grokdrive.git
cd grokdrive
./install.sh

This is also a Claude Code plugin: drop the repo into a plugin marketplace; hooks/hooks.json wires the gate via ${CLAUDE_PLUGIN_ROOT} (only bites under --strict).

Caveat (strict only): hooks load at Claude Code session start. After install, start a fresh session before relying on --strict.

Preview without mutating your machine:

./install.sh --dry-run

Usage

# Arm / disarm (session-scoped by default; soft by default)
grokdrive on [--advisor opus|fable] [--effort auto|high|medium|low] [--global] [--strict]
grokdrive off
grokdrive status
grokdrive explain

# Dispatch
grokdrive "<full self-contained spec>"     # bare form
grokdrive run -f spec.md                   # big spec via file
git diff | grokdrive "review+fix"          # stdin as context
grokdrive parallel "A" "B" "C"             # independent bodies

# External proof
grokdrive verify --gate "pytest -q" [--loop <mode>]

# Health
grokdrive doctor

Routing doctrine

Prefer Grok (token-intensive)	Prefer Claude (discretion)
Multi-file implementation from a frozen spec	Design, API shape, architecture, naming, UX
Refactors, mechanical migrations	Small targeted edits
Bulk test writing / coverage / CI churn	Tasks where writing the spec is the work
Bulk exploration (raw reading ≫ answer)	Session-tool work (MCP, secrets, browser)
Dependency bumps, script rewrites	Destructive / irreversible / release / push ops
	Review of Grok's output (never delegated)

Heuristic: would this burn a lot of Claude tokens for mostly mechanical work → Grok; would writing the spec take longer than doing it → Claude.

The prompt contract

Grok starts each dispatch with zero session context. Every spec must carry:

1. Goal — what done looks like
2. Repo + key paths — exact tree locations
3. Constraints / non-goals — what not to touch
4. Exact proof command — e.g. pytest -q, npm test
5. Output shape — files changed, command stdout, residual risks

Spec quality decides success.

Verify

Grok's summary is advisory. Read the real diff, then run the external gate yourself:

grokdrive verify --gate "pytest -q"
grokdrive verify --gate "npm test" --loop autopilot

GREEN iff the gate exits 0. --loop <mode> also stamps that loop's verifier marker. On RED, dispatch a fix body with concrete failure notes and re-verify. Never close on a summary card alone.

Configuration

Variable	Default	Meaning
GROKDRIVE_EFFORT	auto	auto | high | medium | low
GROKDRIVE_MODEL	empty	Empty = Grok Build CLI default (Grok 4.5 at time of writing)
GROKDRIVE_MAX_TURNS	60	Max turns per dispatch
GROKDRIVE_TIMEOUT	1200	Dispatch timeout (seconds)
GROKDRIVE_SANDBOX	empty	Passed through to grok when set
GROKDRIVE_TRIVIAL_LINES	20	Strict-mode allowlisted edit size (0 = no exceptions)
GROKDRIVE_STATE_DIR	~/.claude/.grokdrive-state	Mode state directory
CLAUDE_GUARDS_OFF	unset	Set to 1 to disable the strict gate

How the optional strict gate works

• Per-session state at ~/.claude/.grokdrive-state/<session_id>.json (all.json for --global). Soft mode sets "strict": false (or omits it — treated as soft). Strict sets "strict": true.
• Only strict: true denies Claude mutation tools. Missing/false = soft no-op.
• Always allowed in strict: trivial edits ≤ GROKDRIVE_TRIVIAL_LINES; paths under ~/.claude/**, ~/.local/bin/**, /tmp/claude-*.
• Kill-switch: CLAUDE_GUARDS_OFF=1 or grokdrive off or re-arm with grokdrive on (soft).
• Fail-soft: any hook error is a no-op (never wedges a tool call).

Uninstall

./install.sh --uninstall

Removes the three symlinks (only if they point into this repo) and strips the grokdrive PreToolUse entry from ~/.claude/settings.json, leaving other hooks intact.

License

MIT © 2026 Renn Labs