- Plan Mode is read-only — the agent can search, read, and reason, but cannot write files.
- Use it before any change that touches 3+ files, changes a data model, or has a risk of regression.
- One Plan Mode turn costs a flat 1 credit. Cheap insurance against a 5-turn rabbit hole.
When to use Plan Mode
Use it when thinking first will save more time than trying first.- Big refactors — “plan how we’d switch from single-tenant to multi-tenant.”
- Cross-cutting changes — anything that touches the data layer, auth, or routing.
- Stuck on a loop — when three turns have failed the same way, Plan Mode breaks the agent’s context and forces a different approach.
- Unfamiliar codebase — after a GitHub import, ask for a plan so the agent reads the project before writing anything new.
How Plan Mode is different from a build turn
| Build turn | Plan Mode | |
|---|---|---|
| Writes files? | Yes | No |
| Calls side-effecting tools? | Yes | No |
| Reads code, searches, reasons? | Yes | Yes |
| Output | Code, file writes, tool calls | A written approach you read and approve |
| Credit cost | 0.5–2 (clamped per turn) | Flat 1 |
| When it ends | When the agent decides it’s done | When you say “implement it” or switch out of Plan Mode |
How to enter and exit Plan Mode
Enter — toggle Plan Mode in the chat composer, or simply prompt:“Plan how we’d add multi-tenancy. Read the relevant code first. List the files you’d touch and the order. Don’t write code yet.”The composer pill will show Plan Mode for the next turn. Exit cleanly:
“Looks good — implement it.”This is the magic sentence. It unlocks the write tools and the agent executes the plan it just proposed. Exit with edits:
“Skip step 3. Revise step 4 to use a separate schema per tenant. Then implement.”The agent treats your edits as the new plan and implements that. Abandon and go back to build mode: Toggle Plan Mode off in the composer. The next prompt resumes normal build behaviour. The plan stays in chat history for reference.
What Plan Mode can do
- Read every file in the project.
- Search the codebase with grep / glob.
- Search the web for docs.
- Read connected Supabase schemas.
- Call MCP / Chat connectors that are read-only (Linear, Figma, Notion as context).
- Produce a written plan: files touched, order of changes, risk notes, open questions.
What Plan Mode can’t do
- Write or edit files.
- Run bash commands that change state (
bun add, migrations, deploys). - Call side-effecting App connectors (send Slack message, create Linear issue).
- Apply suggested changes — even ones it just generated. You have to explicitly leave Plan Mode.
Plan Mode anti-patterns
- Using it for trivial edits. A one-line CSS change doesn’t need a plan. You’ll just pay an extra credit and add a turn.
- Ignoring the plan. If you scan it, say “implement it,” and don’t catch the part that’s wrong — you’ve spent the credit and got a bad implementation anyway. Read the plan.
- Re-prompting in Plan Mode after the agent has already started writing. Plan Mode at the start of a change saves time; toggling it mid-change just blocks the active turn from completing.
Common Plan Mode prompts
“Plan how we’d add invite-by-email to the existing auth flow. Read lib/auth.ts and the Supabase auth tables first. List the files you’d touch and the migrations needed.”
“Plan how we’d switch the payments integration from Stripe to Razorpay. What stays, what gets ripped out, what’s the rollback story if we change our mind?”
“We’ve been failing on the same TypeScript error for 3 turns. Plan a different approach that doesn’t use the type assertion the last two turns kept trying. Then implement it.”
Next
Iterating
Stay productive across many turns without breaking what works.
Prompting
Prompt shapes — including the plan-first shape — in detail.
Troubleshooting
Recovery paths for when a plan-then-implement loop still misfires.
Plans & credits
The flat 1-credit cost of Plan Mode in context.