May 22, 2026 · 8 min read

Grok Build Plan Mode: Review Code Changes Before They Happen

Grok Build’s Plan Mode lets you see exactly what the agent wants to change before it touches your files. Instead of auto-applying edits (Code Mode), Plan Mode generates a complete diff, waits for your review, and only applies changes after explicit approval.

This is the feature that makes Grok Build usable for production codebases where you can’t afford blind edits. It’s similar in spirit to Claude Code’s permission-based approach, but more explicit. Here’s how to use it effectively.

For the full tool overview, see our Grok Build complete guide. For setup and first steps, check how to use Grok Build.

What Plan Mode Does

When you run Grok Build in Plan Mode, the agent:

Analyzes your request and the relevant codebase
Generates all proposed file changes as unified diffs
Displays the diffs in your terminal with syntax highlighting
Waits for you to approve, reject, or modify the plan
Only writes to disk after you confirm

No files are modified until you say so. This is fundamentally different from Code Mode, where changes are applied immediately as the agent works.

How to Activate Plan Mode

Three ways to enter Plan Mode:

1. Start in Plan Mode

# Pass the --plan flag when launching
grok build --plan "Refactor the authentication module to use refresh tokens"

2. Switch mid-session

# Inside an active Grok Build session, use the /plan command
/plan

# Now all subsequent requests use Plan Mode
# Switch back with:
/code

3. Set as default mode

# In your grok config
grok config set default-mode plan

Setting Plan Mode as default is recommended when you’re working on critical code paths or unfamiliar codebases.

What the Output Looks Like

When Plan Mode generates its proposal, you see something like this:

── Plan: Refactor auth module to use refresh tokens ──

📁 src/middleware/auth.ts
@@ -12,8 +12,15 @@
 import { verifyToken } from '../utils/jwt';
+import { verifyRefreshToken, generateTokenPair } from '../utils/jwt';

 export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
-  const token = req.headers.authorization?.split(' ')[1];
-  if (!token) return res.status(401).json({ error: 'No token provided' });
+  const accessToken = req.headers.authorization?.split(' ')[1];
+  const refreshToken = req.cookies?.refreshToken;
+
+  if (!accessToken && !refreshToken) {
+    return res.status(401).json({ error: 'No credentials provided' });
+  }

📁 src/utils/jwt.ts
@@ -1,5 +1,6 @@
 import jwt from 'jsonwebtoken';
+import { randomBytes } from 'crypto';

+export function generateTokenPair(userId: string) {
+  const accessToken = jwt.sign({ userId }, process.env.JWT_SECRET!, { expiresIn: '15m' });
+  const refreshToken = randomBytes(64).toString('hex');
+  return { accessToken, refreshToken };
+}

📁 src/routes/auth.ts (new file)
+ import { Router } from 'express';
+ import { generateTokenPair, verifyRefreshToken } from '../utils/jwt';
+
+ const router = Router();
+
+ router.post('/refresh', async (req, res) => {
+   // ... refresh token endpoint
+ });

── Actions ──
[a]pply  [r]eject  [e]dit  [s]ave plan

Plan Actions

After reviewing the diff, you have four options:

Action	Key	What it does
Apply	`a`	Writes all changes to disk
Reject	`r`	Discards the plan, no files touched
Edit	`e`	Opens the plan in your editor for manual tweaks
Save	`s`	Saves the plan to a file for later review

The edit action is particularly useful. It opens the proposed changes in your $EDITOR, letting you modify the diff before applying. Remove a hunk you don’t like, adjust variable names, or add missing error handling before the changes hit your filesystem.

When to Use Plan Mode vs Code Mode

Use Plan Mode when:

Working on production code. You need to review every change before it lands.
Refactoring critical paths. Auth, payments, data migrations. Anything where a wrong edit causes real damage.
Learning a new codebase. Plan Mode shows you what the agent thinks the code should look like, which teaches you the codebase structure.
Complex multi-file changes. When the agent touches 5+ files, reviewing the full plan catches coordination issues between files.
Pair programming with the agent. Use Plan Mode as a “suggestion engine” where you review and iterate on proposals.

Use Code Mode when:

Prototyping. Speed matters more than precision. You’ll throw it away or rewrite it anyway.
Well-tested codebases. If you have comprehensive tests, let the agent edit freely and run the test suite to catch issues.
Simple, low-risk tasks. Renaming a variable, adding a log statement, fixing a typo.
Automation pipelines. CI/CD workflows where human review isn’t practical.

Use Ask Mode when:

You just want information. “How does this function work?” or “What’s the best approach for X?”
Architecture discussions. Exploring options without committing to changes.
Code review. “Are there any bugs in this file?” without the agent trying to fix them.

Plan Mode with Subagents

