Planning mode has an agent draft a step-by-step plan before it writes any code. You review and refine the plan first — with diagrams and diffs — and the app tracks it as it changes, so a bigger change is agreed on before implementation starts. This article covers generating a plan, reading it, refining it, and how plans are tracked.
Planning pays off for meaningfully significant changes. For quick fixes, you can skip it and just talk to the agent.
Turn on planning mode
Enable planning mode in a chat, then describe the change you want. Instead of jumping straight to code, the agent produces a full plan you can dig into.
Read the plan
A plan isn't just text — you can inspect what the agent intends to do:
- Step diagrams show how the plan progresses through a series of steps.
- Diffs show what the change will do — what gets added, updated, or removed — so you can see the planned result before any code is written. You can view just the planned changes or a full diff.
- ERDs are generated for database changes, so you can see schema changes visually.
Refine with targeted edits
The usual way to change an agent's plan is to have it regenerate the whole thing. Planning mode lets you make targeted edits instead: highlight a specific line and tell the agent what to change — rename something, fix a detail, adjust a step. You can queue several edits and send them in one go, and the agent updates just those parts. If an edit materially changes the plan, the diagrams refresh to match.
Plan tracking and revisions
A plan is tracked in the app as a living document, with revision tracking — each new version is recorded as the plan changes. You can inspect a tracked plan at any time and dig into it in an Explore view, a separate chat for exploring the plan that doesn't disturb your main worktree chat.
It helps to keep three forms of "plan" straight: a plain markdown plan, a tracked plan in the app (what this article is about), and a plan that a pipeline produces or runs from.
Share for team review
A tracked plan can be shared so teammates comment on it from the web. Their comments show up alongside the plan, where you can dismiss them or send them to the agent to make tweaks, then apply and resolve each one. See Sharing plans & team comments.
Execute when you're ready
Once you're happy with the plan, you execute it — send it to a pipeline, have the agent just do it, or take the plan elsewhere. See Executing a plan for the options.
Next steps
- Sharing plans & team comments — collaborate on a plan before any code is written.
- Executing a plan — the three ways to turn a plan into work.
- Pipelines: overview — run a finished plan through a plan-ready pipeline.