Grok Build — the 2026 Method

00Start here

Most Grok Build write-ups — it has only existed since spring 2026 — are "yet another terminal agent" comparisons: install it, give it a prompt, watch it edit files, note that it reads your AGENTS.md. True, and it misses what the tool is for.

Grok Build is the first of the major coding agents designed on the assumption that the agent will be wrong sometimes and must be bounded when it is. Six permission modes where deny rules survive even always-approve. A sandbox enforced by the operating-system kernel, not by the model's good intentions. A plan mode that rejects writes to any file but the plan, in every mode. Subagent roles whose tool access is a capability, not an instruction. It is also open source — Rust, a shell backend and a pager TUI — so when the docs are ambiguous you can read the implementation.

Three statements anchor the method:

xAI, on adoption: "Your AGENTS.md, plugins, hooks, skills, and MCP servers all work out of the box." There is nothing to port before the first useful session.

Grok Build launch announcement

The documented guidance for CI: always-approve plus deny rules or hooks — "not because it is safe, but because there is nobody to approve, so guarantees must be structural."

Grok Build user guide, headless mode

On workflows: describe a large task in plain language and Grok "plans the task as a small script: the phases of work, the agents in each phase, and how their results roll up" — then runs it across hundreds of agents in the background.

xAI, Workflows in Grok Build, July 2026

Everything below follows from those: you do not need to migrate anything, the safety is structural rather than advisory, and the unit of work scales from one agent to a fleet without leaving the terminal.

01Audit your own setup first

Grok has one command that answers the only question that matters at the start — did it find my conventions? — and most people never run it. "It ignores my instructions" almost always means it never discovered them.

grok --version                 # v1.0.5 or later; it ships several times a week
grok inspect                   # every config source, instruction file, skill,
                               # plugin, hook and MCP server it discovered — and
                               # invalid MCP entries that would otherwise block startup
grok doctor                    # terminal, tmux, environment fixes — with repair
gci .grok\skills, .grok\roles, .grok\personas, .grok\workflows
gci ~\.grok\config.toml, ~\.grok\skills, ~\.grok\memory

Inside a session: /context shows what is consuming the window including the fixed overhead — tool definitions, the skills listing, MCP announcements. That is the honest answer to "why does a fresh session already feel full?"

02The four shifts

Trusting the agent → bounding it

The old loop: approve each tool call, read each diff, hope. The new loop: decide once what the agent may touch — sandbox profile, capability mode, deny rules — then stop approving. Approvals are a poor safety mechanism because they are a hundred small decisions made by reflex; a kernel-enforced write boundary is one decision made carefully. Grok is built so the second replaces the first.

Correcting in chat → writing rules

Covered above. This is the one that compounds — and in Grok's case it compounds across vendors, because the instruction layer is portable.

Instructions → capabilities

"Please don't modify files" is advice. A subagent role with default_capability_mode = "read-only" cannot write. Where the model offers a structural control, prefer it over the prose version — it is the difference between a reviewer that agrees with everything and one that cannot be drifted.

One agent → a harness per task

Up to eight subagents in parallel from one prompt; workflows that fan out to 128 agents by default and 1,024 for large jobs; a dashboard that shows every session at once. Picking the right rung is a real skill. That is section 07.

03Bounded, not trusted — the safety model

This section is what distinguishes Grok from everything else on this site, and it is the part to get right before turning approvals down. Three layers, each enforced by something other than the model.

The sandbox — kernel-enforced

Landlock on Linux, Seatbelt on macOS — enforced for the process lifetime. Custom profiles add a deny list with globs (**/*.pem, **/.env), kernel-enforced for read and write. ¹Child-network blocking is Linux-only; on macOS it is a no-op.

Permission modes — six, and the escape hatch is not total

Cycle with Shift+Tab or Ctrl+O; set a baseline with [ui] permission_mode or --permission-mode (CLI wins). Since 0.2.119 the bash allow-list takes glob patterns rather than word prefixes, and [ui] remember_tool_approvals stops it re-asking. Set default_selected_permission = "allow_once" — the default preselects "all sessions", which is how people approve everything by reflex.

Plan mode — actually read-only

