Start a team

Version control for Claude Code and Codex plans

Last updated: 23 September 2026

Ask Claude Code or Codex for a plan and you get a good one in a minute or two. What happens to it next depends on the agent, and in both cases the default is that it does not last. This guide covers where each agent keeps its plans, what is left of them a month later, and two ways to keep every version: git, or flanner.

Where Claude Code keeps a plan

In plan mode, Claude writes its plan to a Markdown file before it asks you to approve it. By default the file goes in ~/.claude/plans/, in your home folder rather than your project.

  • One file per conversation. As the plan changes, Claude edits the same file, so earlier drafts are overwritten. Nothing keeps versions.
  • Named from your prompt. Since v2.1.111 a file name starts from what you asked, plus random words, such as fix-auth-race-snug-otter.md.
  • Deleted after a month. The folder is part of Claude Code's automatic cleanup, which removes files older than cleanupPeriodDays, 30 days by default.

So a plan you did not move is gone a month later, and within that month you only have its latest form.

Where Codex keeps a plan

Codex has a plan mode too, entered with /plan or Shift+Tab. Its plan is an item in the conversation rather than a file. It comes back when you resume that session, but there is no plan file in your repository or your home folder to read, compare or share.

OpenAI's cookbook describes a convention for longer work: keep a template such as .agent/PLANS.md, and tell Codex in AGENTS.md when to use it. That gives you a file, but one you maintain by hand. It is a convention, not a feature, and the article says Codex was not trained on the term.

Option one: keep plans in git

If a plan is a file in your repository, git can keep it. Claude Code has a setting for exactly that. Put it in .claude/settings.json and commit the file, so everyone on the project gets it:

{ "plansDirectory": "./plans" }

Relative paths resolve from the project root, and a path outside the project is ignored. Then commit the plans. What you get is git's history of the commits you made: the plan is still edited in place while you work, so a draft you did not commit is not kept. Plans in git also appear in diffs and pull requests, which some teams want and others do not.

Codex has no such setting. The nearest equivalent is a folder you ask it to write to in AGENTS.md, and remembering to commit what it writes there. What plansDirectory changes, and what it leaves to you goes further into the setting.

Option two: let flanner keep them

flanner is a free, open-source CLI and MCP server built for this. Install it, then run init in a repository:

uv tool install flanner
flanner init

init registers flanner's MCP server with Claude Code and Codex, and writes the same short block of guidance into CLAUDE.md and AGENTS.md. From then on, when you ask your agent to save a plan, it calls flanner instead of writing the file itself:

  • The plan lives in .plans/ with a YAML header, and every revision the agent saves is a new version in its own file: auth-rewrite_v1.md, then auth-rewrite_v2.md.
  • .plans/ is added to .gitignore, so plans stay out of your commits until you decide otherwise.
  • In Claude Code, a guard hook stops the agent writing into .plans/ directly, so a plan cannot skip the versioning.

To read a plan's history, and compare two of its versions:

flanner history auth-rewrite
flanner diff auth-rewrite 2 3

One thing flanner does not do is read plan mode's own file. When you approve a plan in Claude Code, or settle one in Codex, ask the agent to save it. The guidance block tells it how, and the plan has a history from then on.

Know when a plan has gone stale

Keeping a plan is half the problem. The other half is noticing when the code has moved away from it.

flanner freshness

Each plan gets a status, from fresh to stale, with the evidence behind it: files or names it cites that no longer exist, and how many commits have touched the files it describes since it was written. Your agent can run the same check over MCP before it trusts a plan. How to spot a stale plan shows the checks by hand and with flanner.

Which to choose

  • Claude Code only, and you want plans reviewed in pull requests: plansDirectory and git.
  • Codex, or both agents, or every revision kept: flanner.
  • Both at once: fine, as long as plansDirectory does not point at .plans/. flanner's guard hook is there to stop direct writes into it.

If your team works from the same plans, Flanner Mesh moves them between your machines directly, signed and verified. Our servers manage accounts and access, and never receive the plans themselves.

Sources

Checked on 23 September 2026, against Claude Code v2.1.280.

← All posts