Grok

Grok Offload — route heavy work to a Grok build agent

You are the orchestrator and reviewer. Grok is the background worker. Select its model for the task, write a precise brief, launch Grok non-interactively, keep working or wait, then review and verify what it produced. You own final quality — never present Grok's output to the user unreviewed.

When to offload (and when not to)

Offload when the task is heavy but well-specified: large refactors or renames across many files, bulk migrations (API, framework, syntax), generating boilerplate-heavy features from a clear spec, fixing a long list of similar test failures or lint errors, or any task the user explicitly asks to send to Grok.

Keep it yourself when the task is small (faster to just do it), requires conversation context or user judgment mid-flight, is design/architecture work, or touches secrets and credentials.

1. Preflight (once per session)

grok models          # prints login status AND the models this account can use
grok --version

• grok not found → point the user at ; it installs to ~/.grok/bin/grok
• Not logged in → tell the user to run ! grok login (interactive; you cannot do it for them)

2. Select the worker model

Honor an explicit model request from the user. Otherwise honor GROK_ROUTER_MODEL when set; it is the user's configured default. If neither chooses, omit -m and let Grok use its own default.

Never invent a model ID. Availability varies by account, and grok models is the only source of truth — treat its output as the allowlist. As of writing a typical account exposes:

| Model ID | Use for | |---|---| | grok-4.5 | The default: substantial implementation work, refactors, migrations | | grok-composer-2.5-fast | Tightly bounded, repetitive, high-throughput work where latency matters |

Docs found in ~/.grok/README.md may reference model IDs the account cannot actually use (e.g. grok-build). Trust grok models, not the README. If a model is rejected and the user did not choose it explicitly, retry once with the account default and report the fallback. If the user chose it, report the error and ask. Do not retry a run that may have modified the workspace without reviewing it first.

Reasoning effort (-e) accepts none, minimal, low, medium, high, xhigh, max. Default high.

3. Write the brief

Grok starts cold — it sees none of your conversation. The brief must be self-contained. Write it to a temp file (multi-line, no shell-quoting pain) using this shape:

# Task

# Context
- Repo root: . Key files/dirs: 
- Relevant conventions: 

# Requirements
- 

# Definition of done
- 

# Out of scope
- Do NOT commit, push, or create branches.
- Do NOT touch: 

Rules: include concrete file paths (Grok can read them itself — point, don't paste whole files); state the verification command; never include secrets, tokens, or .env contents.

4. Launch

Use the wrapper script (in scripts/ next to this SKILL.md). Run it in the background (run_in_background: true) so you can keep working:

/scripts/run-grok.sh -C /path/to/repo -m grok-4.5 -l short-label - ` | cwd | Grok's working root; the sandbox confines writes to it |
| `-m ` | account default | `$GROK_ROUTER_MODEL` sets the default; must be a real ID from `grok models` |
| `-e ` | `high` | `none`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max` |
| `-s ` | `workspace` | `read-only` for analysis-only tasks; also `strict`, `devbox` |
| `-l ` | `run` | names the run directory |
| `--resume ` | — | continue a previous session (step 7) |
| `--max-turns ` | — | hard cap on agent turns; a cheap runaway guard |
| `--best-of-n ` | — | run the task N ways in parallel, keep the best (costs N×) |
| `--check` | off | append a self-verification loop to the prompt |
| `--deny/--allow ` | — | e.g. `--deny 'Bash(rm*)'`; repeatable, deny wins |
| `--no-sandbox` | — | opt out of confinement — needs explicit user approval |

The script prints `RUN_DIR`, containing `prompt.md`, `events.jsonl` (live progress),
`last_message.txt` (Grok's final report), `meta.json` (stop reason + token usage), and
`session_id` (for resume).

### The sandbox line in the output is not decoration — read it

Grok applies `--sandbox` through Landlock, which needs to open `/dev/tty`. **Launched from an
agent or CI there is no controlling terminal, so the profile silently fails to apply and Grok
runs completely unconfined** — it only leaves an `ApplyFailed` line in
`~/.grok/sandbox-events.jsonl`. A bare `grok --sandbox workspace -p ...` from your Bash tool is
therefore *not sandboxed*, however much the flag suggests it is.

The wrapper exists mainly to fix this: it runs Grok under a PTY so the profile applies, then
verifies enforcement and prints `sandbox=enforced` / `sandbox=NOT ENFORCED`. If you ever see
`NOT ENFORCED`, treat every write as unconfined — check `git status` beyond the repo before
trusting the result, and don't re-run until you know why.

## 5. While it runs

You'll be notified when the background task exits. Meanwhile, do other useful work. To check
progress without interrupting: `tail -5 "$RUN_DIR/events.jsonl"`. Events are only `thought`,
`text`, and a final `end` — there is no tool-call stream, so this shows Grok's narration, not
its actions. For what it actually did, read the diff (step 6). Don't poll in a tight loop.

## 6. Review and verify — you own this

When the run exits:

1. Read `last_message.txt` — Grok's own claim of what it did.
2. Inspect reality, not the claim: `git -C  diff --stat`, then read the diff for the
   load-bearing files.
3. Run the definition-of-done checks yourself (tests, grep, build).
4. Small gaps → fix them yourself. Wrong direction or big misses → resume with a corrective
   follow-up (step 7) or revert and take over.
5. Report to the user: selected model, what was offloaded, what came back, what you verified,
   and what you fixed.

`meta.json` carries `stopReason` and token usage. A `stopReason` of `MaxTurns` means it was cut
off mid-task — expect a partial diff.

## 7. Follow-ups (resume)

Sessions are resumable with full memory of the prior run. The wrapper writes the id to
`$RUN_DIR/session_id` before launching, so it is known even if the run crashes:

```bash
/scripts/run-grok.sh -C /path/to/repo --resume "$(cat "$RUN_DIR/session_id")" -l fixup - . Fix them; everything else was correct.
EOF

Note the asymmetry: -s creates a session and errors if the id already exists, while --resume continues one and errors if it doesn't. The wrapper handles both — pass --resume.

8. Parallel offloads

For independent subtasks, launch multiple runs — but give each its own checkout so sandboxed writes never collide (git worktree add, or Grok's own --worktree). Never point two concurrent runs at the same working tree.

Failure modes

| Symptom | Fix | |---|---| | grok: command not found | User installs from | | Not logged in / 401 | User runs ! grok login | | sandbox=NOT ENFORCED | No PTY available — the run was unconfined; audit writes before trusting it | | Session ID ... is already in use | -s was passed an existing id; use --resume instead | | Model rejected / not found | Re-check grok models; the README lists IDs some accounts lack | | stopReason: MaxTurns | Hit --max-turns; resume to continue or raise the cap | | Empty last_message.txt, nonzero exit | Read stderr.log in the run dir | | Result ignores constraints | Brief was ambiguous — resume with explicit corrections, don't relaunch cold |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: luckeyfaraday
• Source: luckeyfaraday/delegate-to-grok
• License: MIT

Install and usage instructions live in the source repository linked above.