Plan Mode

Plan mode flips the agent from "just do it" to "tell me what you'd do, then wait." You see the file list, the change summary, and an estimated credit cost — and nothing lands until you approve.

If you've ever asked an AI to "refactor the auth flow" and watched it casually rewrite half your repo, plan mode is the answer.

What plan mode actually is

Without plan mode, a prompt becomes a single streaming run: the agent reads, edits, verifies, and reports back in one shot. The first you hear about an edit is when the file appears in the diff.

With plan mode, the run splits in two:

When to use it

Turn plan mode on when the cost of getting it wrong is high:

• First time on a codebase. You don't yet know how the agent reads your structure. Make it show you.
• Ambiguous prompts. "Make the dashboard better" could mean ten things. The plan forces concreteness.
• Touching shared code. Anything in src/lib/, src/hooks/, or auth flows — small mistakes ripple.
• Refactors and renames. Cross-file changes are where agents most often miss spots.
• Schema changes. Database migrations should never run blindly. Read Cloud / Database for context.

Toggling plan mode

The toggle lives at the bottom of the chat panel, next to the prompt box. It's a per-message switch — it doesn't stay on between prompts. If you want planning by default, ask in your project's instructions and the agent will offer plans for substantial changes.

For any change touching more than 2 files, propose a plan first.

You can also enter plan mode mid-conversation by adding /plan to your message — the agent recognizes the prefix and treats the rest as a plan request.

Reviewing a plan

The plan card shows three things:

┌─ PLAN ─────────────────────────────────────────────────┐
│  1. Create src/components/auth/LoginForm.tsx           │
│     New component with email/password fields           │
│                                                        │
│  2. Edit src/pages/Login.tsx                           │
│     Replace placeholder div with <LoginForm />         │
│                                                        │
│  3. Edit src/App.tsx                                   │
│     Add /login route to the router                     │
│                                                        │
│  Estimated credits: 3                                  │
│                                                        │
│  [ Approve ]  [ Modify ]  [ Reject ]                  │
└────────────────────────────────────────────────────────┘

Read the plan like a pull request description. Things to check:

1. File list. Are these the files you'd have edited yourself? If the agent wants to touch src/lib/api.ts and you weren't expecting that — ask why.
2. Step descriptions. Each step should be one sentence and one concern. If a step says "Update auth, add logging, and refactor the hook" — that's three things and you should make it split them.
3. Estimated credits. Sanity-check the magnitude. A 10-credit plan for a button color change means the agent misunderstood.

Approving, modifying, rejecting

Approve kicks off the execute run. The chat collapses the plan into a checklist and you watch each step turn from pending → in_progress → done.

Modify drops you back into the prompt box with the plan still visible. Your follow-up message replaces the plan — typically a steering correction:

Skip step 3 — the route already exists in App.tsx

For step 1, use the existing useAuth hook instead of raw Supabase calls

The agent re-plans with your constraint and shows a revised version. Repeat as needed.

Reject discards the plan entirely and ends the run. No credits charged for execution. You'll still pay for the planning tokens — typically 1-2 credits for the discover phase.

When NOT to use plan mode

Plan mode adds latency (the discover phase runs before any code) and cost (Opus tokens for planning, then Sonnet tokens for execution). Skip it when:

• The change is small. "Change this button color to red" — just let it run.
• You trust the agent. After a few sessions on the same project, you'll know its instincts. Cut planning for routine work.
• You're iterating fast. Tight UI feedback loops — "a bit smaller", "more padding", "darker" — die under plan-mode latency. Use direct prompting for these.
• You're going to undo anyway. If you'd revert in one click via the snapshot system, planning the change first is overkill.

Related

• Overview — the streaming loop and event types
• Prompting Tips — write prompts that produce good plans
• File Operations — what the agent does when it executes