Grok Build: SpaceXAI’s Open-source Terminal AI Coding Agent

Install Grok Build and explore its terminal UI, sessions, Plan mode, worktrees, extensions, automation commands, and security controls.

Grok Build is SpaceXAI’s open-source CLI AI coding agent with a full-screen TUI that reads the project, searches files, edits code, runs shell commands, checks web resources, and tracks work that continues beyond a single response.

Each session retains its prompts, tool calls, and file snapshots, carrying the task from initial investigation through implementation, testing, and review.

August 20, 2026: SpaceXAI expanded Grok Build from its SuperGrok Heavy Early Beta to every plan on the web, iOS, and Android. Users could describe an app, game, website, or dashboard in chat, then publish it to a grok.me link and share it on X. The update also added Remix, custom domains, GitHub export, secrets, and connectors.

The coding agent currently supports three operating models:

Interactive sessions place the agent inside a mouse-aware terminal workspace. Headless commands run repository tasks as scripts or CI jobs with plain, JSON, or streaming output. Agent Client Protocol support connects the runtime to editors and other applications through standard input and output.

Grok Build covers much more than prompt-driven file editing:

Plan mode separates architectural decisions from code changes. Subagents divide large assignments into independent sessions. Git worktrees isolate parallel changes. Background commands, monitors, recurring prompts, and a live dashboard keep long-running work visible. Skills, plugins, hooks, MCP servers, project rules, and custom model endpoints make the CLI a configurable coding-agent platform.

Key Features

  • Full-screen terminal workspace: The TUI combines the conversation, tool activity, diffs, tasks, subagents, session controls, model selection, and extension management in one terminal application.
  • Repository-aware editing: Grok Build reads directory structures, searches symbols and text, opens files, applies multi-file changes, runs commands, and inspects Git state from the current working directory.
  • Plan mode: A separate planning state keeps the proposed implementation visible while project file changes stay subject to approval. During plan approval or preview, press y to copy the complete plan as Markdown.
  • Subagent execution: Independent child sessions handle research, implementation, review, and other task segments in parallel.
  • Git worktree sessions: Parallel sessions receive separate working directories and branches, protecting each agent’s file state from concurrent edits elsewhere.
  • Agent Dashboard: A live overview groups sessions by status, summarizes the previous turn, surfaces questions and approval requests, accepts replies, and dispatches new work to regular directories or worktrees.
  • Persistent sessions: Prompts, responses, tool calls, and file snapshots stay available for resuming, forking, searching, exporting, compacting, or rewinding. Large forks and resumes use less memory, and grok --resume accepts a session title as well as an ID.
  • Background task management: Development servers, test suites, builds, subagents, monitors, scheduled prompts, and queued messages continue while the main conversation stays active. The CLI can recover from repetitive model-output loops by default.
  • Headless automation: Single-prompt commands support scripts, bots, CI jobs, structured output, session continuation, turn limits, explicit permissions, and constrained JSON responses.
  • ACP integration: grok agent stdio exposes the runtime as an Agent Client Protocol server over JSON-RPC.
  • Project instruction discovery: Repository conventions, architecture notes, build commands, and package-specific rules load from AGENTS.md and compatible instruction formats.
  • Extensible agent system: Skills, plugins, custom agents, hooks, LSP servers, and MCP integrations add reusable workflows and external tools.
  • Claude Code and Cursor compatibility: Grok Build reads several existing instruction, skill, plugin, hook, marketplace, and MCP formats from those ecosystems.
  • Custom model configuration: Named model profiles point the agent runtime at first-party or third-party endpoints through configurable API backends.
  • Permission and sandbox controls: Tool policies govern requested actions, while sandbox profiles restrict filesystem and process capabilities at the operating-system level.

How to Install Grok Build

macOS, Linux, WSL, or Git Bash

curl -fsSL https://x.ai/cli/install.sh | bash

Windows PowerShell

irm https://x.ai/cli/install.ps1 | iex

NPM Distribution

Managed environments can install the packaged CLI through npm:

npm install -g @xai-official/grok

Confirm the installed binary:

grok --version

Start authentication explicitly when needed:

grok login

Remote terminals can use device authentication:

grok login --device-auth

Your First Grok Build Workflow

Open the repository:

cd path/to/project
grok

Type /tutorial to open Grok Build’s optional nine-topic onboarding tour.

Begin with a bounded inspection task:

