May 21, 2026 · 7 min read

How to Use Grok Build: Complete Beginner's Guide

Grok Build is xAI’s terminal coding agent. You type what you want in plain English, and it reads your code, makes changes, runs commands, and handles multi-file tasks. This guide walks you through everything from installation to productive daily use.

If you want the full feature breakdown, see our Grok Build Complete Guide. This article focuses on the practical “how do I actually use this” walkthrough.

Step 1: Install Grok Build

Run the installer:

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

Verify it worked:

grok --version

You should see something like grok-build 0.1.x (beta). If the command isn’t found, restart your terminal or add the install path to your shell profile.

Requirements: macOS or Linux. No Windows support yet.

Step 2: Authenticate

You have two options:

grok auth login

This opens your browser. Sign in with your X/xAI account. You need an active SuperGrok subscription ($99/month).

Option B: API key

export XAI_API_KEY=xai-your-key-here

Get your key from the xAI developer console. Add the export to your .bashrc or .zshrc to persist it:

echo 'export XAI_API_KEY=xai-your-key-here' >> ~/.zshrc
source ~/.zshrc

Step 3: Start Your First Session

Navigate to a project directory and launch Grok Build:

cd ~/projects/my-app
grok

You’ll see an interactive prompt. Type your request in plain English:

> Add input validation to the signup endpoint in src/routes/auth.ts

Grok Build will:

Read the relevant files
Plan the changes
Apply the edits
Show you what it did

That’s it. You’re using Grok Build.

Step 4: Understand the Three Modes

Grok Build operates in three modes. Knowing when to use each one will save you time and prevent unwanted changes.

Code Mode (default)

grok
# or explicitly:
grok --mode code

The agent reads, edits, and runs commands automatically. Changes are applied immediately. This is the fastest workflow but requires trust, since you’re giving the agent full autonomy over your files.

Use for: Tasks you’re confident about. Bug fixes, adding straightforward features, refactoring with clear scope.

Plan Mode

grok --mode plan
# or switch mid-session:
/plan

The agent does everything except apply changes. Instead, it shows you a diff of what it wants to do and waits for your approval. You review, then accept or reject.

Use for: Unfamiliar codebases, complex changes, anything where you want to review before committing. This is the safest mode for beginners.

Ask Mode

grok --mode ask

Read-only. The agent can read your code and answer questions but cannot modify any files or run commands.

Use for: Understanding code, asking “how does this work?”, exploring a new codebase without risk of changes.

My recommendation: Start with Plan Mode for your first few sessions. Once you trust the agent’s judgment on your codebase, switch to Code Mode for routine tasks.

Step 5: Learn the Essential Commands

These commands work inside any Grok Build session:

Command	What it does
`/plan`	Switch to Plan Mode
`/model`	Change the active model
`/compact`	Compress context (use when the session gets long)
`/clear`	Reset the conversation completely
`/cost`	Show how many tokens you’ve used and the cost

Checking costs

> /cost
Session: 45,230 input tokens, 12,100 output tokens
Estimated cost: $0.06

This is useful for tracking spend if you’re on usage-based pricing.

Switching models mid-session

> /model gpt-5
Switched to gpt-5 via OpenRouter

You can route to any model available on OpenRouter. Useful if you want Claude’s reasoning for a complex task but Grok’s speed for simple edits.

Compacting context

> /compact
Context compressed: 180K → 45K tokens

Use this when you’ve been working for a while and the session is getting slow. It summarizes the conversation history to free up token space.

Step 6: Use Grok Build Effectively

Here are patterns that work well after a week of daily use:

Be specific about file paths

> Add error handling to the fetchUser function in src/services/user.ts

Better than “add error handling to the user service.” The more specific you are about locations, the faster the agent works.

Use Plan Mode for multi-file changes

> /plan
> Refactor the authentication module to use refresh tokens. This affects src/auth/, src/middleware/, and the user model.

Review the diff before it touches multiple files. You can approve individual files or reject the whole plan.

