How to Use Grok Build — xAI's Terminal Coding Agent (Complete Tutorial)

xAI launched Grok Build on May 14, 2026 as an early beta — a terminal-native coding agent that reads your codebase, plans changes, edits files, runs shell commands, and coordinates parallel subagents for complex tasks. It's xAI's answer to Claude Code and OpenAI Codex CLI.

This tutorial walks you through everything: installation, authentication, Plan Mode, headless scripting, custom models, skills/plugins, and how it compares to the alternatives.

What You Need Before Starting

• macOS or Linux (Windows not supported yet)
• A SuperGrok subscription ($99/month intro, $300/month standard) or an xAI API key
• curl installed (standard on macOS/Linux)

Step 1: Install Grok Build

One command installs the grok binary:

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

On a managed or production machine, inspect the script first:

curl -fsSL https://x.ai/cli/install.sh -o grok-install.sh
less grok-install.sh
bash grok-install.sh

Verify it landed:

grok --version
which grok

⚠️ Important: An unrelated community project (superagent-ai/grok-cli) also installs a grok command. If you previously installed that, check which grok to make sure you're running xAI's agent, not the community wrapper.

Windows PowerShell install:

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

Step 2: Authenticate

Option A: Browser OAuth (recommended for personal use)

cd your-project
grok

On first launch, Grok opens your browser for authentication. Sign in with your SuperGrok/X Premium+ account.

Option B: API Key (for CI/CD, servers, automation)

export XAI_API_KEY="xai-..."
grok

Get your API key from the xAI console → API Keys → Create API Key. The key is shown once — copy it immediately.

For persistent use, add it to your shell profile or inject from your CI secret store. Never commit it to git.

Step 3: Your First Session

Navigate to a project and launch the interactive TUI:

cd ~/code/your-project
grok

Try these prompts to verify it picked up your repo:

Explain this repo.
@src/main.rs Walk me through this file.

The @path syntax pins a file into the agent's context — useful for directing attention to specific files.

Step 4: Understand the Three Modes

Grok Build has three operating modes. Press Shift+Tab in the TUI to cycle between them.

Code Mode (default)

Reads, edits, and runs commands automatically. Best for daily development when you trust the agent.

Plan Mode

The most important safety feature. The agent writes a step-by-step plan describing the change before touching any files. You review, edit, or reject the plan. Only after approval does the agent execute.

Start in Plan Mode:

grok --mode plan

Or switch mid-session:

/plan

Use Plan Mode when:

• Working on production code
• Learning how the agent works
• Reviewing complex multi-file changes
• You want to understand what the agent will do before it does it

Ask Mode

Read-only — no file modifications. Good for questions, exploration, and codebase understanding.

Always-Approve Mode

Skip permission prompts for all tool calls:

grok --always-approve

Or toggle from the TUI with /always-approve.

Set the default permission behavior in ~/.grok/config.toml:

[ui]
permission_mode = "always-approve"

Use permission_mode = "ask" (default) for prompts on each tool call.

Step 5: The Core Workflow

The practical loop looks like this:

1. Prompt. Describe the change in natural language, optionally pinning files with @path.
2. Plan. Grok proposes a step-by-step plan. Nothing is written yet.
3. Review. Approve, edit, or reject the plan. This prevents the agent from misreading your task.
4. Execute. The agent edits files and runs shell commands, delegating to parallel subagents for larger jobs.
5. Diff. Changes come back as reviewable diffs before they land.

Step 6: Use the TUI Commands

Step 7: Multi-Agent Architecture

This is Grok Build's headline feature. For complex tasks:

• A coordinator agent analyzes the task and breaks it into subtasks
• Parallel subagents spin up to handle each subtask simultaneously
• Each subagent can operate in an isolated Git worktree so concurrent edits don't collide
• The coordinator merges results and verifies integration

Example: "Add authentication to this Express app" might spawn subagents for:

• Writing the auth middleware
• Creating the user model
• Adding login/register routes
• Writing tests

Each works independently, then the coordinator reconciles conflicts.

Step 8: Headless Mode (Scripts & CI/CD)

Run Grok Build non-interactively for automation:

# One-shot prompt, print answer and exit
grok -p "Explain the architecture of this service"

# Machine-readable output for pipelines
grok -p "List every TODO and the file it is in" --output-format json

# Streaming JSON for real-time processing
grok -p "Fix all TypeScript errors" --output-format streaming-json

Common flags:

Suppress updates in automation:

grok --no-auto-update -p "Run the test suite and fix failures"

Or persist in config:

[cli]
auto_update = false

Step 9: ACP (Agent Client Protocol)

Use Grok Build as a service for IDE or tool integration:

grok agent stdio

This runs Grok as an ACP agent over JSON-RPC on stdin/stdout. External tools can:

• IDE extensions can use Grok Build as their backend
• Custom UIs can drive the agent programmatically
• Other agents can delegate tasks to Grok Build

Step 10: Custom Models

Grok Build isn't locked to Grok models. Route to any model:

# Use a specific model in headless mode
grok -p "Refactor the auth module" -m my-model

# Switch inside the TUI
/model my-model

Configure custom models in ~/.grok/config.toml:

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

You can route through OpenRouter to use Claude, GPT-5, Gemini, or any other model while still getting Grok Build's multi-agent architecture and tooling.

Step 11: Skills, Plugins & Marketplace

Skills

Reusable folders with markdown instructions, scripts, and resources. Grok discovers skills from:

• ./.grok/skills/ (walked up to repo root)
• ~/.grok/skills/
• Any enabled plugin's skills/ directory
• Extra paths in ~/.grok/config.toml under [skills] paths

User-invocable skills appear as slash commands: /<skill-name>

Plugins

Extend Grok with additional skills, agents, hooks, MCP servers, and LSP servers. Load from:

• ./.grok/plugins/
• ~/.grok/plugins/
• Marketplace installs under ~/.grok/plugins/marketplaces/

Browse and install from the TUI:

/skills
/plugins

Hooks

Run scripts on lifecycle events:

• pre-edit: Before file modification
• post-edit: After changes applied
• pre-command: Before running shell command
• post-command: After command execution
• on-error: When something fails

Configure in .grok/hooks.json:

{
  "post-edit": "npm run lint --fix",
  "pre-command": "echo 'Running: ${command}'"
}

Step 12: CLAUDE.md & AGENTS.md Compatibility

Zero-config migration from Claude Code. Grok Build reads these files natively:

• CLAUDE.md, Claude.md, CLAUDE.md.local
• .claude/rules/
• AGENTS.md, Agents.md, AGENT.md

Your existing project instructions carry over without changes. xAI also discovers user-level skills from:

• ~/.agents/skills/
• ~/.agents/commands/

Step 13: MCP Server Support

Connect to Model Context Protocol servers for external tools:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"]
    }
  }
}

Same format as Claude Code and other MCP-compatible tools.

Step 14: Use the grok-build-0.1 Model via API

The same model powering Grok Build is available directly on the xAI API:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-build-0.1",
    "input": "Refactor this function to handle null inputs."
  }'

Python (xAI SDK):

import os
from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-build-0.1")
chat.append(user("Refactor this function to handle null inputs."))
print(chat.sample().content)

Python (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_XAI_API_KEY",
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-build-0.1",
    input="Refactor this function to handle null inputs.",
)
print(response.output_text)

JavaScript (AI SDK):

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai.responses('grok-build-0.1'),
  prompt: 'Refactor this function to handle null inputs.',
});

console.log(text);

Step 15: Inspect Your Setup

Before trusting the agent with real changes, verify what it detected:

grok inspect

This shows config sources, instructions, skills, plugins, hooks, and MCP servers loaded for the current directory.

Pricing

Model specs:

• Context window: 256K tokens
• Cached input: $0.20/1M tokens
• Capabilities: function calling, structured outputs, reasoning

Comparison: Grok Build vs Claude Code vs Codex CLI

Known Issues (Early Beta)

xAI is upfront that this is rough:

• Some documented commands don't work yet
• Error handling is incomplete — agent runs can fail without clean explanations
• Subagent coordination can misfire on complex jobs
• The marketplace is sparse (early days)

Recommendation: Use Plan Mode for anything important. Review every diff before approving.

Quick Reference Card

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

# First run (browser auth)
cd your-project && grok

# Headless with API key
export XAI_API_KEY="xai-..."
grok -p "Explain this codebase"

# Plan Mode (safe)
grok --mode plan

# Inspect setup
grok inspect

# Headless CI/CD
grok -p "Fix lint errors" --output-format json --no-auto-update

# Custom model
/model my-model

# Check what the agent sees
/context

Sources

• xAI Official Docs — Getting Started
• xAI Official Docs — Modes and Commands
• xAI Official Docs — Skills, Plugins & Marketplaces
• xAI Official Docs — Headless & Scripting
• xAI Launch Announcement
• CodersEra — Grok Build CLI Install & Setup 2026
• AIMadeTools — Grok Build Complete Guide