Map the repository architecture.
Identify:
- application entry points
- major packages
- build and test commands
- external services
- generated code
- areas with missing tests
Do not edit files.

Review the response, then open Plan mode for a real change:

/plan Add rate limiting to the public API.
Inspect the current request path, choose the correct integration point, identify configuration changes, and list the required tests.

Revise the plan until its file scope and acceptance criteria are clear.

Approve implementation, then request verification:

Run the relevant tests and lint checks. Review the final diff for unrelated changes, missing error handling, and incomplete test coverage.

Check Git state before ending the session:

Show the changed files, summarize each change, and list any unresolved risks.

Reopen the session with grok -c after leaving the TUI.

How Grok Build Handles a Coding Task

A Grok Build session follows an agent loop tied to the repository on disk.

1. It loads the working context

The current directory determines the repository, project rules, local configuration, skills, plugins, hooks, MCP servers, and saved sessions that belong to the workspace.

A prompt can reference a file directly:

@src/auth/session.ts Trace the authentication flow and identify every caller.

The agent then reads related files, searches the repository, and inspects surrounding code before proposing or applying changes.

2. It chooses tools during the task

Repository work can call file-reading, search, editing, terminal, Git, web, MCP, or plugin tools. Permission rules evaluate each request before execution. Tool output returns to the same conversation and becomes part of the ongoing task context.

3. It records work as a session

The session stores the conversation and file snapshots under ~/.grok/sessions/. A later terminal, headless process, or ACP client can continue the same work.

4. It tracks unfinished operations

Builds, servers, monitors, subagents, and queued prompts stay attached to the session. The task pane and dashboard show which work is active, blocked, idle, completed, or failed.

5. It supports review and recovery

Diffs expose code changes during implementation. Rewind restores the conversation and files to an earlier prompt boundary. Git provides a safer permanent record for valuable work because rewind removes later file changes from disk.

Interactive TUI, Headless Mode, and ACP

Grok Build uses the same underlying runtime across three interfaces, but each interface fits a different workflow.

ModeInvocationTypical Role
Interactive TUIgrokRepository exploration, implementation, review, and multi-agent supervision
Headless CLIgrok -p "..."CI, scripts, bots, scheduled checks, and machine-readable tasks
ACP agentgrok agent stdioEditor integration and application-controlled agent sessions

Interactive TUI

Running grok opens a full-screen terminal application. The interface contains scrollback, prompt input, tool cards, diffs, task panels, extension controls, session navigation, and the Agent Dashboard.

Automatic theme detection works through SSH and tmux, and Markdown tables reflow inside narrow cells. Typing exit or quit from the Dashboard closes the CLI.

The terminal accepts mouse input and keyboard navigation. Common controls include:

KeyAction
Shift+TabCycle Normal, Plan, and approval modes
Ctrl+BOpen background tasks
Ctrl+;Open the prompt queue
Ctrl+SOpen sessions
Ctrl+LOpen extensions
Ctrl+\Open the Agent Dashboard
EscCancel the current turn
Esc EscOpen rewind from an empty prompt
Ctrl+GMove a foreground command to the background

Headless CLI

Headless mode sends one prompt and returns output through standard streams:

grok -p "Review the current diff and list possible regressions"

The output format controls how another process consumes the result:

grok -p "List unresolved TODO comments" \
  --output-format json
grok -p "Explain the service architecture" \
  --output-format streaming-json

plain returns readable text. json emits one final object. streaming-json emits newline-delimited events as the task progresses.

A JSON Schema can constrain the final response for downstream automation:

grok -p "Audit the changed API routes" \
  --output-format json \
  --json-schema audit-schema.json

Headless sessions use the same storage system as interactive work. A script can start a task, capture its session ID, then resume it during another stage.

ACP Agent Mode

The ACP entry point runs over JSON-RPC through standard input and output:

grok agent stdio

An editor or host application manages the visible interface. Grok Build manages the session, repository tools, project context, permissions, model calls, and task state.

Plan Mode and Approval Modes

Plan mode places a review step between repository analysis and implementation.

Enter it from the TUI:

/plan Migrate the REST API from Express to Fastify

The agent can search the repository, inspect dependencies, identify affected files, and write a structured session plan. Project file changes require approval. /view-plan reopens the current plan during the session.

During plan approval or preview, press y to copy the complete plan as Markdown.

A useful plan request includes the expected outcome and the decisions that need investigation:

Plan the migration from session cookies to rotating JWT authentication.
Cover:
- affected middleware and routes
- token storage and rotation
- database changes
- test updates
- deployment order
- rollback path

The execution mode controls how Grok Build handles tool approvals.

ModeBehavior
PlanFocuses on planning and restricts normal write flow
AskPrompts before actions that require approval
Always-approveExecutes requested tools without interactive prompts
Accept editsApproves file edits while retaining prompts for shell commands
Don’t askDenies actions that lack an explicit allow rule

Always-approve removes interactive approval requests. Sandbox restrictions and explicit deny rules are separate controls.

Unattended jobs need stricter policies than an interactive development session. A CI review can use dontAsk, grant a narrow set of commands, and deny destructive operations:

grok -p "Review the API changes and run approved checks" \
  --permission-mode dontAsk \
  --allow 'Bash(git *)' \
  --allow 'Bash(cargo check*)' \
  --allow 'Read' \
  --allow 'Grep' \
  --deny 'Bash(git push*)' \
  --deny 'Bash(rm -rf *)'

Deny rules take priority over allow rules. Command chains are evaluated by segment, which prevents an approved read command from carrying an unapproved destructive command in the same shell expression. Permission prompts display the complete script; press Ctrl+F to expand a long Bash body before approving it.

Subagents, Worktrees, and the Agent Dashboard

Large coding tasks often contain several independent investigations. Grok Build represents these branches of work as subagents and peer sessions.

A parent session can delegate tasks such as:

  • tracing an authentication flow
  • examining database migrations
  • updating tests
  • reviewing a proposed patch
  • checking documentation or external APIs
  • identifying regressions in a separate package

Each subagent receives its own conversation context. The parent sees its status and receives its result after completion.

Git Worktree Isolation

Parallel file editing becomes risky when several agents share one working directory. Grok Build addresses this with worktree sessions.

Start an isolated session from the shell:

grok -w

Name the worktree and assign a task:

grok --worktree=auth-refactor "Refactor the authentication middleware"

Choose the base reference:

grok -w --ref main "Fix the intermittent integration test"

A worktree session lives under:

~/.grok/worktrees/<repository>/<name>

It starts from the selected Git state and receives an isolated working directory. Worktrees created from the current state include uncommitted changes. A clean --ref start uses the selected branch, tag, or commit.

The worktree is a normal Git checkout. Review its changes, create commits, push the branch, or merge it through the team’s existing Git process.

Worktrees persist after their sessions end. Cleanup requires an explicit command:

grok worktree list
grok worktree show <id>
grok worktree rm <id>
grok worktree gc --max-age 7d

Forking a Session

/fork copies the current conversation into a peer session. A directive can send the fork toward a different solution:

/fork Explore a database-backed token store instead.

Add worktree isolation when both branches will edit files:

/fork --worktree Implement the alternative design in an isolated branch.

Forking preserves the shared history up to the split. Each branch then develops its own tool activity, changes, and conclusions.

Agent Dashboard

The Dashboard presents all sessions in a full-screen control view:

grok dashboard

It is also available through /dashboard or Ctrl+\.

Sessions appear under states such as:

  • Needs input
  • Working
  • Idle
  • Inactive
  • Completed
  • Failed

Selecting a session opens a live preview of its latest activity, and each Dashboard row summarizes what the agent did in the previous turn. A reply sent to an idle session arrives immediately. A reply sent to a busy session enters its prompt queue. Permission questions can be answered from the Dashboard without opening the full conversation.

The bottom input bar starts a new session. Directory and worktree controls determine where the new agent operates. The terminal acts as a lightweight supervisor for several repository tasks.

Sessions, Rewind, Forking, and Context Management

Every interaction creates a persistent session tied to the working directory.

The UI now appears immediately on cold starts while models and settings continue loading in the background. Large session forks and resumes also use less memory.

Resume a specific session by its ID or title:

grok --resume <session-id>

Resume the most recent session for the directory:

grok --resume

Continue through the shorthand flag:

grok -c

Remote resume restores the conversation only. Add --restore-code when the resumed session must also restore its saved code state. Grok leaves the working tree unchanged unless you pass that flag.

Headless automations can assign a UUID with --session-id. Resuming with --fork-session copies the prior context into a new session ID.

Session Search and Export

The CLI includes commands for reviewing past work:

