[FEATURE] Configurable Plan File Location

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request: Configurable Plan File Location

Summary

Allow users to configure where plan mode saves plan files, with an option to save plans inside the project directory instead of the global ~/.claude/plans/ directory.

Motivation

Currently, when using plan mode, Claude Code saves all plan files to a global directory:

~/.claude/plans/random-name.md

Problems with current approach:

1. Not version controlled: Plans are saved outside the project directory, so they can't be committed with the code
2. Hard to find: Plans are scattered across a global directory with random names instead of being co-located with relevant projects
3. Team collaboration: Plans can't be easily shared with team members through version control
4. Project context: Plans are disconnected from the project they describe

Proposed Solution

Option 1: Project-level Setting (Preferred)

Add a configuration option in .claude/settings.json:

{
  "planMode": {
    "planFileLocation": "project", // or "global"
    "projectPlanPath": ".claude/plans/", // relative to project root
    "planFileNaming": "timestamp" // or "descriptive" or "custom"
  }
}

Behavior:

• "project": Save plans in project directory (e.g., .claude/plans/plan-2024-04-23.md)
• "global": Current behavior (save to ~/.claude/plans/)

Option 2: CLI Flag

Allow users to specify plan location when starting:

claude-code --permission-mode plan --plan-location project

Option 3: Prompt User

When entering plan mode, ask where to save the plan:

• "Save plan in project directory? (Y/n)"
• Default to user's saved preference

Use Cases

Use Case 1: Team Collaboration

project/
├── .claude/
│   └── plans/
│       ├── feature-auth.md
│       └── refactor-api.md
├── src/
└── README.md

Team members can review plans in PRs and track planning history.

Use Case 2: Project Documentation
Plans serve as implementation documentation, explaining why certain approaches were chosen.

Use Case 3: Audit Trail
Plans provide a historical record of architectural decisions for future reference.

Implementation Suggestions

1. Add plan configuration schema to settings
2. Update plan mode initialization to check for project-level plan settings
3. Fall back to global directory if project doesn't have .claude/ or settings don't specify
4. Update plan file naming to be more descriptive when saved in project

Alternatives Considered

Manual workaround: Users can manually move plans from global to project directory after creation (current workaround, not ideal)

Git hooks: Users could set up post-plan hooks to move files, but this requires complex setup

Related Features

• .claude/settings.json configuration system
• Plan mode (Shift+Tab to enter)
• permissions.defaultMode setting

Impact

• Low risk: Backward compatible (defaults to current behavior)
• High value: Improves plan mode usability for teams and version control
• Easy adoption: Optional setting, doesn't change default behavior

Questions for Maintainers

1. Should .claude/plans/ be gitignored by default, or allow users to commit plans?
2. Should plan files use descriptive names or timestamps when saved in projects?
3. Should there be a setting to save plans to both locations?

---

Environment:

• Claude Code version: [will be filled when submitting]
• OS: macOS/Linux/Windows
• Use case: Individual developer and team collaboration

Priority: Medium (quality of life improvement)

Labels: enhancement, area:config, area:cli, plan-mode

Proposed Solution

Add a configuration option in .claude/settings.json:

{
  "planMode": {
    "planFileLocation": "project", // or "global"
    "projectPlanPath": ".claude/plans/", // relative to project root
    "planFileNaming": "timestamp" // or "descriptive" or "custom"
  }
}

### Alternative Solutions

_No response_

### Priority

Medium - Would be very helpful

### Feature Category

CLI commands and flags

### Use Case Example

_No response_

### Additional Context

Currently I am using
claude --version     
2.0.70 (Claude Code)