Chain tasks in a session

Don’t start a new session for every task. Grok Build maintains context:

> Add a /health endpoint to the Express app
[agent completes]
> Now add a test for it
[agent completes, knows about the endpoint it just created]
> Also add it to the API documentation in docs/api.md

Use ask mode for exploration

grok --mode ask
> Explain how the payment processing flow works in this codebase
> What would break if I changed the User model to use UUIDs instead of auto-increment IDs?

No risk of accidental changes while you’re learning.

Inspect before starting

grok inspect

This shows you what Grok Build sees: project structure, detected languages, any CLAUDE.md or configuration files. Run it once when starting on a new project to verify the agent understands your setup.

Step 7: Set Up Project Instructions

Create a CLAUDE.md file in your project root (yes, the filename is CLAUDE.md, and Grok Build reads it natively):

# Project: My App

## Tech Stack
- Node.js 20 with TypeScript
- Express with Zod validation
- PostgreSQL with Prisma ORM
- Jest for testing

## Conventions
- Use async/await, never callbacks
- All API responses use the ResponseWrapper type from src/types/
- Tests go in __tests__/ directories next to the code they test
- Use named exports, not default exports

## Commands
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run lint` - Run ESLint

This gives Grok Build context about your project without you having to explain it every session. It’s the same format used by Claude Code, so if you switch between tools, the instructions work for both.

Step 8: Headless Mode for Automation

For scripts and CI/CD, skip the interactive session:

# Single task, no interaction
grok -p "Fix all TypeScript compilation errors" --output-format streaming-json

# Pipe output to a file
grok -p "Generate API documentation for src/routes/" --output-format streaming-json > result.json

The -p flag passes a prompt directly. Combined with --output-format streaming-json, you get structured output suitable for parsing in scripts.

Tips and Gotchas

Git commit before complex tasks. If the agent makes a mess in Code Mode, you can git checkout . to undo everything.
Use /cost regularly if you’re on API pricing. Multi-agent tasks with parallel subagents consume tokens faster than you might expect.
The multi-agent system kicks in automatically for complex tasks. You don’t need to configure it. If you see multiple subagents spawning for a simple task, your prompt might be too vague.
Model routing adds latency. Using non-Grok models through OpenRouter adds a network hop. For speed-sensitive work, stick with the default Grok model.
Skills are optional. You don’t need to install any Skills to use Grok Build effectively. The built-in capabilities (file editing, terminal, git) cover most workflows.

FAQ

Do I need a SuperGrok subscription to use Grok Build?

Either a SuperGrok subscription ($99/month) or an xAI API key with credits. There’s no free tier. The API key option is cheaper for light usage.

What languages does Grok Build support?

It works with any programming language. It’s particularly strong with TypeScript, Python, Go, and Rust based on my testing. It handles less common languages fine but with less nuanced understanding of idioms.

Can I use Grok Build in VS Code’s integrated terminal?

Yes. It’s a standard CLI tool that works in any terminal, including VS Code’s integrated terminal, iTerm2, Alacritty, or whatever you use.

How do I undo changes Grok Build made?

If you’re using git (you should be), run git diff to see what changed and git checkout . to revert everything. Or use Plan Mode to review changes before they’re applied.

Is Grok Build better than Claude Code for beginners?

The explicit Plan/Code/Ask modes make Grok Build slightly more approachable. You can start in Ask mode (zero risk), graduate to Plan mode (review everything), then move to Code mode when comfortable. Claude Code defaults to auto-applying, which can be surprising for new users.

How much does a typical coding session cost?

On API pricing, a 30-minute session with moderate file reading and editing typically costs $0.05-0.15. Heavy multi-agent sessions with large codebases can reach $0.50+. Use /cost to monitor in real-time.

Can Grok Build access the internet?

Not by default. It works with your local files and can run local commands. For internet access (APIs, documentation lookup), you’d need to configure an MCP server that provides web access.