How do I set plansDirectory to move Claude Code plan files?
Set plansDirectory in a Claude Code settings file to choose where plan mode writes plan files. Claude Code 2.1.325 (Nov 13, 2026) fixed lost plan edits.
plansDirectory is a Claude Code setting that chooses where plan mode writes its plan files. It is worth knowing now because Claude Code 2.1.325, released on November 13, 2026, fixed a bug: an approved plan edit could be lost when the plansDirectory folder couldn't take it. Add the key to any settings file, point it at a folder you can write to, and run one plan to see where it lands.
{
"plansDirectory": "~/.claude/plans"
}
The settings reference says the key decides where plan mode "writes plan files", and it lists the scope as "Any file". This guide is independent and unofficial, and it follows those two pages plus the Claude Code changelog.
What plan mode does, and why the folder matters
Plan mode is the permission mode where Claude researches first and edits later. Anthropic's permission modes page puts it this way: "Plan mode tells Claude to research and propose changes without making them." You enter it with Shift+Tab, with a /plan prefix on a single prompt, or by starting Claude Code with claude --permission-mode plan.
The plan itself is a file. You review it, approve it, and Claude Code starts editing. If that file ends up somewhere you don't expect, such as a folder you never open, your plans are hard to find, back up or share.
That is the practical reason to set plansDirectory. You decide where the plan lives instead of discovering it afterwards. For the beginner view of plan mode itself, see Claude Code for non-devs.
Set it in four steps
Pick the settings file
Use ~/.claude/settings.json for every project on your machine, .claude/settings.json to share the choice with your team, or .claude/settings.local.json for you in one project.
Add the key
Add "plansDirectory" with a folder path as a string. Settings files are strict JSON, so no comments and no trailing commas.
Run one small plan
Start Claude Code, press Shift+Tab until you are in plan mode, and ask for a plan for a tiny change.
Look in the folder
Open the folder you named and confirm a plan file appeared. If none did, run /status to confirm your settings file loaded.
The file choice follows the normal rules in Anthropic's settings files and precedence page. A project local file beats the shared project file, which beats your user file, and managed settings from an organization beat all of them.
If you already juggle several settings keys, our guide to setting maxEffortLevel walks through the same scopes with a different key.
The Claude moves worth stealing, by email
Workflows tested on real jobs, sent only when they are worth it. Free.
What Claude Code 2.1.325 changed
The Claude Code changelog lists the release date as November 13, 2026. One line under Fixed concerns this setting:
Fixed an approved plan edit being lost when the
plansDirectoryfolder can't take it: the plan is now saved in the default plans folder, and a warning says where and why
In plain terms, a folder that rejects the write no longer swallows your approved plan. The plan goes to the default plans folder, and Claude Code warns you which folder it used and the reason.
Read that line for what it says. The changelog does not list the causes, so we can't tell you whether a read-only disk, a missing folder or a permissions rule triggers it. It also does not say how you edited the plan. The permission modes page documents one route: "Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds."
Where it can go wrong
- The fallback is not the folder you chose. If you see the warning, your plan is safe, but it is in the default plans folder. Fix the path rather than ignoring the message.
- A relative path is an open question. The only example in the settings reference is a home-folder path,
~/.claude/plans. We could not confirm from Anthropic's pages what a relative path is measured from, so start with an absolute or~path. - Old plans can be swept away. Our guide on Claude Code's 30-day cleanup lists
plans/among the things removed once they passcleanupPeriodDays. Whether a custom folder gets the same treatment is not stated, so copy any plan you want to keep. - Plans can hold project details. If you point the folder inside a repository, check what Git would commit before you share it.
- Below 2.1.325 you may still hit the old bug. Run
claude --versionand update if the plan edit you approved ever seems to vanish.
For the permission side of plan mode, such as which modes ask before editing, read Claude Code permissions in settings.json.
Frequently asked questions
What is plansDirectory in Claude Code?
It is a settings key whose string value tells plan mode where to write plan files. The settings reference lists its scope as "Any file". If you leave it unset, Claude Code uses its default plans folder.
Which settings file should plansDirectory go in?
Any settings file works. Use ~/.claude/settings.json for a personal default everywhere, .claude/settings.json to commit a team choice, and .claude/settings.local.json for a personal override in one project. If two files set it, the higher level in the precedence order wins.
What happens if the plansDirectory folder can't be written to?
Since Claude Code 2.1.325, the plan is saved in the default plans folder instead of being lost, and a warning says where and why. The changelog lists the fix under Fixed. It does not list which folder problems trigger it.
Do I need plansDirectory to use plan mode?
No. Plan mode works without it, because the key is unset by default and Claude Code then uses its default plans folder. Set it only when you want plan files in a specific place, such as a folder you back up.
Sources (checked 2026-11-16)
- Settings reference: the
plansDirectoryentry, its scope and the example - Choose a permission mode: what plan mode does, how to enter it,
Ctrl+G - Settings files and precedence: which file wins
- Claude Code changelog: version 2.1.325, November 13, 2026, the Fixed line