Read-only except plan.md. Edits to any other file are rejected outright, the call failing with the plan file named as the only writable path — in every permission mode, always-approve included. That makes plan mode a safe way to let an agent survey a production repository: it cannot touch anything. /plan <task> enters and starts in one step; the agent can request it itself via enter_plan_mode (needs your approval); /view-plan reopens the saved preview, y copies the whole plan as markdown.

The order of operations

grok --sandbox workspace --permission-mode auto     # the everyday invocation

1. Sandbox first, approvals second. Never the reverse. Approvals off without a sandbox is just removing the brakes.
2. Capability modes over instructions. A read-only role cannot write; a polite request can be drifted from.
3. Deny rules and hooks before always-approve — they survive it.
4. Worktree isolation the moment two children write.

04Verification — the primary lever

The logic is simple. An agent stops when the work looks done. Without a check it can run, "looks done" is the only signal available — and you become the verification loop, at review time, which is the most expensive moment to find out. Give it something that returns pass or fail and the loop closes on its own.

The ladder

Rung 4 is where Grok's design pays off. The agent that did the work is the worst judge of the work — models prefer their own output. A reviewer role with default_capability_mode = "read-only" cannot "fix" what it finds, cannot widen its own access, and sees only what you hand it. The kit's reviewer.role.toml is exactly that. Workflows do the same at scale: the built-in /pr-review runs an adversarial verification phase against every finding before synthesis.

Rewrite your prompts

✗  add retry logic to the client
✓  add exponential-backoff retry to HttpGateway.Send for 5xx and
   timeouts only — max 3 attempts, jitter. add tests for: retries
   on 503, no retry on 400, gives up after 3. run
   `dotnet test --filter Gateway` and paste the summary.

✗  the import is slow
✓  ImportJob takes 11 min on the 40k-row fixture (timing attached).
   target < 2 min. profile first; don't change the schema. show me
   before/after timings from `pwsh scripts/bench-import.ps1`.

And always: ask for evidence, not assertions. "Paste the test output" beats "confirm it works." Evidence is the only thing you have for a session you were not watching.

05Context is the budget

Performance degrades as the window fills — and with Grok there is a second reason to care, because price steps up at 200k prompt tokens (section 09). Auto-compaction fires at 85% of the window by default, which on a 500k model is 425k: long past both the quality cliff and the pricing one.

Two rules of thumb

• After two failed corrections on the same issue, /new and start over with a better brief. A clean session with a good prompt beats a long session full of failed approaches.
• Set [session] auto_compact_threshold_percent deliberately. The kit's config.toml uses 60 — on a 500k window that is 300k, still past the cliff; the real fix is /compact by hand when /context shows 150k.

AGENTS.md discipline

Grok reads AGENTS.md, CLAUDE.md, .claude/CLAUDE*.md root-down, .claude/settings.json and Cursor rules. That is a convenience and a trap: if a repository carries all of them, every one loads on every turn. Consolidate into AGENTS.md — the one file every current agent reads — and delete the rest, or keep them as one-line pointers.

The test for every line: "would removing this cause the agent to make a mistake?" If not, cut it. Build, test and lint commands; conventions that differ from the default; architecture boundaries with the reason; where the real docs live; known traps. Not the directory tour, not what the linter enforces, not rules nobody follows.

06How to write a brief now

Delegation means full task context in turn one: goal, constraints, acceptance criteria. Think hard once rather than iterating fast.

GOAL        what "done" looks like, in one sentence
CONTEXT     which files; what pattern to follow; the ticket
            ("look at OrdersController — follow that pattern")
CONSTRAINTS what must not change; what is out of scope;
            libraries you will and will not accept
VERIFY      the exact command that proves it — and "paste the output"

Plan mode — when it earns its place

Plan mode is for genuine ambiguity: "add authentication" (session vs JWT vs middleware), "add caching" (Redis vs in-memory vs file), "redesign the pipeline". It is pure latency for "add a delete button" or "fix the typo". xAI's own list of what a good plan contains is the review checklist: context (why), the recommended approach — not every alternative, paths of critical files, existing functions to reuse with paths, and a verification section. If the plan lacks the last item, send it back.

/plan add rate limiting to the public API      # enter and start in one step
                                               # read it; y copies it; approve → Build
