{"slug": "plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md", "title": "Plan Mode Saves Your Plan Where Only One Agent Can Find It. Commit PLAN.md Instead", "summary": "A developer argues that coding agents' plan-mode output should be committed to the repository as PLAN.md rather than left in vendor session directories. The piece notes that Claude Code stores plans in ~/.claude/plans/ (auto-cleaned after a default 30 days), GitHub Copilot CLI writes plan.md under ~/.copilot/session-state/{session-id}/, and Codex keeps plans in the chat, so none lands in the repo or pull request by default. It points to Claude Code's plansDirectory setting, which can redirect plan files into the project, and to git log -p -- PLAN.md as a way to review how a plan evolved.", "body_md": "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.\"\n\nThat 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.\n\nEvery 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.\n\nGive the vendors credit first, because the single-session design is good.\n\n[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.\n\n[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.\n\n[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.\"\n\nAll 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.\n\n*The plan moves from one agent's private drawer to the branch every agent can read.*\n\nThink 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.\n\nAnthropic'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.\n\nWhat the committed copy gives you that the session copy doesn't:\n\n`git log -p -- PLAN.md` shows how the plan changed as the agent learned things, each change tied to a commit.\nClaude 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`:\n\n```\n{\n  \"plansDirectory\": \"./plans\"\n}\n```\n\nThe 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:\n\n```\n# Plan: refund endpoint for paid orders\n\nStatus: step 2 of 4\n\n## Goal\nPOST /orders/:id/refund refunds a paid order once.\n\n## Steps\n- [x] 1. Add `refunded` to the order status type\n- [x] 2. Write failing tests for the endpoint\n- [ ] 3. Implement the handler and repository call\n- [ ] 4. Update the API docs\n\n## Decisions\n- A second refund returns 409, not 200.\n\n## Done when\n- `npm test` passes\n```\n\nThe 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:\n\n```\ngit add PLAN.md\ngit commit -m \"plan: refund endpoint for paid orders\"\n\n# later: how did the plan change on this branch?\ngit diff main...HEAD -- PLAN.md\ngit log --oneline -- PLAN.md\n```\n\nTo 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:\n\n```\n## Plans\n- If PLAN.md exists, read it before changing code.\n- Tick a step in PLAN.md in the same commit that does it.\n- Write any change of approach under Decisions.\n```\n\nDecide 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.\n\nUsage 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.\n\nThat 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).\n\nI 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.\n\n*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.*\n\nWhen 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.\n\n*Codex on orders-types and Claude Code on orders-api, side by side in Hermes 2.3.4, each in its own hermes/ worktree.*\n\nNothing 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.\n\nA 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.\n\nA 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.\n\nSo 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.\n\nA `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.", "url": "https://wpnews.pro/news/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md", "canonical_source": "https://dev.to/gabrielanhaia/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-planmd-instead-4n72", "published_at": "2026-11-04 03:01:12+00:00", "updated_at": "2026-11-04 03:22:33.135365+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Claude Code", "Anthropic", "GitHub Copilot CLI", "Codex", "GitHub", "OpenAI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md", "markdown": "https://wpnews.pro/news/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md.md", "text": "https://wpnews.pro/news/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md.txt", "jsonld": "https://wpnews.pro/news/plan-mode-saves-your-plan-where-only-one-agent-can-find-it-commit-plan-md.jsonld"}}