grok sessions list
grok sessions search "authentication migration"
grok sessions delete <session-id>
grok export <session-id> migration-review.md

An exported transcript creates a Markdown record of the conversation. File changes belong in Git.

Rewind

/rewind lists restoration points based on previous prompts. Choosing a point restores the conversation and tracked file state to that moment.

Rewind modifies files on disk. Changes created after the selected point disappear unless Git or another backup contains them. Commit valuable changes before using it as an experimental rollback tool.

Context Compaction

Long sessions eventually approach the model’s context limit. /compact summarizes earlier conversation history and retains a shorter working state.

Optional instructions can protect important details:

/compact Preserve the approved architecture, unresolved test failures, and rollout constraints.

/context reports context usage. Automatic compaction also runs as the session grows.

Compaction concerns conversation history. Session snapshots, background tasks, and repository files are separate parts of the runtime.

Background Tasks, Loops, Monitors, and Prompt Queues

Repository agents often start operations that outlive a model response. Grok Build tracks these operations as first-class session objects.

Background Commands

Development servers, builds, tests, and other long-running commands can run in the background. Ctrl+B opens the task pane. /tasks inserts a task summary into the conversation.

A foreground process can move to the background with Ctrl+G. Selecting a task and pressing x stops it.

This fits commands such as:

npm run dev
cargo test --workspace
docker compose up
pytest -x

The agent can return to their output after working on another part of the task.

Scheduled Prompts

/loop repeats an agent request at a specified interval:

/loop 5m Check whether the test suite passes and report new failures.

The scheduler accepts seconds, minutes, hours, and days, with a minimum interval of 60 seconds. Each run creates a new agent turn. Current loops expire after seven days, and the scheduler caps the number of active entries. A loop can include a stop condition so a recurring task ends when its work is complete.

A loop handles periodic state checks. It is a poor fit for a noisy real-time log.

Monitors

A monitor connects a script or event stream to the conversation. Each output line becomes a notification.

Examples include:

  • watching deployment logs
  • tracking a CI job
  • detecting changes on a port
  • observing a file-generation pipeline
  • waiting for an external process to reach a known state

Monitor scripts should emit only meaningful events. Every line interrupts the session.

Prompt Queue

New prompts sent during an active turn enter a queue. The current task keeps running, and the queued instructions wait in order.

Ctrl+; opens the queue panel. /queue prints its current contents.

This supports mid-task direction while the active operation continues. Queued prompts stay visible while Grok waits for subagents, and slash-command or image rows can be reordered before they run. Rapid send-now actions retain earlier queued messages.

Project Rules with AGENTS.md

Grok Build loads repository instructions into each session before work begins.

A root AGENTS.md can contain:

# Project Rules
- Use TypeScript for application code.
- Run `npm test` before completing a task.
- Keep API handlers under `src/routes/`.
- Use Zod for request validation.
- Do not modify generated files under `src/generated/`.

Nested files add package-specific rules:

my-monorepo/
├── AGENTS.md
└── packages/
    ├── frontend/
    │   └── AGENTS.md
    └── backend/
        └── AGENTS.md

A session inside packages/frontend/ receives the repository rules and the frontend rules. Deeper files take priority when instructions conflict.

Grok Build recognizes several instruction formats:

  • AGENTS.md
  • Agents.md
  • AGENT.md
  • CLAUDE.md
  • Claude.md
  • CLAUDE.local.md
  • Markdown files under .grok/rules/
  • Markdown files under .claude/rules/
  • Markdown files under .cursor/rules/

Rule files load in full. Concise instructions protect the context budget and reduce conflicts.

You can pass temporary rules for one session:

grok --rules "Use TypeScript. Do not edit database migrations."

--system-prompt-override replaces the normal system prompt and requires greater care.

Inspect the effective project configuration before starting a sensitive task. The report identifies loaded rules, skills, plugins, hooks, MCP servers, compatibility settings, and their origins.

grok inspect

Skills, Plugins, Marketplaces, MCP Servers, and Hooks

Grok Build’s extension system operates at several levels. Each level solves a different type of customization problem.

Skills

A skill packages reusable instructions, scripts, and supporting files for a repeated task.

Grok Build discovers skills from:

./.grok/skills/
~/.grok/skills/
enabled plugin skill directories
additional configured skill paths

An invocable skill appears as a slash command. The agent can also select a skill when the current task matches its purpose.