grok -p --permission-mode plan "…"             # a survey that cannot write anything

Plan previews render Mermaid diagrams since 0.2.119 — an architecture change as a picture you can open, copy and paste into the ticket.

Let the agent interview you

I want to build [one line]. Interview me before writing anything —
data model, failure cases, what must not change, tradeoffs I haven't
considered. Don't ask obvious questions. When we've covered everything,
write SPEC.md and stop.

Then /new and execute the spec in a fresh session, or hand it to a workflow. Clean context, written reference.

Three more techniques

• Challenge the output. "Prove this works — show me the diff and the test output." Then hand it to the reviewer role.
• Ask codebase questions like you would ask a senior engineer. An explore subagent in --sandbox read-only is the safest onboarding tool there is for a repository you do not own.
• Use voice. Ctrl+Space / F8 toggles dictation. Roughly three times faster than typing for long briefs — and briefs should be long now.

07The parallelism ladder

This is where the leverage lives. Five rungs, each a different answer to "who holds the plan?"

Worktrees

An isolated checkout per task, so edits never collide. Grok manages its own under ~/.grok/worktrees (reclaimed automatically since 1.0.5) when you ask for isolation: worktree; for your own parallel sessions, make them by hand and run one Grok in each:

git worktree add ..\repo-ratelimit feature/ratelimit
cd ..\repo-ratelimit; grok --sandbox workspace --permission-mode auto

Name sessions by outcome ("ratelimit-tests-green") — /rename, and /rename --auto to let Grok title them — and let /dashboard be the control plane once more than two are running.

Subagents — declarative, bounded, one level deep

Just append "use subagents" to a hard prompt. The main agent calls spawn_subagent with a prompt, a type (general-purpose · explore · plan, or a role you defined), optionally background and isolation: worktree. Each has its own context window; they report back a summary. /dashboard shows them; the stop command kills background ones from prior turns.

# .grok/roles/reviewer.toml
[subagents.roles.reviewer]
description = "Read-only reviewer: correctness, security, stated requirements"
default_capability_mode = "read-only"
model = "grok-4.6"
prompt_file = ".grok/prompts/reviewer.md"

Three things to know. Nesting is one level — a subagent calling spawn_subagent fails with a depth-limit error; fan out from the parent, do not build trees. Use isolation: worktree whenever more than one child writes. And children inherit the parent's MCP servers; narrow with mcpInheritance: none | named | except so a reviewer cannot reach the ticket system's write tools. resume_from continues a finished child rather than re-briefing it.

Workflows — the big one

A workflow is a small script that orchestrates agents at scale: Grok writes the phases, the agents in each, and how the results roll up; a runtime executes it in the background while your session stays responsive. The critical difference from everything above: the plan moves out of a context window and into code. Loops, branching and intermediate results live in script variables; your context only ever holds the final answer.

use a workflow to audit every controller under src/Api/ for missing
authorisation checks, and adversarially verify each finding

/pr-review 1842            # built-in: gather context → specialist review →
                           #   adversarial verification → synthesis
/deep-research <question>  # built-in: parallel investigators, claims checked
                           #   against sources, cited report
/workflows                 # watch live, phase by phase, per-agent tokens;
                           #   pause · resume · stop · save

On by default since 0.2.111; a run that fails resumes where it stopped. Save one and it becomes a slash command that takes arguments — .grok/workflows/ for the team, ~/.grok/workflows/ for you. The session "stays free the whole time"; the agents do not. Save workflows for genuine fan-outs — every feature in a large PR, the last hundred issues, one class of bug across a codebase — not twenty-line tweaks.

/loop — the smallest harness

/loop stores a prompt with a stop condition and re-runs it; recurring loops expire after seven days unless renewed. "Re-run the integration suite every 20 minutes and report only when the failure count changes" is a harness; "check the build" is noise.

08Making it permanent

Skills

The rule of thumb: if you do something more than once a week, make it a skill. A skill is a folder — markdown plus scripts — and its description is the matcher: what it does and when to use it, or it never fires.

.grok/skills/release-notes/SKILL.md
---
name: release-notes
description: Draft release notes from merged PRs since the last tag.
  Use when asked for release notes or a changelog entry.
