What Claude Code's plansDirectory setting does, and does not

Last updated: 23 September 2026

Claude Code writes the plan it makes in plan mode to a file. By default that file lives in ~/.claude/plans/, outside your project, where it is cleaned up after 30 days. The plansDirectory setting, added in v2.1.9, puts it somewhere else. Here is what the setting changes, how to set it, and what it leaves for you to handle.

Setting it

plansDirectory is accepted in every Claude Code settings file: your user settings, a project's .claude/settings.json, the git-ignored .claude/settings.local.json, and managed settings. For a whole team, set it in the project file and commit that:

{
  "plansDirectory": "./plans"
}

A relative path resolves from the project root. A path that resolves outside the project is ignored, and Claude Code falls back to the default folder, so a typo sends plans back to your home folder without an error. Check the folder after your next plan.

What it changes

Plans sit beside the code. You can open, commit and review them like any other file.
They leave the cleaned-up folder. The docs list ~/.claude/plans/ among the files removed after cleanupPeriodDays. They do not say the same of a custom folder.
Names stay the same. A file is still named from your prompt plus random words, such as fix-auth-race-snug-otter.md.

What it leaves to you

The setting moves a file. Four jobs stay yours.

History

Claude Code keeps one plan file per conversation and edits it in place. Git keeps the versions you commit, and nothing else: a revision made between two commits is gone.

Noticing when a plan stops being true

Nothing reads a plan against the code later. A plan that names a function you renamed last week reads exactly as confidently as the day it was approved, to you and to the next agent that opens it.

A record of review

Approving a plan happens inside one session. There is no record of who approved which version, or whether anyone looked at the revision the agent made afterwards.

Your other agents

Codex does not read the setting. Its plan mode keeps the plan in the conversation, with no file at all.

Where flanner fits

flanner does those four jobs for plans your agent saves through it. Every revision is a numbered version in .plans/; flanner freshness gives each plan a status, from fresh to stale, with the evidence behind it; flanner review records who proposed and who approved a version; and the same MCP tools work from Claude Code and Codex.

It does not read plan mode's file, so after you approve a plan, ask the agent to save it through flanner. If you use both, keep plansDirectory away from .plans/: flanner's guard hook is there to stop direct writes into that folder.

Version control for Claude Code and Codex plans compares the two approaches side by side.

Sources

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

← All posts