Explainer

Build vs Plan mode: when to let your AI agent think before it edits

You hand an AI agent a vague task — "add rate limiting to the API" — and hit enter. It immediately starts editing. Twelve files later it hands you a 400-line diff that touches your auth middleware, invents a config format, and renames a function you didn't ask it to touch. Now you're not reviewing a change; you're doing forensics on one. The problem isn't that the agent is bad. It's that you let it commit to an approach before you'd seen the approach.

That's the whole reason modern coding agents split into two modes. Plan mode reads, greps, and outlines what it intends to do — without writing a single line to disk. Build mode makes the edits. Used together they turn "wait and see what it does" into "approve the approach, then watch it execute." Here's how each one works and when to reach for it.

What each mode actually does

The split is about permission to write, not about how smart the agent is. Both modes use the same model and read the same files. The difference is the guardrail.

• Plan mode is read-only. The agent can open files, search the codebase, run read-only commands, and reason out loud — but it can't edit, create, or delete anything. Its output is a proposal: the files it intends to change, the approach, and the order of steps.
• Build mode is read-write. Now the agent applies edits, creates files, and runs commands that change state. This is where work actually lands on disk.

In Claude Code, Plan mode is a first-class state you toggle into, and it presents a plan for your approval before it touches anything. The keybinding that cycles modes shifts between releases, so confirm the current one in the official docs rather than trusting an old tutorial. Cursor's agent and others have their own framing of the same idea. The label varies; the contract doesn't. Plan looks, Build changes.

Why Plan saves you from bad diffs

The cost of a wrong decision in an agent run isn't linear — it compounds. If the agent picks the wrong abstraction in step one, every edit after that builds on the mistake. By the time you see the diff, unwinding it means understanding everything it did and why. Reviewing a 12-file change to find the one bad assumption is genuinely harder than writing the change yourself.

A plan moves the review to the cheapest possible moment. A plan is a paragraph and a file list — you can read it in fifteen seconds and catch the disaster before it exists:

• Wrong file. It's about to edit the legacy module you're deprecating, not the new one. Obvious in the plan, invisible until too late in a diff.
• Wrong scope. You asked for one endpoint; the plan says it'll refactor the whole router. Catch it now, not after.
• Missing context. The plan reveals it never found your existing helper and is about to reimplement it. You point it at the file and the build goes straight.

This is the same principle behind keeping a tight loop in vibe coding — small, reviewable steps beat one giant leap. Plan mode just moves the brake to before the edit instead of after.

The plan-then-build workflow

The pattern that works is boring and reliable. Start in Plan for anything non-trivial, read the proposal, then switch to Build once the approach is right.

• Open in Plan for fuzzy or large tasks. Anything where you're not sure how the agent will interpret it, or where it'll touch more than a file or two.
• Read the plan, push back in words. "Use the existing RateLimiter in middleware/, don't add a new dep." Revising a plan is a sentence; revising a diff is a cleanup job.
• Switch to Build when it's right. Now the agent executes a plan you already agreed to, so the diff holds few surprises.
• Skip Plan for the trivial stuff. "Fix this typo," "bump the version" — going straight to Build is faster and there's nothing to get wrong.

A rough heuristic: if you could describe the change in one sentence and you'd recognize a wrong version instantly, go straight to Build. If you'd have to read the result carefully to know whether it did the right thing, plan first. The bigger and blurrier the task, the more a plan pays for itself.

Plan mode and running unattended

There's a tension worth naming. The point of an agent is that you can walk away from it — but Plan mode is a checkpoint that waits for you. If you start a plan and tab over to something else, the agent sits there with a proposal and no one to approve it, which is exactly the dead time you were trying to kill by running it in the background.

The resolution is a notification, not abandoning Plan mode. You want the agent to plan, then ping you the moment the plan is ready — the same way it should ping you when a build finishes or hits a permission prompt. Make that approval moment loud instead of silent and Plan stays valuable, precisely because you don't have to babysit the gap between "plan ready" and "you noticed." That's the whole idea behind not babysitting the terminal.

Where Backgrind fits

Backgrind runs your agent — your own Claude Code or Cursor CLI, or Grindy, our hosted model — in an always-on-top overlay, and surfaces a per-task Build/Plan toggle right on each session tab, so you can flip a fuzzy task into Plan without remembering a keybind. When a plan is ready for review, or a build finishes, the window flashes and the tab gets an accent ring instead of leaving you watching scrollback — so you can plan, approve, and let it build hands-off. There's a live demo if you want to see the toggle in motion.