Grok Build Reference xAI's terminal coding agent

A terminal coding agent built to be bounded rather than trusted: six permission modes where deny rules survive even always-approve, a kernel-enforced sandbox, and a plan mode that is genuinely read-only in every mode. Guide cards explain the mechanisms; the index below is a searchable dictionary of every command, flag, slash command, config key and TOML field.

CLIslash commandconfig / TOMLsafetymodelanti-pattern August 2026

▾How Grok Build works

the safety machinery, the extension layer, and what it costs to run · click to collapse

What Grok Build is

xAI · CLI

A terminal coding agent: reads and edits files, runs shell commands, searches the codebase, plans work, applies changes after you approve. What distinguishes it is how much is built to be bounded rather than trusted.

MechanismWhat it guarantees
Six permission modesDeny rules, hooks and some shell rules survive even always-approve
Kernel sandbox, 5 profilesLandlock / Seatbelt — enforced by the OS, not the agent
Plan modeRead-only except the plan file, in every mode
Roles & personas (TOML)Capability modes: a reviewer that must not write cannot

Open source — xai-org/grok-build, Rust, split into a shell (agent backend) and a pager (TUI). When the docs are ambiguous you can read the implementation.

Access with SuperGrok / X Premium+, or the Code API. Two components you will see named in logs and settings: the shell and the pager.

The 30-second orientation: install, grok inspect to see what config it found, then a real task in /plan mode — and read the plan before approving.

Install & first run

5 minutes
curl -fsSL https://x.ai/cli/install.sh | bash # macOS / Linux irm https://x.ai/cli/install.ps1 | iex # Windows

npm is an alternative path. Authenticate with a SuperGrok / X Premium+ subscription, or set XAI_API_KEY from console.x.ai.

grokinteractive TUI grok inspectwhat config was actually discovered grok -p "…"headless grok --sandbox workspacethe sensible default

Run grok inspect first, every time. It lists discovered config sources, instructions, skills, plugins, hooks and MCP endpoints — the only question that matters at the start is whether it found your conventions.

It is open source

xai-org/grok-build, in Rust: a shell (agent backend) and a pager (TUI frontend). When the docs are ambiguous you can read the implementation — not true of its competitors.

Permission modes

6
ModeRuns without asking
default (ask)Read-only tools and built-in read-only shell
acceptEditsFile edits
autoWhat the safety check allows; rest blocked or escalated
dontAskOnly pre-approved tools
bypassPermissionsTool calls in general — "always-approve"
planClaude-compat alias; use real plan mode

Cycle with Shift+Tab or Ctrl+O. Set via /always-approve, /auto, /settings, --permission-mode, or [ui] permission_mode. CLI overrides config.

Even in always-approve, deny rules, hooks and some shell ask rules still apply. The escape hatch is deliberately not total — you can hand over the keys and keep a lock on the drinks cabinet.

Admins can lock the mode off. Enable per-command allowlists with [ui] remember_tool_approvals.

The sandbox

kernel-enforced

OS kernel primitives — Landlock on Linux, Seatbelt on macOS — enforced for the process lifetime, not by the agent's good intentions. Off by default.

ProfileWritesChild net
offeverywhereallowed
workspaceCWD, ~/.grok/, tempallowed
devboxall top-level except /dataallowed
read-only~/.grok/, tempblocked¹
strictCWD, ~/.grok/, tempblocked¹

¹ Child-network blocking is Linux-only (seccomp). On macOS it is a no-op — a macOS read-only profile does not stop a child process phoning home. Know this before relying on it.

Platform support

PlatformMechanismMinimum
LinuxLandlockKernel 5.13+
macOSSeatbeltall versions
Windowsnone—

No kernel sandbox on native Windows, and the failure is quiet — an unapplied profile "logs a warning and continues without enforcement." For the sandbox on Windows, run under WSL. A failed custom profile is the exception: Grok refuses to start rather than expose denied paths.

Custom profiles take a deny list with globs — **/*.pem, **/.env — kernel-enforced for read and write alike.

Sandbox first, then loosen approvals. grok --sandbox workspace --permission-mode auto is the combination worth adopting. Approvals off without a sandbox is just removing the brakes.

