# Plan Mode Saves Your Plan Where Only One Agent Can Find It. Commit PLAN.md Instead > Source: > Published: 2026-11-04 03:01:12+00:00 Claude Code already writes your plan to a file. Its [docs](https://code.claude.com/docs/en/claude-directory) put that file in `~/.claude/plans/` and list the folder under application data that is "Cleaned up automatically" once it is older than `cleanupPeriodDays`, which defaults to 30 days. In the table of what you lose if you delete that folder, the answer is "Nothing user-facing." That is a sensible call for a cache. It is an odd home for the most reviewable thing an agent produces before it touches your code. Every major coding CLI has a planning mode now, and each one files the plan under the vendor's session: a folder in your home directory, a session-state directory, or the chat itself. My take: the plan is part of the deliverable. It belongs in a committed file on the task branch, where a reviewer can diff it and a second agent, from any vendor, can pick it up. Give the vendors credit first, because the single-session design is good. [Claude Code](https://code.claude.com/docs/en/permission-modes) enters plan mode with Shift+Tab or a `/plan` prefix. Claude reads files and writes a plan, but by default doesn't edit your source until you approve it, and Ctrl+G opens the proposed plan in your editor. Its [context-window docs](https://code.claude.com/docs/en/context-window) say that when a long session compacts, "the plan Claude wrote in plan mode" is "Re-injected from disk." So in Claude Code, compaction doesn't eat the plan. An optional setting, `showClearContextOnPlanAccept`, adds a choice that approves the plan and clears the planning conversation ([settings reference](https://code.claude.com/docs/en/settings-reference)). Anthropic already treats the plan as the thing that outlives the chat. [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-best-practices) works the same way. Shift+Tab or `/plan` switches to plan mode, the plan is saved to `plan.md` in the session folder under `~/.copilot/session-state/{session-id}/`, `/session plan` shows it, and Ctrl+Y opens it in your Markdown editor. [Codex](https://learn.chatgpt.com/codex/reference/slash-commands) describes `/plan` as "Toggle plan mode for multi-step planning." Its slash-command reference doesn't say the plan is saved to a file, so assume it lives in the chat, next to `/compact`, which will "Compact the current chat's context." All three keep the plan with the session that made it, and by default none of them puts it in your repository or your pull request. *The plan moves from one agent's private drawer to the branch every agent can read.* Think about what review looks like today. The PR shows the code. The reasoning that picked this approach over the other two, the steps the agent agreed to, the edge cases you told it to cover: all of that sat in a plan you approved in a terminal and never saw again. Anthropic's own [best-practices guide](https://code.claude.com/docs/en/best-practices) already leans on documents in the repo. To check work against a plan instead of hunting for bugs in general, it suggests the prompt "use a subagent to review the rate limiter diff against SPEC.md". Before a task runs unattended, its first question is whether the agent knows what done looks like: "A goal condition, a spec file, or a failing test it has to turn green." Both only work when the document is a file that the reviewer and the agent can open. A plan in `~/.claude/plans/` on one laptop is neither. What the committed copy gives you that the session copy doesn't: `git log -p -- PLAN.md` shows how the plan changed as the agent learned things, each change tied to a commit. Claude Code has a setting for half of this. The settings reference describes `plansDirectory` as "Choose where plan mode writes plan files", with a default of unset, which means `~/.claude/plans` ([settings reference](https://code.claude.com/docs/en/settings-reference)). Its example points it at a folder in the project, so in the repo's `.claude/settings.json`: ``` { "plansDirectory": "./plans" } ``` The settings reference doesn't say how the files are named, so treat `./plans` as an inbox rather than the final name. The vendor-neutral half is a habit that works in every agent: right after you approve a plan, ask the agent to write it to `PLAN.md` at the repo root and commit it before the first code change. A shape that survives a handoff: ``` # Plan: refund endpoint for paid orders Status: step 2 of 4 ## Goal POST /orders/:id/refund refunds a paid order once. ## Steps - [x] 1. Add `refunded` to the order status type - [x] 2. Write failing tests for the endpoint - [ ] 3. Implement the handler and repository call - [ ] 4. Update the API docs ## Decisions - A second refund returns 409, not 200. ## Done when - `npm test` passes ``` The Decisions section is the part a conversation summary is most likely to flatten, and the part a reviewer most wants to see. The git side is plain: ``` git add PLAN.md git commit -m "plan: refund endpoint for paid orders" # later: how did the plan change on this branch? git diff main...HEAD -- PLAN.md git log --oneline -- PLAN.md ``` To make every agent respect the file, put the rule where they all look. [AGENTS.md](https://agents.md/) is read by Codex, GitHub's Copilot coding agent, Gemini CLI (with a setting) and many others, and Claude Code [can read an existing AGENTS.md](https://code.claude.com/docs/en/claude-directory) in place of a CLAUDE.md: ``` ## Plans - If PLAN.md exists, read it before changing code. - Tick a step in PLAN.md in the same commit that does it. - Write any change of approach under Decisions. ``` Decide before merge whether the file stays. Moving it to `docs/plans/` keeps it next to the code it explains. Deleting it in the last commit keeps `main` clean while the branch history still holds the plan. Either works. A stale `PLAN.md` left on `main` for the next task to trip over doesn't. Usage limits make handoffs routine. Claude's Pro and Max plans have a five-hour session limit and a weekly limit, and when you hit one, the [help center](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan) lists your options: wait for the reset, enable usage credits, switch to API credits, or upgrade your plan. The list doesn't mention opening the same task in another vendor's agent. That agent starts with the code on the branch and none of the first agent's session. If the plan is in `~/.claude/plans/` or `~/.copilot/session-state/`, the new agent plans from scratch, or you paste it over by hand. If it's `PLAN.md` in the worktree, the first prompt is "read PLAN.md and continue from the first unchecked step." I wrote up the manual version, with a `HANDOFF.md` and a test baseline, in [Claude Code Hit Its Usage Limit Mid-Task. Hand the Same Worktree to Codex in 4 Commands](https://dev.to/gabrielanhaia/claude-code-hit-its-usage-limit-mid-task-hand-the-same-worktree-to-codex-in-4-commands-3b5). I build [Hermes IDE](https://hermes-ide.com/download), so weigh this part with that in mind. Hermes runs Claude Code, Codex, GitHub Copilot CLI, Antigravity CLI and other agents, each in its own real terminal, and a task you start with ⌘N gets its own `hermes/` branch and worktree. Since [2.3.4](https://github.com/hermes-hq/hermes-ide/releases) (October 15, 2026), the bar above each session works the same way for every agent: Model, Plan and Review are always in the same place, and you can pin the ones you use. *The bar above a Claude Code session in Hermes 2.3.4: Context, Model, Plan and Review pinned, and built-in commands such as Compact, Usage and Diff.* When one agent hits its usage limit, you can continue the task in another ([README](https://github.com/hermes-hq/hermes-ide)). That is the moment a committed plan matters: `PLAN.md` is on the branch whichever agent picks the task up next. Hermes also has project memory and context pins. Pinned files reach every later session's agent, even after a restart, so pinning `PLAN.md` puts it in front of the next agent too. *Codex on orders-types and Claude Code on orders-api, side by side in Hermes 2.3.4, each in its own hermes/ worktree.* Nothing in the plan-file habit depends on Hermes. It's plain git, and it works the same in a bare terminal. Hermes is free, source-available under BSL 1.1, runs on macOS, Windows and Linux, and isn't affiliated with Nous Research, Anthropic, OpenAI, GitHub or any other agent vendor. A one-line fix doesn't need a plan file, and neither does a task you'll finish in one sitting with one agent. Claude Code already keeps its plan across compaction, so the single-session case is covered. The file earns its place when the task spans days, agents or reviewers. A plan file can go stale like any other doc. The AGENTS.md rule that ticks steps in the same commit is what keeps it honest. And a reviewer who finds code with no matching step has found something worth asking about. So where do your agents' plans live right now? Do you commit them, or do they stay in the session that wrote them? Tell me in the comments. A `PLAN.md` is retrieval at its smallest: the agent answers from a document you control instead of from what it remembers. My [RAG Pocket Guide](https://www.amazon.com/dp/B0GX2YDC5Z) covers the same idea at scale, with the chunking, retrieval and reranking patterns that ground answers in your own docs. It's one of the *Pocket Guides for Developers*, [8 short books](https://www.amazon.com/dp/B0GYLH38X4) on agents, RAG, prompts, observability, events, databases and system design.