delegate-to-grok

A Claude Code skill for orchestrating the Grok CLI as a background build agent. Claude stays the orchestrator and reviewer; Grok does the heavy lifting in a sandboxed workspace; you get a reviewable diff.

It ships two things:

• SKILL.md — the operating manual the orchestrating agent reads: when to offload, how to split a task into cleanly-scoped subtasks, how to write a self-contained brief, how to launch, and how to verify and reintegrate what came back.
• scripts/run-grok.sh — a wrapper around grok that makes headless runs safe, loggable, and resumable.

Works with any agent that can read a skill and run a shell command — Claude Code, Codex, or a plain terminal.

Why the wrapper exists

Grok's --sandbox silently does nothing when there is no TTY.

Grok applies its sandbox profile via Landlock, which needs to open /dev/tty. When you launch Grok from an agent, a script, or CI, there is no controlling terminal — the profile fails to apply and Grok continues to run completely unconfined. The only trace is an ApplyFailed line in ~/.grok/sandbox-events.jsonl. The command still exits 0, and the flag still looks like it worked.

Demonstrated on grok 0.2.101, Linux 6.17, kernel Landlock available:

$ grok -p 'Run: touch ~/ESCAPED' --sandbox workspace --cwd /tmp/demo --permission-mode bypassPermissions
$ ls ~/ESCAPED
/home/<user>/ESCAPED          # ← written straight through the sandbox

$ tail -1 ~/.grok/sandbox-events.jsonl
{"event_type":"ApplyFailed","profile":"workspace","enforced":false,
 "error":"Landlock path error: failed to open \"/dev/tty\": No such device or address"}

The wrapper runs Grok under a PTY so the profile actually applies, then verifies enforcement after the fact rather than trusting the flag:

$ ./scripts/run-grok.sh -C /tmp/demo -l demo - <<< 'Run: touch ~/ESCAPED'
RUN_DIR=/tmp/grok-router/20260715-133012-demo-48652
sandbox=enforced
--- last message ---
touch: cannot touch '/home/<user>/ESCAPED': Permission denied

If it can't confirm enforcement it prints sandbox=NOT ENFORCED and warns on stderr, so an unconfined run is never mistaken for a sandboxed one.

What else it handles

• Deterministic resume. The session UUID is generated before launch and written to $RUN_DIR/session_id, so follow-ups work even if the run crashes. (grok -s creates a session and errors if the id exists; --resume continues one and errors if it doesn't. The wrapper takes --resume and does the right thing.)
• Clean JSON. A PTY rewrites \n to \r\n; stderr would otherwise interleave with the event stream. The wrapper strips CRs and redirects stderr inside the PTY, leaving parseable NDJSON.
• Briefs via file. Prompts go through --prompt-file, so multi-line briefs need no shell quoting.
• Run artifacts. Every run leaves a directory behind rather than scrolling past you.

Install

Requires grok (logged in via grok login), bash, jq, and script (util-linux or BSD).

git clone https://github.com/luckeyfaraday/delegate-to-grok.git
ln -s "$PWD/delegate-to-grok" ~/.claude/skills/grok

Then verify:

grok models        # prints login status and the models your account can use
~/.claude/skills/grok/scripts/run-grok.sh --help

Usage

The agent normally drives this, but the wrapper stands alone:

# Offload a task; brief comes from a file, run lands in $RUN_DIR
./scripts/run-grok.sh -C ~/code/myrepo -m grok-4.5 -l migrate - < brief.md

# Analysis only — no writes
./scripts/run-grok.sh -C ~/code/myrepo -s read-only - <<< 'Summarize the auth flow.'

# Follow up on the same session, with full memory of the prior run
./scripts/run-grok.sh -C ~/code/myrepo --resume "$(cat $RUN_DIR/session_id)" - <<< 'Tests still fail: ...'

Options

Environment: GROK_ROUTER_MODEL, GROK_ROUTER_EFFORT, GROK_ROUTER_SANDBOX, GROK_ROUTER_RUNS (run-directory root, default $TMPDIR/grok-router).

Run artifacts

$RUN_DIR/
  prompt.md          the brief as sent
  events.jsonl       NDJSON stream: thought / text / end
  last_message.txt   Grok's final report, reconstructed from the stream
  meta.json          stopReason, sessionId, token usage
  session_id         for --resume
  stderr.log         diagnostics when a run exits non-zero
  raw.log            unprocessed PTY output

Note that events.jsonl carries only thought, text, and a final end — Grok streams no tool-call events, so it shows narration, not actions. Read the diff to see what it did.

Caveats

• Runs use --permission-mode bypassPermissions — Grok is not asked to confirm tool calls. The sandbox, not a prompt, is what confines it. Use --deny rules for finer control.
• --sandbox enforcement is Linux/Landlock (kernel ≥ 5.13) and macOS Seatbelt. Elsewhere the wrapper will report NOT ENFORCED.
• Concurrent runs need separate checkouts (git worktree add). Never point two runs at one tree.
• Model IDs vary by account; ~/.grok/README.md documents some that aren't universally available. grok models is the source of truth.

License

MIT — see LICENSE.