Plan mode

actually read-only

Read-only except the plan file. plan.md edits auto-approve; edits to any other file are rejected outright, the call failing with the plan file named as the only writable path. This holds in every permission mode, including always-approve.

/planenter; next prompt starts planning /plan <description>enter and start a turn in one step Shift+Tabone press from Normal lands on Plan /view-planreopen the saved preview

The agent can enter it itself via enter_plan_mode (needs your approval) and leaves via exit_plan_mode. The plan is written to ~/.grok/sessions/<cwd>/<session-id>/plan.md.

What a good plan contains

Context (why the change) · the recommended approach, not every alternative · paths of critical files · existing functions to reuse, with paths · a verification section describing how to test end to end.

✓ Worth planning

  • "Add authentication" — session vs JWT vs middleware
  • "Add caching" — Redis vs in-memory vs file
  • "Redesign the pipeline"

✗ Not worth it

  • "Add a delete button"
  • "Fix the typo"
  • "Update the error handling"

Planning a task that did not need planning is pure latency.

Subagents

roles & personas

Declarative rather than prose: define roles and personas as TOML and reuse them.

[subagents.roles.researcher] description = "Deep research agent" default_capability_mode = "read-only" model = "grok-build" prompt_file = ".grok/prompts/researcher.md"
CapabilityReadWriteExec
read-only✓
read-write✓✓
execute✓✓
all✓✓✓