when-to-use: changelog, what shipped, release summary
allowed-tools: shell
disable-model-invocation: true
---
1. `git describe --tags --abbrev=0` for the last tag
2. `gh pr list --state merged --search "merged:>$TAG_DATE" --json ...`
3. Group by label; one line per PR; link each. Write CHANGELOG.md; do not commit.

disable-model-invocation: true means you run it as /release-notes and the model cannot fire it on its own — right for anything with side effects. paths: takes gitignore-style patterns so a skill is invisible until a matching file is in play. grok skill search and grok skill install @ns/name pull from marketplaces; plugin skills arrive the same way and can bring a language server with them — real symbol navigation and after-edit diagnostics, the part of the IDE that mattered.

Hooks

Hooks are the only deterministic layer — instructions are advice, a hook is a rule — and they survive always-approve. Project hooks require /hooks-trust: a hook in a repository you cloned is arbitrary code execution, so read it first. SessionEnd hooks fire in headless sessions too (fixed in 0.2.113), which is what makes them usable for the rung-3 test run. Ask for them rather than hand-writing: "write a hook that runs the formatter after every edit"; /hooks manages what is loaded.

Memory and sessions

Memory is experimental and off: GROK_MEMORY=1 or [memory] enabled, /memory on|off per session. Markdown under ~/.grok/memory/, keyed by the origin remote — so clones and worktrees of one repo share a memory, and a wrong fact learned in one follows you to the others. Correct mistakes deliberately. Sessions persist: grok -c continues, -r <id|title> resumes (scripts should use IDs), --fork-session branches, and /resume shows a recap first.

09Models and the 200k cliff

The two numbers in each price column are the point of this section. A request whose prompt reaches 200k tokens is billed at the higher rate for every token in it — not just those past the threshold. A cliff, not a ramp: a 210k prompt costs roughly double a 190k one. Cached input bills well below fresh on every model, and 0.2.115 improved caching for long conversations, which helps — but nothing helps like staying under the line.

/model                       # switch for this session
/usage · /context            # what it is costing and why (tabbed modal since 1.0.1)
grok -m grok-build -p "…"    # cheap model for a scripted sweep
[models] default = "grok-4.6"            # decide once, in config.toml
[session] auto_compact_threshold_percent # and lower it

Pin the model per role, not per moment. model = in a role TOML decides once: the reviewer on 4.6, the explorer on Grok Build 0.1. A workflow with cheap finders and one strong judge costs a fraction of the all-4.6 version and finds the same bugs. Watch /context for fixed overhead — plugins and MCP announcements get you to 200k sooner than you think.

10Headless, CI and ACP

Install on Windows with irm https://x.ai/cli/install.ps1 | iex (adds %USERPROFILE%\.grok\bin to the PATH), or curl -fsSL https://x.ai/cli/install.sh | bash under WSL — which is where the sandbox works. Authenticate with SuperGrok / X Premium+, or XAI_API_KEY from console.x.ai; enterprise sign-in goes through [auth] auth_provider_command.

Grok as a component

