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

Grok Build is SpaceXAI’s new 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.

The coding agent currently supports three operating models:

Interactive sessions place the agent inside a mouse-aware terminal workspace. Headless commands turn repository tasks into 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 turn the CLI into 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 remain subject to approval.
• 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, 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 remain available for resuming, forking, searching, exporting, compacting, or rewinding.
• Background task management: Development servers, test suites, builds, subagents, monitors, scheduled prompts, and queued messages continue while the main conversation stays active.
• 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 may 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

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.

The session remains available through 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 may 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 may 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 remain 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 remains the 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.

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.

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

Headless CLI

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

grok -p "Review the current diff and list likely 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 may 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 may search the repository, inspect dependencies, identify affected files, and write a structured session plan. Project file changes still require approval. /view-plan reopens the current plan during the session.

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.

Always-approve removes interactive approval requests. Sandbox restrictions and explicit deny rules remain 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.

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 may 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 remains 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 may send the fork toward a different solution:

/fork Explore a database-backed token store instead.

Add worktree isolation when both branches may 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. 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. This design turns the terminal into a lightweight supervisor for several repository tasks.

Sessions, Rewind, Forking, and Context Management

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

Resume a specific session:

grok --resume <session-id>

Resume the most recent session for the directory:

grok --resume

Continue through the shorthand flag:

grok -c

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 still 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 remain 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 may 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 works well for 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 without discarding the active operation. A queued message may request a later test, documentation update, or review pass while the current implementation continues.

Project Rules with AGENTS.md

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

A root AGENTS.md may 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.

Temporary rules may be passed 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

A user-invocable skill appears as a slash command. The agent may 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 still needs editorial review because a successful one-time conversation may 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 may live inside the repository or the user’s 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.

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 still 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 remove <name>

Remote servers that use OAuth start an authentication flow on first use. Local credentials remain under the Grok 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 user server replaces the user definition for that workspace.

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 may 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. Grok Build also recognizes compatible Claude and Cursor hook definitions.

Hooks execute outside the model’s prose response. A small hook may enforce a policy more reliably than repeatedly explaining the same policy 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 remains the verification point because duplicate definitions may 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 may differ. Existing automation deserves a test run before production use.

Custom Models and Configuration

User 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 may use supported Responses, Chat Completions, or Messages-style APIs. Endpoint behavior, tool calling, context size, authentication, and structured output support still 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 still create network traffic when used.

Configuration Scopes

Grok Build merges configuration from several scopes:

System requirements have the highest authority in managed deployments. A root-owned requirements file may 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 may request.

Rules can target:

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

A configuration may 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.

Start a workspace sandbox:

grok --sandbox workspace

Start a stricter review session:

grok --sandbox strict

The sandbox profile is off unless the user or organization changes it.

Several credential directories remain 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 may request. A sandbox limits what an approved process may reach.

Authentication

Grok Build supports several authentication paths:

• 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 may 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 remains 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

Common Session and Execution Flags

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 model access is temporary

Alternatives & Related Resources

• 7 Best CLI AI Coding Agents (Open Source)
• Multi-Model AI Coding Agent CLI – OpenClaude
• Kimi Code CLI: Open-Source AI Coding Agent with Skills & MCP Support
• Run Multiple AI Coding Agents in Parallel – Manaflow
• The Ultimate Claude Code Resource List: Agents, Skills, Plugins & More

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 may 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 remain 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.

Q: Are Grok Build sessions stored only in the cloud?
A: The CLI stores local session history under ~/.grok/sessions/. First-party inference still sends selected prompt and repository context to the remote model service. Optional session synchronization and sharing add another remote path.