A reviewer role at read-only cannot edit code — structural, not an instruction it might drift from. Personas (.grok/personas/*.toml) overlay tone and focus without changing the agent type or its tools, so they can never widen permissions.

spawn_subagent

prompt · descriptiontask, and a 3–5 word label subagent_typegeneral-purpose · explore · plan backgroundlaunch async, return an ID isolation: worktreeits own git worktree resume_fromcontinue a finished child

Nesting is one level. A subagent calling spawn_subagent fails with a depth-limit error — fan out from the parent, do not build trees. Subagents inherit the parent's MCP servers by default; narrow with mcpInheritance: all | none | named | except.

Use isolation: worktree whenever more than one child will write.

Skills, plugins & hooks

extension layer

Skills

Folders of markdown plus scripts. From ./.grok/skills/ (to repo root), ~/.grok/skills/, plugin skills/, and [skills] paths.

FrontmatterDoes
descriptionThe matcher — what it does and when
when-to-useExtra trigger phrases
pathsGitignore patterns gating visibility
allowed-toolsTools it may use
user-invocableAppears as /name. Default true
disable-model-invocationYou invoke it; the model cannot
grok skill search "kw"find in marketplaces grok skill install @ns/nameinstall

Plugins

Bundle skills, agents, hooks, MCP servers and LSP servers — real language intelligence, not just prompts. From ./.grok/plugins/, ~/.grok/plugins/, ~/.grok/plugins/marketplaces/, --plugin-dir. Sources via [[marketplace.sources]].

TUI modals: /plugins · /skills · /hooks · /mcps.

Hooks

Project hooks require /hooks-trust — a hook in a repo you cloned is arbitrary code execution. Plugin hooks get GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA. Hooks are the only deterministic layer: instructions are advice, a hook is a rule.

Context, sessions & memory

85%
/new · /clearfresh session /compact [note]note steers what is kept /contextbreakdown incl. fixed overhead /forkbranch into a new agent /rewind · /undoroll back a turn /dashboardlive session roster

Auto-compaction at 85% of the window; tune with [session] auto_compact_threshold_percent.

/context itemises the fixed overhead — tool definitions, the skills listing, MCP announcements. That is the honest answer to "why does a fresh session already feel full?" If you installed a lot of plugins, that is where the window went.

Memory

Experimental, off by default. GROK_MEMORY=1 or [memory] enabled; /memory on|off is session-scoped. Markdown under ~/.grok/memory/, SQLite-indexed.

Workspace identity is the origin remote (org/repo), else the directory path — so clones and worktrees of one repo share a memory directory.

Headless & ACP

automation
-p, --singlethe headless entry point -m, --modelmodel for this run -c / -r <id|title>continue / resume --fork-sessionfork instead of append --output-formatplain·json·streaming-json --tools / --disallowed-toolsallow / deny built-ins --rules <text>extra system-prompt rules

For CI the documented recommendation is always-approve plus deny rules or hooks — not because it is safe, but because there is nobody to approve, so guarantees must be structural. Pair with --sandbox and --disallowed-tools.

Agent Client Protocol

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

Drive it as a server to build your own tooling on top — and read the source when you need to.

Models & the pricing cliff

watch 200k
ModelCtxIn $/MtokOut $/Mtok
Grok 4.6500k2.00 / 4.006.00 / 12.00
Grok 4.3 / 4.201M1.25 / 2.502.50 / 5.00
Grok Build 0.1256k1.00 / 2.002.00 / 4.00

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.

  • /compact before you cross it. Auto-compaction at 85% of 500k fires at 425k — long past the cliff.
  • Watch /context — plugin overhead gets you to 200k sooner than you think.
  • Grok 4.6 is the recommended coding model. Set [models] default deliberately.

Config it already understands

adoption

Alongside its own .grok/ directories, Grok discovers and honours the instruction files and extensions other agents use — so a repository that already carries agent config needs no porting before the first useful session.

It findsWhere
AGENTS.mdRepo root — the cross-vendor standard
CLAUDE.md, Claude.md, CLAUDE.local.mdAlways recognised at top level
.claude/CLAUDE*.mdScanned root-down through directories
~/.claude/User-level Claude config
.claude/settings.jsonIncluding defaultMode
~/.cursor/, <dir>/.cursor/Cursor rules too
Marketplaces, plugins, skills, MCP servers, agentsClaude Code's, alongside .grok/

xAI's announcement puts it plainly: “Your AGENTS.md, plugins, hooks, skills, and MCP servers all work out of the box.”

The durable point: the instruction layer is becoming portable. An AGENTS.md stating your build commands, boundaries and conventions is read by every current agent worth using — time spent writing it is not a bet on a vendor.

Idioms

what pays off

The evaluation, in full

cd a-repo-you-already-use-with-claude-code grok inspect # did it find your conventions? grok # /plan a real task, read the plan

That is the whole thing. Because it reads your existing config, there is nothing to port first.

The everyday invocation

grok --sandbox workspace --permission-mode auto

Far fewer prompts than default, with the kernel still bounding the damage.

Order of operations

  • Sandbox first, approvals second. Never the reverse.
  • Capability modes over instructions. A read-only role cannot write; a polite request can be drifted from.
  • Worktree isolation the moment two children write.
  • Deny rules and hooks before always-approve — they survive it.

Give it something worth reading

The machinery operates on context. A plain-text work wiki and CLI access to your data matter more than any of the above — and neither is vendor-specific.

Public opposition to AI

the argument under the tooling

A large share of the public — in most 2025–26 polling, a plurality to a majority — says it is more worried than excited about AI. You use xAI's tools all day; it is worth being able to state the other side's case accurately, and then say why you are on this side of it anyway.

What people are worried about

  • Jobs. The fear is not abstract: entry-level software, support, translation and content roles are where hiring has visibly softened, and "learn to code" was the advice given to the last displaced cohort.
  • Training data. Models were trained on books, code and images whose authors were not asked. Courts have mostly sided with fair use so far; the authors have not changed their minds.
  • Energy, water, neighbours. Data-center electricity demand is real, concentrated, and frequently paid for through everyone's rates — the one objection that wins county votes.
  • Slop and trust. Fluent, confident, wrong text at scale: fabricated citations, AI-generated pull requests that waste maintainers' time, search results that are summaries of summaries.
  • Deskilling. If the tool writes the code, who still knows how? Juniors who never debug a thing they did not write are the worry here.
  • Concentration. A handful of companies own the frontier models, the chips and the capital. Nobody voted for that.

Why the advantages are larger

  • The productivity is measured, not claimed. Controlled studies put task completion gains for developers at roughly a third to a half on bounded work; at the high end, teams using agentic tools report output doubling. Every previous tool with that profile — compilers, IDEs, Stack Overflow — ended up with more programmers, not fewer, because cheaper software means more software gets built.
  • Access. The person who could never afford a developer, a lawyer's first read, a tutor at 11 pm, a translator, or a patient explanation of their own lab results now has one. That is the largest transfer of expert capacity to ordinary people since the public library.
  • Verification is the answer to slop — and it is a discipline, not a hope. Everything on this sheet about tests, hooks, reviewers and evidence exists because the failure mode is known and solvable. The tool that writes the bug also runs the test.
  • Learning accelerates rather than atrophies for anyone who uses it to be questioned instead of answered. The deskilling risk is real and it is a choice: a tutor that refuses to give the answer is one output style away.
  • Small teams do large things. One person with an agent fleet ships what took a department. For a hobbyist with a bench and a 3D printer that is the difference between a project finished and a project imagined.
  • The hard problems need it. Protein structure, materials, formal verification, reading every paper in a field — these are not jobs the technology takes; they are jobs nobody could do.

Where the honest ground is

  • Most objections are to allocation, not to the technology: who pays for the substation, who is compensated for the training data, who is retrained. Those are policy fights with real losers, and "the benefits are larger" is true and insufficient to the person on the losing end.
  • The energy objection gets settled by large-load tariffs and closed-loop cooling, not by arguing about it.
  • The slop objection gets settled by people who refuse to ship unverified work. Be one of them — it is the single thing a user can do for the tool's reputation.
  • The jobs objection is the one without a clean answer. The historical pattern is strongly reassuring and the people living through the transition are not wrong to be afraid of it.

Grok specifically. xAI draws two objections the others do not. The Memphis Colossus site ran dozens of gas turbines before its air permits were settled, in a neighbourhood that already carried a disproportionate pollution load — the data-center fight in its sharpest form. And the model's deliberately looser guardrails have produced public incidents (antisemitic output in July 2025, the "MechaHitler" episode, image-generation abuse) that the safety-first labs point to as the case for guardrails. Being the model that refuses least is the selling point and the liability at once.

The short version for the dinner table: the concerns are mostly legitimate and mostly about who pays; the benefits are larger, broader and already measurable; and the one thing in your control is to be a user whose output earns the tool its trust.

▾Index

every command, flag, slash command, config key and TOML field · use the search box above · click to collapse

CLI

grok

Launching

grokStart the interactive TUI in the current directory.
grok inspectWhat config, instructions, skills, plugins, hooks and MCP were discovered.
grok -p "<prompt>"Headless. Also --prompt-json and --prompt-file.
-m, --model <MODEL>Model for this run, e.g. grok-build.
-c, --continueContinue the most recent session in this directory.
-r, --resume <ID|TITLE>Resume by ID, or by title for the current directory. Scripts should use IDs.
-s, --session-id <UUID>Create a new session with this UUID. Does not resume — use -r.
--fork-sessionWith -r/-c, fork into a new session instead of appending.
--cwd <PATH>Set the working directory.
--output-format <FMT>plain · json · streaming-json · streaming-messages-json.
--include-partial-messagesRaw stream_event deltas. Only affects streaming-messages-json.
--tools <LIST>Allowlist of built-in tools. Headless only; MCP meta-tools stay.
--disallowed-tools <LIST>Denylist of built-in tools. The structural limit for CI.
--rules <TEXT>Extra system-prompt rules for this run.
--yolo · --always-approveApprove all tool executions. Deny rules and hooks still apply.
--permission-mode <MODE>Set the baseline mode. CLI overrides config for the process.
--sandbox <PROFILE>off · workspace · devbox · read-only · strict. Kernel-enforced.
--plugin-dir <PATH>Load plugins from an additional directory.

Subcommands

grok skill search "<kw>"Search marketplaces for skills.
grok skill install @ns/nameInstall a skill from a marketplace.
grok agent stdioServe over ACP on stdio — for building your own client.
grok agent serve --bind --secretServe ACP over a bound address with a shared secret.

Slash commands

in the TUI

Session

/new · /clearStart a fresh session and clear the conversation.
/resumeOpen the session picker to reload a previous session.
/compact [note]Compress history. The note steers what is kept.
/contextWindow breakdown, including what tool defs, skills and MCP announcements cost.
/session-info · /statusAuth method, model, turn count, context usage.
/forkBranch the session into a new agent, keeping history to this point.
/rewind · /undoRoll back to an earlier turn and discard everything after it.
/dashboardLive session roster: peek, reply, dispatch, pin, rename, stop, attach.
/edit-promptOpen $VISUAL/$EDITOR for the composer. Minimal mode only.

Modes & planning

/plan [description]Enter plan mode, optionally starting a turn in one step.
/view-planReopen the saved plan preview. Aliases /show-plan, /plan-view.
Shift+TabCycle Normal → Plan → Always-approve. One press from Normal gives Plan.
Ctrl+OAlso cycles the permission mode.
/always-approveSwitch to always-approve. Deny rules and hooks survive it.
/autoAuto mode: the safety check gates calls instead of you.
/settingsOpen the settings modal.

Extensions & misc

/pluginsManage plugins and browse the marketplace tab.
/skillsManage skills.
/hooksManage hooks.
/hooks-trustRequired before project hooks run. A cloned repo's hook is arbitrary code.
/mcpsManage MCP servers.
/memory on|offToggle cross-session memory. Session-scoped; does not persist to config.
/modelSwitch the model for this session.
/config-agentsManage agent definitions and personas, not sessions (that is /dashboard).
/feedbackSend bugs and requests straight to the team.
/plugin-name:skillHow a skill appears when its name collides with a built-in command.

Config & files

TOML

Locations & precedence

~/.grok/config.tomlThe user config file.
precedenceCLI → env → requirements/MDM → overlay → config.toml → managed → defaults.
managed_config.tomlOrg defaults, layered under your config.
requirements.toml / MDMOrg-enforced; overrides everything below it.
./.grok/skills/Project skills, traversed up to the repo root.
.grok/roles/*.tomlSubagent role definitions.
.grok/personas/*.tomlPersona overlays.
~/.grok/plugins/marketplaces/Where marketplace installs land.
~/.grok/memory/MEMORY.md global, plus per-workspace dirs. SQLite index.
~/.grok/sessions/<cwd>/<id>/plan.mdWhere plan mode writes. <cwd> is an encoded name, not a literal path.

Keys

[models] defaultModel for new sessions. Set it deliberately.
[models] web_searchModel used by the web_search tool.
[ui] permission_modeBaseline approval mode. CLI overrides it.
[ui] remember_tool_approvalsEnable per-command allowlists instead of re-asking.
[ui] default_selected_permissionPreselected approval row. Defaults to all-sessions; consider allow_once.
[ui] screen_mode"fullscreen" or "minimal".
[ui] simple_modetrue = readline editing; false = vim keys.
[session] auto_compact_threshold_percentAuto-compaction trigger. Defaults to 85% of the window.
[memory] enabledCross-session memory. Experimental, off by default.
[skills] pathsAdditional directories to discover skills from.
[[marketplace.sources]]Marketplace sources for plugins and skills.
[model.<name>]Custom model: model, base_url, api_key. Point at any compatible endpoint.
[auth] auth_provider_commandExternal auth binary, with auth_provider_label for the login screen.

Environment

XAI_API_KEYAPI key from console.x.ai.
GROK_HOMEOverride the config directory.
GROK_CONFIGInline JSON overlay. Allowlisted keys only: models, features, toolset.
GROK_CONFIG_PATHAdditional overlay file (.json or .toml).
GROK_MEMORY1/true enables memory, 0/false force-disables it.
GROK_WORKFLOWSToggle background workflows.
GROK_PLUGIN_ROOT / _DATAPassed to plugin hooks.

Claude Code compatibility

AGENTS.mdRead by Grok, Claude Code, Copilot, Cursor and Gemini. Not lock-in.
CLAUDE.md · CLAUDE.local.mdAlways recognised at top level.
.claude/CLAUDE*.mdScanned from repo root down through directories.
.claude/settings.jsonSupported, including defaultMode.
~/.cursor/ · <dir>/.cursor/Cursor rules are scanned too. Codex is reserved but inactive.

Skill frontmatter

descriptionThe matcher. What it does AND when to use it, or it never fires.
when-to-useExtra trigger phrases appended to the listing.
pathsGitignore-style patterns gating when the skill is even visible.
allowed-toolsTools the skill may use (declarative).
user-invocableWhether it appears as /name. Default true.
disable-model-invocationYou invoke it; the model cannot. Right for side effects.
argument-hintAutocomplete hint for arguments.

Safety

modes & sandbox

Permission modes

default (ask)Read-only tools and built-in read-only shell run without asking.
acceptEditsFile edits run without a prompt; you review diffs later.
autoThe background safety check gates calls; others blocked or escalated.
dontAskOnly pre-approved tools. For strict CI allowlists.
bypassPermissionsAlways-approve. Deny rules, hooks and some shell ask rules still apply.
deny rules survive always-approveThe escape hatch is deliberately not total.

Sandbox profiles

Landlock · SeatbeltLinux and macOS kernel primitives. Enforced for the process lifetime.
--sandbox workspaceRead everywhere; write CWD, ~/.grok/ and temp. The everyday default.
--sandbox read-onlyWrite only to ~/.grok/ and temp. For exploration and review.
--sandbox strictRead CWD + system paths only. For untrusted code.
--sandbox devboxWrites all top-level dirs except /data. For disposable dev VMs.
child-network blocking is Linux-onlyseccomp only. On macOS it is a no-op — do not rely on it.
custom deny listGlobs like **/*.pem, kernel-enforced for read and write.
no sandbox on native WindowsNot in the platform table. Run under WSL for Landlock, or rely on deny rules.
unapplied profile fails quietlyGrok warns and continues unenforced. A custom profile refuses to start.
irm x.ai/cli/install.ps1 | iexWindows install; adds %USERPROFILE%\.grok\bin to your PATH.

Plan mode guarantees

read-only except plan.mdOther edits rejected outright — every mode, always-approve included.
enter_plan_modeThe agent can request plan mode; it needs your approval.
exit_plan_modePresents the finished plan for your approval.

Subagent controls

capability modesread-only · read-write · execute · all. Structural, not advisory.
spawn_subagentprompt, description, subagent_type, background, isolation, resume_from.
isolation: worktreeIts own git worktree. Use whenever more than one child writes.
nesting is one levelA subagent spawning a child fails with a depth-limit error.
mcpInheritanceall (default) · none · named · except. Narrow what a child can reach.
resume_fromContinue a completed child's conversation, inheriting its transcript.

Models

Aug 2026

The lineup

Grok 4.6500k context, recommended for coding. $2/$4 in, $6/$12 out.
Grok 4.3 / 4.201M context. $1.25/$2.50 in, $2.50/$5 out. Reasoning variants.
Grok Build 0.1256k context. $1/$2 in, $2/$4 out.

Cost

the 200k cliffReach 200k prompt tokens and EVERY token bills at the higher rate.
compact before the cliff85% of a 500k window is 425k — long past it.
watch fixed overheadPlugins and MCP announcements get you to 200k sooner than you think.
cached inputCached input is billed well below fresh input on every model.

Don't

10 traps

Evaluation

migrating before evaluatingIt already reads your Claude Code setup. Install, inspect, prompt.
skipping grok inspect"It ignores my conventions" usually means it never found them.
planning trivial workPlan mode is for genuine ambiguity, not a clear implementation path.

Safety

approvals off, no sandboxSandbox first, then loosen. Never the reverse.
trusting macOS for networkChild-network blocking is Linux-only. macOS is a no-op.
trusting a cloned repo's hooksProject hooks need /hooks-trust. Read them first.
parallel writers, no isolationUse isolation: worktree whenever more than one child writes.
building subagent treesNesting is one level. Fan out from the parent.

Cost & config

drifting past 200kThe cliff bills all tokens higher. Compact early, watch /context.
vague skill descriptionsThe description is the matcher. Say when to use it.
docs.x.ai/build · github.com/xai-org/grok-build · August 2026