Feature Request: Configurable Plan File Storage Path & Plan Templates

To add another use case:

At current API limits: it is nice to plan work in one session and execute on it in another.

This would be super useful. I’m doing my best to keep each Claude Code project atomic, but it keeps putting plan files in ~/.claude, which means they drift out of sync with the project’s instructions. I try to use a PLAN.md in the repo root, but I spend way too much time fighting Claude to keep plan items there instead of in ~/.claude.

I’m also switching between multiple machines (work and personal), which makes the sync problem even worse.

Workaround for loading existing plans into new sessions:

I found a workflow that works:

1. Start a new session and enter plan mode
2. Ask Claude to read your existing plan: "Read and use this plan: ~/.claude/plans/mighty-mapping-storm.md"
3. Claude will create a new session plan based on that content
4. Exit plan mode and continue working

Note: This creates a duplicate file in ~/.claude/plans/ since Claude Code always generates a new random filename per session.

However, the core issue remains: I was thinking that /plan should accept an optional path argument to load existing plans without duplication. Also, as the ticket describes, if we can configure a directory and load plans, that would be ideal.

Something like:

• /plan → show current plan (existing)
• /plan <path> → load specified plan as session plan
• /plan --list → list available plans

+1 for this feature! I'd like to add a specific pain point I'm experiencing:

The Confusion/Duplicate Files Problem

When working on multi-phase features, I ask Claude to create phase-specific plan documents during plan mode. This causes:

1. I ask: "Create a plan for Phase 1: Database"
2. Claude creates it in ~/.claude/plans/ (plan mode default)
3. I wanted it in my project's .claude/plans/
4. Claude gets confused and creates a duplicate in the project directory
5. Result: Wasted context tokens (1000+) on confusion instead of planning

My Use Case: Multi-Phase Planning

For complex features (e.g., RevenueCat subscriptions), I need hierarchical plans:

• Main plan: subscription-system-main.md
• Phase plans: subscription-phase-1-database.md, subscription-phase-2-revenuecat.md, etc.

These plans must:

• Live with code in version control
• Be accessible across Claude Code sessions (spanning weeks)
• Be visible to team members for PR reviews

Support for Option 1

I strongly support Option 1 (configurable plansDir in .claude/settings.json):

• Simple - one setting
• Explicit - no ambiguity
• Consistent - matches .claude/skills/ pattern

{
  "plansDir": ".claude/plans"
}

The current workaround wastes valuable context tokens on file management instead of development work.

I just started working with Claude Code since 3 days and this is what I currently miss the most in order to separate planning from implementation while being able to commit a plan/spec for other users to see and comment on.

I started to use the plan mode more recently, and it's very annoying that the plans are not project-scoped. It would be nice if it was implemented properly.

