How to use plan mode

Plan mode is read-only. The agent can read, search, browse and reason; it cannot write a file or run a command. The allowlist is exactly: read, list_files, glob, grep, web_search, web_scrape, db_schema, read_runtime_errors, mcp_list, mcp_call, spawn_subagent, use_skill, ask_user and exit_plan_mode. Nothing in that list touches your code.

When to reach for it

Anything that touches more than a handful of files: multi-tenancy, a payment flow, swapping a data layer, a schema change, an auth migration. The default mode is build, which is right for feature work and wrong for a decision you have not made yet.

"We're about to add multi-tenancy. Read the auth and DB code and tell me what would have to change. Don't write anything yet."

You get back a structured plan — overview, key decisions, architecture, user journeys, data models, files, steps, dependencies. Read it, argue with it, then approve:

"Good, but keep the existing profiles table. Go ahead and implement that."

The agent calls exit_plan_mode and the full toolset unlocks.

The other use: breaking a loop

When the agent keeps making the same wrong edit, more build turns will not help — it is working from a wrong model of your code and each turn reinforces it. Switch to plan mode and ask for the cause instead of the fix. A read-only turn cannot make the situation worse, which is precisely why it is the escape hatch.

Audits are plan-mode questions

Scope them, or you get a list too long to act on:

Switch to plan mode. Audit the database policies: list every table, whether RLS
is on, and whether the policies actually restrict rows to their owner. Flag
anything a logged-in user could read that isn't theirs. Don't change anything.

Switch to plan mode. Audit accessibility on the checkout flow only: labels,
focus order, contrast, and whether errors are announced. Give me a ranked list
with the file and line for each.

Then pick from the list one turn at a time. "Fix everything you found" produces a diff you cannot review.

What it costs

Plan turns are billed like any other turn — a long plan over a large codebase is not free. It is still cheaper than three wrong builds, and much cheaper than shipping the second-best architecture. See how credits are charged.

Plans are not memory

Chat context compacts once a conversation crosses 90% of the model's context window, and a new chat starts empty. A decision that must survive that goes in Knowledge (Settings → Knowledge, project-scoped or workspace-scoped, 10,000 characters each), not in a message you hope the agent still remembers.