Feature Request: Configurable Plan File Storage Path & Plan Templates

[Interstellar-code]

Problem Statement

Currently, Claude Code stores plan files in ~/.claude/plans/ (user-level directory). This makes it difficult to:

1. Version control plans alongside project code
2. Share plans with team members via git
3. Reference past plans for specific projects
4. Standardize plan formats across a team

Proposed Solution

Option 1: Configurable Plan Path

Add a setting in .claude/settings.json to specify plan storage location:

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

Option 2: Auto-detect Project Plans Directory

Automatically use .claude/plans/ if it exists in the project root, falling back to ~/.claude/plans/ otherwise (similar to how .claude/commands/ works for project-scoped commands).

Additional Feature: Plan Templates

Support a template file (.claude/plan-template.md) that Claude uses as a starting structure when creating new plans. This would help teams standardize plan documentation formats.

Use Cases

• Teams wanting to track planning decisions in version control
• Projects requiring consistent plan documentation formats
• Developers working on multiple projects who want project-specific plan history
• Code review workflows where plans need to be visible to reviewers

Current Workaround

Currently requires manual copying of plan files from ~/.claude/plans/ to the project directory after plan mode exits.

Consistency with Existing Features

This would be consistent with how other Claude Code features work:

• Commands: .claude/commands/ (project) vs ~/.claude/commands/ (user)
• Skills: .claude/skills/ (project-scoped)
• Settings: .claude/settings.json (project) vs ~/.claude/settings.json (user)

Plans should follow the same pattern for consistency.

---

Thank you for considering this enhancement!

[SaymV]

To add another use case:

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

[CodeOfficer]

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.

[tsw025]

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

[salam0smy]

+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.

[TomTom101]

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.

[cyberhuman]

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.

[optechdvb]

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