grok -p "summarise the failing tests" < test.log
git diff main | grok -p "list any change that alters a public API"
grok -p --output-format json "…"                    # or streaming-json
grok -p --sandbox strict --permission-mode dontAsk `
     --tools read,grep,glob --rules "never modify files" "audit src/ for …"

-p turns Grok into a filter — scriptable from a git hook, a build script, a CI step. For CI the documented recommendation is always-approve plus deny rules or hooks, because there is nobody to approve — so pair it with --sandbox and --disallowed-tools, and set GROK_SESSION_ID where downstream tools need to correlate. !cmd runs a command yourself inside a session (one-hour timeout); grok du reports what sessions and worktrees are costing in disk.

Agent Client Protocol

grok agent stdio --always-approve
grok agent serve --bind 127.0.0.1:2419 --secret <token> --always-approve

Drive Grok as a server to build your own client on top — an editor integration, an internal tool, a bot. Because the agent is open source, when the protocol docs run out you read xai-org/grok-build.

MCP — tools beyond the shell

grok mcp enable|disable <name> from the command line (0.2.113), /mcps in the TUI. The high-value additions are systems that hold answers your repo cannot give: the issue tracker, the observability stack, the design system. Two disciplines: every server costs context — its announcements are in the fixed overhead /context shows — and tool output is data, not instructions. Use read-only credentials wherever the work is read-only, and mcpInheritance to keep write tools away from subagents that do not need them.

11Beyond the repo — ops, documents, data

Step one — give it something to read

A plain-markdown wiki in git — hosts, decisions and why, runbooks, where the dashboards and tickets live, traps and the incident that proves them — and CLI access to live data, because pasting is stale, truncated and unrepeatable. Both are the subject of the work-wiki lesson; this page assumes they exist.

Step two — find the verification loop

The third column is what Grok adds. "Survey the production config and tell me what drifted" is a task most people would not hand to an agent; in --sandbox read-only --permission-mode plan it cannot write a byte, and the answer is worth having.

Step three — write the domain knowledge down

Environment names, which tenant is which, the release calendar, the ticket that explains why the weird thing is weird — each an instruction line, a skill or a wiki page, written once. The most quietly valuable is a runbook skill with disable-model-invocation: true: the exact commands, the check at each step, the rollback — run by you, at 2 a.m., with the agent doing the typing.

12Away from the keyboard

The pattern that ties them together is the one from section 04: give the unattended run a way to know it is done — and, because it is Grok, a bound on what it may do while nobody is watching. A scheduled grok -p without a sandbox is the one invocation on this page to refuse to write.

13Tools on the PATH

An agent is exactly as capable as the command-line tools it can call. Grok cannot make a PDF, query a database or lint a template by wanting to — it needs a binary on the PATH that does it and returns an exit code. On Windows winget makes it one line each; under WSL it is apt or brew.

Three selection rules. Prefer tools with a non-interactive mode — an agent cannot answer a prompt. Prefer machine-readable output (--json, ConvertTo-Json, exit codes). Prefer one tool that does a thing well over a GUI app with a CLI bolted on.

14The starter kit

Four files that turn the ideas above into configuration. Copy them into a repository's .grok/ and adapt. Nothing here is specific to one machine.

Two more ship with the work-wiki lesson and are worth taking together: a config.toml with the model, permission and compaction settings chosen deliberately, and an AGENTS.md template.

15What to do, in order

This week — thirty minutes

• Install; cd into a repository that already has an AGENTS.md or CLAUDE.md; run grok inspect. If it found your conventions, you are evaluating the real thing.
• Set [models] default and default_selected_permission = "allow_once" in config.toml.
• /plan a real task. Read the plan; send it back if it lacks a verification section.
• Next time you correct Grok, stop and ask: should this be a rule instead? Then write it.
• Add "run the tests and paste the summary" to the end of every brief.

Next week

• Adopt the everyday invocation: grok --sandbox workspace --permission-mode auto — under WSL if you want the sandbox to mean anything.
• Copy in the reviewer role and make "have the reviewer check it" the last line of every brief.
• One skill for the thing you do every Friday, with disable-model-invocation: true.
• On the next multi-module task, say "use subagents on worktrees" and watch /dashboard.
• /pr-review on a real pull request; read the adversarial-verification phase in /workflows.

The month after

• Write a deny list (**/*.pem, **/.env, the migrations folder) and one hook; then try /always-approve on a bounded task.
• Run /deep-research on a real question and compare it to what a single pass would have said.
• Put ci-audit.ps1 on Task Scheduler and see whether you read the output.
• Save one workflow you wrote as a slash command for the team.
• Read /context after a heavy day, and uninstall the plugins that are costing more than they give.

16Anti-patterns

The one-paragraph version

Bound the agent before you trust it: a sandbox profile, a capability mode, a deny list — decided once, enforced by something other than the model — and only then turn approvals down. Give it a way to check its own work, in the brief, in the plan's verification section, in a hook, and in a reviewer role that cannot edit. Guard your context like a budget and your prompt like a bill: clear often, compact before 200k, delegate reading to subagents. When Grok gets something wrong, write a rule in AGENTS.md rather than a correction in chat, so every agent you will ever point at the repo improves at once. And when the work is bigger than one conversation, don't hold it in one: worktrees for independent work, subagents for research and review, workflows when the plan belongs in a script.