claude/for
Search
Subscribe
Claude Code

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.

We did not run this. The writing session behind this page had no access to the Claude Code CLI, so nothing below is a "tested on" result. Every claim about Claude Code comes from the Anthropic pages linked in the text, read on November 16, 2026. Run the check in the steps below on your own machine before you rely on a new folder.

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

now

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.

now

Add the key

Add "plansDirectory" with a folder path as a string. Settings files are strict JSON, so no comments and no trailing commas.

next

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.

next

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 plansDirectory folder 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 pass cleanupPeriodDays. 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 --version and 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)

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.