Plan Mode
Explore, design, then implement. Plan mode thinks before it codes.
Explore, design, then implement.
Plan mode is for tasks where diving straight into code isn't the right move. It separates exploration and design from implementation — giving you a structured, reviewed plan before any file is modified.
What it does
Plan mode runs in two distinct phases. First, the agent explores your codebase read-only: it reads relevant files, maps dependencies, and understands the full scope of what needs to change. Then it produces a structured plan with numbered steps, files to touch, and a clear approach. You review and approve the plan before the agent writes a single line of code.
When to use it
- A refactoring that touches many files across the codebase
- An architectural change where the right approach isn't obvious
- A complex feature where the implementation strategy matters
- Any task where you want to review the approach before committing to it
- When you're unsure how to implement something and want the agent to propose a path
Plan mode is the right choice when you want to understand what the agent will do before it does it. If you already know the approach and just need it built, use Feature mode instead.
How it works
- Describe the task — explain what you want to achieve. You don't need to know the implementation — that's what the plan phase is for.
- Exploration phase — the agent reads the codebase read-only: relevant files, existing patterns, dependencies. No changes are made.
- Plan produced — a structured, step-by-step plan is presented: what will change, why, and in what order.
- You review — read the plan, ask questions, or request adjustments. Nothing is written until you're satisfied.
- Implementation — once approved, the agent executes the plan step by step, updating the sidebar as it progresses.
Key features
- Read-only exploration first — no code is changed before you approve the plan
- Structured plan output — numbered steps with file references and rationale
- User approval required — implementation only starts after you sign off
- Isolated branch — all changes happen in a dedicated branch
- Live sidebar — see progress during both the exploration and implementation phases
Tips
Give Plan mode a high-level goal, not a solution. "Migrate our authentication from session-based to JWT" is a better prompt than prescribing a specific implementation. Let the agent design the approach.
Use Plan mode before launching parallel Feature agents on a large task. One planning session can produce a breakdown that multiple agents can execute independently.