Plan mode or a written plan?
Claude Code, Codex, and Cursor each have a plan mode for the change in front of you. When a written plan in your repository pays off, and how to use both.
Plan mode is the right tool for a change you finish in one session. When the work spans several sessions, several people, or several pull requests, a written plan in your repository pays off. Most teams use both.
What plan mode does
Claude Code, Codex, and Cursor each have a plan mode: the agent researches the change and proposes a plan before it edits anything.
- Claude Code. Press Shift+Tab until the status bar shows plan mode, or start a session with
claude --permission-mode plan. Claude reads files and proposes a plan, but makes no edits until you approve it. Plan files go to~/.claude/plansby default; theplansDirectorysetting keeps them inside the project instead. - Codex. In the Codex CLI, a slash command switches the chat into plan mode, and Codex proposes an execution plan before implementation work starts.
- Cursor. Press Shift+Tab in the chat input, or use the mode picker. The agent researches your codebase, asks clarifying questions, and writes a plan you can edit before you build. Plans are saved in your home directory until you choose Save to workspace.
For a bug fix, a small refactor, or a change you will finish before you close the session, plan mode is enough.
Where a written plan helps
Plan mode writes a plan for the change in front of you. A written plan in OpenPlanr is a set of files with a fixed shape, kept in your repository and read by every later step:
- A spec with acceptance criteria. Each criterion is observable and has a stable ID, such as AC-001.
- Stories and tasks with their context. Every task names its files to create, modify, and preserve, the tasks it depends on, its rationale, the risks a reviewer should watch, and the acceptance IDs it delivers.
- Files in your repository. Specifications, stories, tasks, and provenance live under
.planr/, reviewed and versioned like code, so the next session and the next teammate start from the same plan. - A separate build step. Plan stops after writing the plan. Ship later reads the task, its story, its acceptance criteria, and the spec before it changes code, one task at a time.
- Checks without a model. The
openplanrCLI validates the planning files offline.
Choosing between them
| Situation | Use |
|---|---|
| A change you finish in one session | Plan mode |
| Work that spans several sessions or days | A written plan |
| Several people or agents build parts of it | A written plan |
| More than one pull request | A written plan |
| The plan itself needs review before anyone builds | A written plan, reviewed as a diff |
Using both
Start a feature with a written plan, then use plan mode inside a single task when the change needs a closer look before your agent edits code.
If you already have a plan from plan mode, you can hand it to /planr:plan$plan@planr-plan as the request. Plan accepts a specification or a clear product request, reads the repository, and writes the stories and tasks. For a vague idea, start with /spec$spec@planr-spec instead.
Next: Plan a feature, or Plans are files for what the folder holds.