> ## Documentation Index > Fetch the complete documentation index at: https://docs.vibely.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Plan Mode > A read-only reasoning pass. Get a written approach before the agent writes any code. **TL;DR** * 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](/docs/tips/troubleshooting#break-the-agent-out-of-an-error-loop) 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. Skip it when the change is small, surgical, or the agent has already been working in that area successfully. ## 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 | The same agent, the same tools, with the *write* and *side-effect* tools filtered out. Plan Mode isn't a different model. ## 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. If the agent says *"I cannot do that"* while you're in Plan Mode, that's usually why. See [Troubleshooting → Unstick "I cannot do that"](/docs/tips/troubleshooting#unstick-i-cannot-do-that). ## 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 Stay productive across many turns without breaking what works. Prompt shapes — including the plan-first shape — in detail. Recovery paths for when a plan-then-implement loop still misfires. The flat 1-credit cost of Plan Mode in context.