I love this enhancement submission for relocating the plans folder into the repo. Though this feature request is still open, support for a planDirectory field has recently been added to settings. (https://code.claude.com/docs/en/settings#available-settings)

In order to support capturing additional information about the plan, I use a skill to put metadata in the plan itself, called plan_writer. I have instructions in CLAUDE.md to utilize this skill. I've attached the plan_writer skill, the instructions added to CLAUDE.md and the plan I used for migrating existing plans.

Note: I migrated all of the plans from my ~/.claude/plans folder but you could extend the migration plan to let you choose which ones to migrate.

Plan Writer Skill goes in skills/plan-writer/SKILL.md

CLAUDE-plan-writing-snippet.md

plan-writer-skill-implementation-and-migration.md

+1, I need .claude/plans/

I suggest we close this ticket because, for example, I am currently using the latest version (v2.1.62), and everything is working as intended. I have the following settings in Claude Code Settings for the project ("plansDirectory": "./.claude/plans" in .claude/settings.json), and the plans are being placed within the project.

I believe the bug no longer exists.

+1 on project-local storage and templates. The missing piece beyond path config is that plans also need identity and status tracking — right now a new planning cycle silently overwrites the old plan with no archive, no reference, nothing. See #29445 for a proposal that covers storage, naming, lifecycle, and cross-session chaining as a coherent unit.

Real-world use case: Plan files as persistent lifecycle documents

We run a monorepo with 10+ applications and use plan files as the primary lifecycle document for every work cycle — not ephemeral scratch. Our plan files track:

• Time intervals (ISO 8601 start/end timestamps on every task)
• Resource usage (token estimates per phase)
• Work completed vs discovered during implementation
• Exit reports summarizing what was done and what remains
• Code review context — plans are posted as PR comments for reviewer context

The hardcoded ~/.claude/plans/ path means these documents aren't version-controlled alongside the code they describe. We built a PostToolUse hook bridge that auto-copies native plan files to a git-tracked plans/{branch-slug}/plan.md directory, but this is a workaround for what should be a first-class feature.

What we'd use: A planPath setting in .claude/settings.json (Option 1 in this issue) pointing to a project-relative directory. The auto-detect pattern (Option 2) would also work — it's consistent with how .claude/commands/ already behaves.

The consistency argument is strong: Commands, skills, and settings all support project-scoped paths. Plans are the obvious missing piece.

Related: #21131 (overwrite-on-pivot destroys plan history), #30668 (boolean flag for project-relative storage), #30438 (first-class plan system)

It seems like you’re describing something that’s already been implemented. Please read my message above.

Saving plans in a local project directory already works. I’ve personally been using it for at least a week. And that option is already available.

Real-world use case: Plan files as persistent lifecycle documents We run a monorepo with 10+ applications and use plan files as the primary lifecycle document for every work cycle — not ephemeral scratch. Our plan files track: - Time intervals (ISO 8601 start/end timestamps on every task) - Resource usage (token estimates per phase) - Work completed vs discovered during implementation - Exit reports summarizing what was done and what remains - Code review context — plans are posted as PR comments for reviewer context The hardcoded ~/.claude/plans/ path means these documents aren't version-controlled alongside the code they describe. We built a PostToolUse hook bridge that auto-copies native plan files to a git-tracked plans/{branch-slug}/plan.md directory, but this is a workaround for what should be a first-class feature. What we'd use: A planPath setting in .claude/settings.json (Option 1 in this issue) pointing to a project-relative directory. The auto-detect pattern (Option 2) would also work — it's consistent with how .claude/commands/ already behaves. The consistency argument is strong: Commands, skills, and settings all support project-scoped paths. Plans are the obvious missing piece. Related: #21131 (overwrite-on-pivot destroys plan history), #30668 (boolean flag for project-relative storage), #30438 (first-class plan system)

Yeah, this is implemented: https://code.claude.com/docs/en/settings

| Setting | Description | Example |
|---|---|---|
| plansDirectory | Customize where plan files are stored. Path is relative to project root. Default: ~/.claude/plans | "./plans" |

Which I didn't realize until I went through the whole cycle of wanting this for weeks, finally mustering the energy to spend 30sec searching for it, and arriving here.

Until configurable plan paths and templates are supported:
Workaround 1 — Use a skill as a plan template:

mkdir -p ~/.claude/skills/plan-template
cat > ~/.claude/skills/plan-template/SKILL.md << 'EOF'
---
name: plan-template
description: "Create a plan using our standard template"
---
When creating a plan, use this template:
[What we're trying to accomplish]
[Current state, constraints, background]
1. [ ] Step 1 — description
2. [ ] Step 2 — description
3. [ ] Step 3 — description
- Risk 1: mitigation
- Risk 2: mitigation
- [ ] Criterion 1
- [ ] Criterion 2
Save the plan to tasks/current-plan.md
EOF

Invoke with /plan-template to get a structured plan.
Workaround 2 — Custom plan location via CLAUDE.md:

<!-- CLAUDE.md -->
When creating plans, always save them to:
  docs/plans/YYYY-MM-DD-<topic>.md
Never use the default plan location. Use the docs/plans/ directory.

Workaround 3 — PostToolUse hook to relocate plans:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hook": "bash -c 'INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FILE\" | grep -q \"plan\"; then mkdir -p docs/plans; fi'"
      }
    ]
  }
}