Grok Build’s multi-agent architecture interacts with Plan Mode in a useful way. When subagents work in parallel, Plan Mode collects all their proposed changes and presents them as a single unified plan:

grok build --plan "Add input validation, error handling, and tests to the user API"

The agent spawns subagents for each concern, but you see one consolidated diff:

── Plan: Add validation, error handling, and tests ──

Subagent 1/3: Input validation
📁 src/validators/user.ts (new file)
📁 src/routes/user.ts (modified)

Subagent 2/3: Error handling
📁 src/middleware/errorHandler.ts (modified)
📁 src/routes/user.ts (modified)

Subagent 3/3: Tests
📁 tests/user.test.ts (new file)

── Conflicts ──
⚠️  src/routes/user.ts modified by subagents 1 and 2
    Showing merged result:
    [diff...]

── Actions ──
[a]pply  [r]eject  [e]dit  [s]ave plan

When multiple subagents modify the same file, Grok Build merges their changes and flags potential conflicts. This is where Plan Mode really shines: you can catch merge issues before they hit your codebase.

Tips for Effective Plan Mode Usage

1. Be specific in your requests

Vague prompts produce vague plans. Instead of “improve this code,” try “add input validation for email and password fields in the registration endpoint, returning 400 with specific error messages.”

2. Use /plan for risky operations, /code for safe ones

You can switch modes within a single session. Start in Code Mode for setup tasks, switch to Plan Mode for the critical changes:

/code
> Add a new migration file for the users table

/plan
> Modify the existing user model to add the new fields

3. Save plans for team review

The save action writes the plan to a .grok-plan file that you can share with teammates or attach to a PR:

# After reviewing a plan, press 's'
# Creates .grok-plan/2026-05-22-refactor-auth.diff

# Share with your team
git add .grok-plan/
git commit -m "Proposed auth refactor (Grok Build plan)"

4. Chain plans iteratively

Reject a plan, refine your prompt, and try again. Each iteration gives the agent more context about what you actually want:

grok build --plan "Add caching to the API"
# Review... too aggressive, caches everything
# Press 'r' to reject

grok build --plan "Add Redis caching only to the /products endpoint with 5min TTL"
# Review... better, apply
# Press 'a'

5. Combine with grok inspect

Use grok inspect to understand what the agent sees before asking for changes:

# See what files the agent considers relevant
grok inspect src/

# Then make your plan request with confidence
grok build --plan "Refactor the service layer based on the patterns in src/services/"

Plan Mode in CI/CD

Plan Mode works in headless pipelines too. Use it to generate proposed changes that require human approval:

# Generate a plan without interactive prompts
grok build -p "Update all dependencies to latest compatible versions" \
  --output-format streaming-json \
  --plan-only > proposed-changes.json

# In your CI pipeline, post the plan as a PR comment
# Then apply manually after review

The --plan-only flag generates the plan and exits without waiting for interactive input. Combine with --output-format streaming-json for machine-readable output.

Limitations

Plan Mode adds latency. The agent generates the full plan before showing anything. For simple tasks, this overhead isn’t worth it.
Large plans are hard to review. If the agent proposes 500+ lines of changes across 20 files, the terminal diff becomes unwieldy. Use the save action and review in your editor.
No partial apply (yet). You can’t apply some hunks and reject others from the terminal UI. Use the edit action to remove unwanted changes before applying.
Subagent conflicts require judgment. When multiple subagents modify the same file, the merged result might not be what you want. Review carefully.

FAQ

Can I set Plan Mode as the permanent default?

Yes. Run grok config set default-mode plan to make Plan Mode the default for all sessions. You can still switch to Code Mode within a session using /code.

Does Plan Mode cost more tokens?

Slightly. The agent generates the same changes but also formats them as diffs and waits for your response. The overhead is minimal (typically less than 5% extra tokens) because the actual code generation work is the same.

Can I apply only part of a plan?

Not directly from the terminal UI. Press e to edit the plan, remove the hunks you don’t want, then apply the modified plan. A per-hunk apply feature is on xAI’s roadmap.

How does Plan Mode interact with git?

Plan Mode doesn’t create commits automatically. It writes the changes to your working directory. You handle git operations yourself (or switch to Code Mode and ask the agent to commit).

Is Plan Mode available in headless mode?

Yes. Use --plan-only with the -p flag to generate plans programmatically. The output includes the full diff in structured format, suitable for CI/CD pipelines or automated review workflows.

What happens if I close the terminal during a plan review?

Nothing is written to disk. Plan Mode only applies changes on explicit approval. If you close the terminal or the session crashes, your files remain untouched.

Can subagents be configured to always use Plan Mode?

Yes. In your project’s configuration, you can set mode preferences per subagent type. This is useful when you want fast execution for tests (Code Mode) but careful review for production code changes (Plan Mode).