May 23, 2026 · 5 min read

How to Migrate from Claude Code to Grok Build (It Reads Your CLAUDE.md)

Grok Build reads CLAUDE.md natively. That single fact makes migrating from Claude Code easier than any other CLI agent switch. Your project context, coding conventions, and instructions carry over without changes.

This guide covers the full migration: what transfers automatically, what needs manual work, and where the two tools differ.

TL;DR: the fast path

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

# Authenticate
grok

# That's it. Your CLAUDE.md is already picked up.
# MCP servers need manual migration (see below).

If you only use Claude Code with a CLAUDE.md and no MCP servers, you’re done. Run grok in your project directory and start working.

What transfers automatically

Feature	Status	Notes
`CLAUDE.md`	Works as-is	Grok Build reads it natively from project root
Nested `CLAUDE.md` files	Works	Reads from subdirectories too
Project context/instructions	Works	Same format, same behavior
Code conventions in CLAUDE.md	Works	Grok Build follows them

What needs manual migration

Feature	Migration effort	Details
MCP servers	5 minutes	Different config format (see below)
Permission settings	2 minutes	Grok Build uses hooks instead
Custom slash commands	Not supported	Use skills/plugins instead
`/ultrareview`	No equivalent	Use Plan Mode for review-like analysis
Anthropic model preferences	N/A	Grok Build uses xAI models

Step 1: Install Grok Build

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

# Verify
grok --version

Step 2: Authenticate

Two options:

Option A: SuperGrok subscription ($99/mo, unlimited)

grok
# Opens browser for OAuth login

Option B: API key (pay-per-token)

export XAI_API_KEY="xai-your-key-here"
grok

Step 3: Verify CLAUDE.md is loaded

cd your-project
grok --mode ask
> "What project conventions are you following?"

Grok Build should reference the contents of your CLAUDE.md. If it doesn’t, check that the file is in the project root or a parent directory.

Step 4: Migrate MCP servers

Claude Code stores MCP config in ~/.claude/mcp.json. Grok Build uses a different location and format.

Claude Code format (~/.claude/mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

Grok Build format (~/.grok/mcp.json):

{
  "servers": {
    "filesystem": {
      "command": "npx @modelcontextprotocol/server-filesystem /home/user/projects"
    },
    "github": {
      "command": "npx @modelcontextprotocol/server-github",
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

Key differences:

Top-level key is servers instead of mcpServers
command and args are merged into a single command string
Environment variables work the same way

Or use the CLI:

grok mcp add filesystem --command "npx @modelcontextprotocol/server-filesystem /home/user/projects"
grok mcp add github --command "npx @modelcontextprotocol/server-github" --env GITHUB_TOKEN=ghp_xxx

Step 5: Replace permission controls with hooks

Claude Code has a permission system (allow/deny file edits, commands). Grok Build uses hooks for similar control:

// .grok/hooks.json
{
  "pre-edit": "echo 'Editing: $GROK_FILE'",
  "post-edit": "npm run lint --fix $GROK_FILE",
  "pre-commit": "npm run typecheck && npm run test"
}

This gives you validation at each lifecycle stage rather than upfront permission grants.

Step 6: Adapt your workflow

Claude Code workflow	Grok Build equivalent
`claude "prompt"`	`grok "prompt"`
`claude --mode plan`	`grok --mode plan`
`/compact`	`/compact`
`/cost`	`/cost`
`/model`	`/model`
`/clear`	`/clear`
Multi-file edits	Same (multi-agent parallel subagents)
`CLAUDE.md` context	Same (native support)

Key differences to know

Multi-agent architecture. Grok Build spawns parallel subagents for complex tasks. Claude Code is single-threaded. You’ll notice faster completion on multi-file refactors.

Skills/Plugins. Grok Build has a marketplace for domain-specific extensions. Claude Code doesn’t have an equivalent. Run grok skill search to explore.

Model routing. Grok Build can route to different models based on task complexity. Claude Code is locked to Anthropic models.

Context window. Grok Build has 256K tokens. Claude Code varies by model (200K for Opus, 200K for Sonnet).

Pricing. SuperGrok is $99/mo flat. Claude Code requires Max plan ($100/mo for Sonnet, $200/mo for Opus with limits). API key usage on Grok Build is $1/1M input tokens via OpenRouter.

Running both side by side

Nothing stops you from keeping both installed during transition:

# Claude Code
claude "explain this function"

# Grok Build
grok "explain this function"

Both read CLAUDE.md, so your project context stays consistent. This is a good way to compare output quality before fully committing.

Common migration issues

“CLAUDE.md not found” warning. Grok Build looks in the current directory and parent directories. Make sure you’re running grok from within your project.

MCP server connection failures. Check that the command string in Grok Build’s format includes all arguments. The most common mistake is forgetting to merge args into the command string.

Different code style in output. Grok Build follows your CLAUDE.md conventions, but the underlying model is different. You may need to add more explicit style instructions to your CLAUDE.md if output diverges from what you expect.

For a similar migration guide, see Migrate from Gemini CLI to Antigravity CLI. For the full Grok Build setup, see the complete guide.

FAQ

Do I need to rename CLAUDE.md to something else?

No. Grok Build reads CLAUDE.md as-is. Keep the filename. This means you can use both tools on the same project without maintaining separate config files.

Will my Claude Code slash commands work in Grok Build?

Most common ones (/compact, /clear, /cost, /model) have direct equivalents. Custom commands or Claude-specific ones like /ultrareview don’t exist. Use /help to see all available commands.

Is the output quality the same?

Different model, different strengths. Grok Build uses xAI’s models which excel at reasoning and structured output. For most coding tasks the quality is comparable. Run both side by side for a week to judge for your specific use case.

Can I use Grok Build with Anthropic models?

Not directly. Grok Build uses xAI models and supports custom model routing, but it’s designed around xAI’s model family. If you need Anthropic models, keep Claude Code for those tasks.

What happens to my Claude Code session history?

Session history doesn’t transfer. Grok Build maintains its own session history in ~/.grok/sessions/. Your CLAUDE.md provides the persistent project context that matters most.

Is SuperGrok ($99/mo) cheaper than Claude Code Max?

For heavy usage, yes. Claude Code Max starts at $100/mo (Sonnet) or $200/mo (Opus) with usage limits. SuperGrok is $99/mo with no token limits on the CLI. See our pricing comparison for detailed scenarios.