Examples include:

  • preparing a release
  • reviewing database migrations
  • generating API documentation
  • checking accessibility
  • running a repository-specific deployment process

/skillify converts an existing session into a starting point for a reusable skill. The generated result needs editorial review because a successful one-time conversation can contain assumptions that do not belong in a general workflow.

Plugins

A plugin bundles several extension types:

  • skills
  • custom agents
  • slash commands
  • hooks
  • MCP servers
  • LSP servers

Local plugins can live inside the repository or your Grok directory. Marketplace plugins install under the configured marketplace storage path.

Manage them from the CLI:

grok plugin list
grok plugin install <plugin>
grok plugin update <plugin>
grok plugin disable <plugin>
grok plugin details <plugin>
grok plugin validate <path>

The TUI combines plugins, hooks, skills, and MCP servers in one extensions modal. The modal sorts items alphabetically and places skills in collapsible sections for quicker navigation through larger installations.

A plugin expands the agent’s code and data access. Review its manifest, commands, hooks, server definitions, and external connections before enabling it in a sensitive repository.

Marketplaces

A marketplace is a configured source of plugins. The TUI contains a Marketplace tab, while the CLI manages sources directly:

grok plugin marketplace list
grok plugin marketplace add <source>
grok plugin marketplace update

Marketplace installation reduces setup work across related integrations. Trust belongs to each installed package and its dependencies.

MCP Servers

Model Context Protocol servers expose external tools beside Grok Build’s built-in tools. Their names follow the pattern:

<server>__<tool>

Add a local stdio server:

grok mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Add a remote HTTP server:

grok mcp add --transport http \
  linear https://mcp.linear.app/mcp

Add a static authorization header:

grok mcp add --transport http \
  internal-api https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${API_TOKEN}"

Inspect and diagnose servers:

grok mcp list
grok mcp doctor
grok mcp enable <name>
grok mcp disable <name>
grok mcp remove <name>

Remote servers that use OAuth start an authentication flow on first use. Grok stores local credentials under its configuration directory.

Project-scoped MCP definitions live in .grok/config.toml. Grok Build also reads common Claude and Cursor MCP files. A project server with the same name as a personal server replaces the personal definition for that workspace.

Invalid MCP entries in config.toml no longer prevent Grok Build from starting. Run grok inspect to identify configuration problems.

Project MCP and LSP servers belong to the repository trust boundary. Review them before granting folder trust.

Hooks

Hooks run a shell command or call an HTTP endpoint during session and tool lifecycle events.

Common applications include:

  • blocking unsafe commands
  • logging tool calls
  • formatting changed files
  • validating generated code
  • notifying an external service
  • starting a review after a subagent completes

A PreToolUse hook can block execution. Post-use hooks observe successful or failed operations. Other events cover session start, session end, prompts, permission denials, notifications, and subagent activity.

A project hook requires explicit folder trust. Hooks can be defined in config.toml or compatible JSON files. Grok Build also recognizes compatible Claude and Cursor hook definitions.

Hooks execute outside the model’s prose response. A small hook can enforce a policy more reliably than repeated instructions in prompts.

Claude Code and Cursor Compatibility

Grok Build reads several existing configuration families from other agent environments.

Claude Code compatibility covers:

  • instruction files
  • rules
  • skills
  • agents
  • hooks
  • plugins
  • marketplaces
  • MCP servers

Cursor compatibility covers relevant rule, hook, and MCP configuration files.

The compatibility layer reduces migration work for repositories that already store agent instructions and integrations alongside the source code. grok inspect is the verification point because duplicate definitions can merge, override one another, or arrive from several directories.

Compatibility does not make every behavior identical. Tool names, model behavior, permission semantics, terminal controls, and plugin assumptions can differ. Test existing automation before production use.

Custom Models and Configuration

Personal settings live in:

~/.grok/config.toml

Windows uses:

%USERPROFILE%\.grok\config.toml

GROK_HOME selects another configuration directory.

A custom model profile should look like this:

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "My Coding Model"
env_key = "MODEL_API_KEY"
api_backend = "responses"
[models]
default = "my-model"

The backend can use supported Responses, Chat Completions, or Messages-style APIs. Endpoint behavior, tool calling, context size, authentication, and structured output support depend on the selected provider.

A compatible localhost endpoint fits the same model profile:

[model.local-coder]
model = "local-model-name"
base_url = "http://127.0.0.1:11434/v1"
name = "Local Coder"
env_key = "LOCAL_API_KEY"
api_backend = "chat_completions"

Inspect the loaded model:

grok inspect
grok models

Select it from the shell:

grok -m local-coder

Select it inside the TUI:

/model local-coder

Custom inference does not automatically localize the complete workflow. Web search, remote MCP servers, marketplace downloads, remote hooks, update checks, and session-sharing services create network traffic when used.

Configuration Scopes

Grok Build merges configuration from several scopes:

ScopeTypical LocationPurpose
EnvironmentGROK_* variablesSession and CI overrides
Personal~/.grok/config.tomlPersonal settings
Project.grok/config.tomlShared MCP, plugin, and permission rules
Managed~/.grok/managed_config.toml or /etc/grok/managed_config.tomlOrganization defaults
Requirements~/.grok/requirements.toml or /etc/grok/requirements.tomlPinned policies

System requirements have the highest authority in managed deployments. A root-owned requirements file can lock authentication, sandbox, permission, telemetry, plugin, and marketplace policies.

Permissions, Sandboxing, and Data Boundaries

Grok Build separates model requests, local tool execution, permission decisions, and operating-system restrictions.

Permission Rules

Permissions decide which tools the model can request.

Rules can target:

  • shell commands
  • file edits
  • file reads
  • repository searches
  • MCP tools
  • web fetches

A configuration can allow Git inspection while denying every other shell command:

[permission]
rules = [
  { action = "allow", tool = "bash", pattern = "git status*" },
  { action = "allow", tool = "bash", pattern = "git diff*" },
  { action = "allow", tool = "read" },
  { action = "deny", tool = "bash", pattern = "*" }
]

Commands such as rm, permission changes, process termination, and git push receive special treatment in approval-based sessions. Always-approve mode removes those prompts unless an explicit rule blocks the operation.

Sandbox Profiles

The sandbox restricts process access after Grok Build starts.

ProfileFilesystem and Child NetworkTypical Role
offUnrestricted filesystem; network allowedNo sandbox
workspaceWrites limited to the workspace, temp, and Grok data; network allowedNormal development
devboxBroad writes with protected data paths; network allowedCloud development boxes
read-onlyMinimal writes outside temp and Grok data; child network blocked on supported Linux systemsReview and audit
strictReads and writes constrained around the workspace; child network blocked on supported Linux systemsUntrusted repositories

Start a workspace sandbox:

grok --sandbox workspace

Start a stricter review session:

grok --sandbox strict

The sandbox profile is off unless you or your organization changes it.

Several credential directories are write-protected across profiles, including SSH, GnuPG, cloud-provider, and Grok authentication paths.

Linux applies child-process network restrictions through kernel controls in the restrictive profiles. macOS applies filesystem sandboxing through Seatbelt, but the current implementation does not enforce the same child-network block.

Permissions and sandboxing address different risks. A permission rule limits the actions the agent can request. A sandbox limits what an approved process can reach.

Authentication

Grok Build supports several authentication paths:

Authentication and feature gating also support the SuperGrok Plus subscription tier.

  • interactive account login
  • device-code login
  • external organization authentication
  • API keys

Device authentication fits SSH sessions, containers, and remote development environments:

grok login --device-auth

CI commonly supplies an API key through an environment variable:

export XAI_API_KEY="xai-..."

Managed deployments can require a specific identity provider or team and reject personal credentials.

Local and Remote Data

The repository tools run on the host machine. File reads, edits, shell commands, Git operations, and local MCP processes execute in that environment.

First-party model inference sends the assembled prompt and selected file context over an encrypted connection to the inference service. Responses stream back to the local session. Local session history stays under ~/.grok/.

Remote session synchronization and share links use an additional service. Blocking that service keeps sessions local to the machine but removes sharing and remote restoration.

Zero Data Retention applies only to qualifying teams or enterprise environments where the setting is active. A local session directory does not prove that inference stayed on the device.

A custom local model endpoint changes the inference destination. External tools and integrations retain their own data paths.

Headless Workflows for CI and Scripts

Review a Pull Request Diff

grok -p "Review the current diff for regressions, security issues, and missing tests" \
  --output-format json \
  --sandbox read-only \
  --permission-mode dontAsk \
  --allow 'Read' \
  --allow 'Grep' \
  --allow 'Bash(git diff*)' \
  --allow 'Bash(git status*)'

