---
title: Plan mode or a written plan?
description: 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.
url: https://openplanr.dev/docs/guides/plan-mode-vs-written-plan
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/guides/plan.md
  - https://openplanr.dev/docs/guides/user-stories-for-coding-agents.md
---

# Plan mode or a written plan?

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/plans` by default; the `plansDirectory` setting 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 `openplanr` CLI 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` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) 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` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) instead.

Next: [Plan a feature](https://openplanr.dev/docs/guides/plan.md), or [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md) for what the folder holds.