Quick reference for Grok Build, xAI’s terminal coding agent with multi-agent architecture.

Install and authenticate

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

# Authenticate via browser OAuth
grok

# Or use API key
export XAI_API_KEY="your-key-here"
grok

Modes

Mode	Command	Description
Code	grok --mode code	Default. Reads, writes, and executes code
Plan	grok --mode plan	Generates a plan without making changes
Ask	grok --mode ask	Answer questions, no file modifications

Switch modes mid-session with /mode code, /mode plan, or /mode ask.

Slash commands

Command	What it does
/help	Show all available commands
/mode <mode>	Switch between code, plan, ask
/compact	Compress context, keep working
/clear	Reset context completely
/cost	Show token usage and cost this session
/tokens	Display current context window usage
/model	Switch model or routing strategy
/skills	List installed skills/plugins
/skill install <name>	Install a skill from the marketplace
/hooks	List active lifecycle hooks
/mcp	Show connected MCP servers
/arena	Enter Arena Mode (coming soon)
/quit	Exit Grok Build

Keyboard shortcuts

Shortcut	Action
Ctrl+C	Cancel current generation
Ctrl+C Ctrl+C	Exit Grok Build
Enter	Send message
Shift+Enter	New line in message
Tab	Accept inline suggestion
Esc Esc	Rewind to previous message
Ctrl+R	Re-run last prompt

Diagnostics

# Inspect your Grok Build setup (auth, connectivity, config)
grok inspect

Headless mode (CI/scripting)

# Single prompt, streaming JSON output
grok -p "refactor auth module" --output-format streaming-json

# Pipe output to file
grok -p "generate tests for src/utils.ts" --output-format streaming-json > output.json

# Specify mode in headless
grok -p "explain this codebase" --mode ask

# Custom model
grok -p "fix the bug in main.go" --model grok-3

Headless output formats

Flag	Output
--output-format streaming-json	Newline-delimited JSON events
--output-format text	Plain text response
--output-format json	Single JSON object on completion

Model routing

# Use specific model
grok --model grok-3

# Use custom routing (set in config)
grok --routing fast    # Routes to fastest available
grok --routing smart   # Routes to best model for task

Configuration files

File	Purpose
~/.grok/config.json	Global settings, default model, routing
.grok/config.json	Project-level overrides
CLAUDE.md	Reads natively for project context
.grok/hooks.json	Lifecycle hook definitions
.grok/skills/	Local skill definitions

Hooks (lifecycle events)

// .grok/hooks.json
{
  "pre-edit": "npm run lint",
  "post-edit": "npm run test",
  "pre-commit": "npm run typecheck",
  "on-error": "notify-send 'Grok Build failed'"
}

Available hook events: pre-edit, post-edit, pre-commit, post-commit, on-error, on-complete.

Skills/Plugins

# List marketplace skills
grok skill search "database"

# Install a skill
grok skill install @xai/postgres-migrations

# List installed
grok skill list

# Remove
grok skill remove @xai/postgres-migrations

MCP server management

# Add MCP server
grok mcp add filesystem --command "npx @modelcontextprotocol/server-filesystem /path"

# List connected servers
grok mcp list

# Remove server
grok mcp remove filesystem

Environment variables

Variable	Purpose
XAI_API_KEY	API key authentication
GROK_MODEL	Default model override
GROK_MODE	Default mode (code/plan/ask)
GROK_MCP_CONFIG	Path to MCP config file
GROK_HOOKS	Path to hooks config

Context window

• 256K token context window
• Use /tokens to check usage
• Use /compact before hitting limits
• Reads CLAUDE.md automatically for project context

Cost check

# During session
/cost

# After session (last session summary)
grok --last-cost

For the full setup walkthrough, see How to Use Grok Build.

Tips for using this cheat sheet effectively

1. Start every project with a CLAUDE.md file. Before you run your first grok command in a new repo, create a CLAUDE.md in the project root. Include your tech stack, coding conventions, test commands, and any constraints. Grok Build loads this file automatically, so every session starts with the right context. This single step eliminates most “the agent did something weird” moments.

2. Use Plan Mode before Code Mode for unfamiliar tasks. When you are unsure how Grok Build will approach a problem, run /mode plan first. Review the generated plan, adjust your prompt if needed, then switch to /mode code to execute. This two-step workflow gives you a checkpoint before any files are modified and helps you catch misunderstandings early.

3. Set up hooks for your most common post-edit actions. If you always run npm run lint or npm run test after changes, put those in .grok/hooks.json as post-edit hooks. This turns manual verification into automatic verification. You will catch issues immediately instead of discovering them minutes later when you remember to run tests.

4. Monitor your context window with /tokens. Large codebases eat through the 256K context window quickly. Check /tokens periodically during long sessions. When you are above 80% usage, run /compact to compress the context and keep working. If you wait until the window is full, you lose the ability to compact gracefully and may need to start a new session.

5. Use headless mode for repeatable tasks. Any prompt you run more than twice belongs in a script. Wrap it in grok -p "your prompt" --output-format streaming-json and save it as a shell script or Makefile target. This makes your AI-assisted workflows reproducible, shareable with teammates, and easy to integrate into CI pipelines.

6. Keep slash commands visible while learning. Print this cheat sheet or keep it open in a split pane during your first week with Grok Build. The slash commands (/compact, /cost, /tokens, /mode) are the fastest way to control the agent, but they are easy to forget when you are focused on your actual coding task. After a week of regular use, they become muscle memory.

---

FAQ

How do I check my remaining context window?

Type /tokens during any session. It shows used tokens vs. the 256K limit.

Can I use Grok Build with my own API key instead of SuperGrok?

Yes. Set XAI_API_KEY as an environment variable or pass it during grok first run. You pay per token ($1/1M input via OpenRouter).

Does Grok Build read CLAUDE.md files?

Yes, natively. If you have a CLAUDE.md in your project root, Grok Build loads it automatically as project context. No migration needed.

How do I run Grok Build in a CI pipeline?

Use headless mode: grok -p "your prompt" --output-format streaming-json. Set XAI_API_KEY as a pipeline secret. See our CI/CD guide for full examples.

What’s the difference between Plan Mode and Ask Mode?

Plan Mode analyzes your codebase and generates a step-by-step implementation plan (but doesn’t execute it). Ask Mode answers questions without reading or modifying files beyond what’s needed to answer.

How do I install skills from the marketplace?

Run grok skill search "keyword" to find skills, then grok skill install @namespace/skill-name to install. Skills extend Grok Build with domain-specific capabilities.