Generate a Structured Repository Report

grok -p "Audit this repository against the supplied schema" \
  --output-format json \
  --json-schema repository-audit.json

Continue a Multi-Step Automation

Start a session and capture its ID:

SESSION_ID=$(
  grok -p "Inspect the migration and propose a test plan" \
    --output-format json |
  jq -r '.sessionId'
)

Resume during the next stage:

grok --resume "$SESSION_ID" \
  -p "Run the approved checks and summarize the failures" \
  --output-format json

Disable Update Checks in Automation

grok --no-auto-update \
  -p "Check the generated API client" \
  --output-format json

Unattended automation should pin the CLI version, model, permissions, sandbox profile, working directory, and expected output structure.

Core CLI Reference

Main Commands

CommandPurpose
grokStart the interactive TUI
grok loginAuthenticate
grok logoutClear cached authentication
grok inspectShow effective configuration
grok doctorDiagnose terminal, tmux, clipboard, keyboard, and environment issues
grok modelsList available models
grok mcpManage MCP servers
grok pluginManage plugins
grok plugin marketplaceManage marketplace sources
grok sessionsList, search, or delete sessions
grok exportExport a session transcript
grok importImport supported external sessions
grok memory clearClear workspace or global memory
grok worktreeManage Grok worktrees
grok dashboardOpen the Agent Dashboard
grok agent stdioStart the ACP agent
grok wrapRun a command with terminal clipboard support
grok updateCheck or install CLI updates
grok completionsGenerate shell completions
grok setupInstall managed configuration

Common Session and Execution Flags

FlagPurpose
--cwd <PATH>Set the working directory
-r, --resume [ID]Resume a session
-c, --continueContinue the latest directory session
-s, --session-id <UUID>Assign a session ID
--fork-sessionFork a resumed session
-w, --worktree [NAME]Start in a new worktree
--ref <REF>Choose the worktree base
-m, --model <MODEL>Select a model
-p, --single <PROMPT>Run a headless prompt
--output-format <FORMAT>Select plain, JSON, or streaming JSON
--json-schema <FILE>Constrain structured output
--permission-mode <MODE>Select a permission policy
--allow <RULE>Add an allow rule
--deny <RULE>Add a deny rule
--sandbox <PROFILE>Select a sandbox profile
--no-auto-updateSkip background update checks
--no-planDisable planning behavior
--no-subagentsDisable subagent delegation
--no-memoryDisable memory use
--disable-web-searchRemove web-search access

Run the built-in help for the complete command surface:

grok --help
grok <subcommand> --help

Pros

  • Full-screen terminal agent workspace
  • Interactive, headless, and ACP modes
  • Parallel Git worktree sessions
  • Persistent sessions with rewind
  • Fine-grained permission policies
  • Multiple sandbox profiles
  • Apache-licensed Rust runtime

Cons

  • Remote inference receives selected context
  • Sandbox defaults to off
  • Worktrees persist after sessions
  • Extensions expand the trust surface
  • Free access has lower usage limits than paid SuperGrok plans

Alternatives and Related Resources

Changelog

August 7, 2026: Grok Build 1.0.0 changed remote resume to restore the conversation only by default. Pass --restore-code when you also need the saved code state.

FAQs

Q: Does deleting a Grok Build session remove its worktree?
A: No. Session deletion leaves the worktree directory and Git checkout in place. Remove it through grok worktree rm, then run grok worktree gc to clear stale tracking entries.

Q: Can Grok Build reuse an existing Claude Code setup?
A: Grok Build reads many Claude Code instruction files, rules, skills, agents, plugins, marketplaces, hooks, and MCP configurations. Run grok inspect to confirm which files loaded and which configuration has priority.

Q: Can Grok Build run with a local model?
A: A custom model profile can point to a compatible localhost endpoint. The endpoint needs a supported API format and suitable tool-calling behavior. Web search, remote MCP servers, plugins, updates, and sharing use separate network paths.

Q: Does the strict sandbox block network access on macOS?
A: The restrictive profiles block child-process networking through Linux kernel controls. The current macOS sandbox restricts filesystem access but does not enforce the same child-network block.

Leave a Reply

Your email address will not be published. Required fields are marked *

Get the latest & top AI tools sent directly to your email.

Subscribe now to explore the latest & top AI tools and resources, all in one convenient newsletter. No spam, we promise!