[FEATURE] Allow CLAUDE.md in ~/.claude to apply only to that directory

[PaulRBerg]

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

I keep my ~/.claude directory in version control and frequently ask Claude to make changes to it. The current behavior loads ~/.claude/CLAUDE.md as global instructions for all projects on my machine.

This creates a conflict: I want project-specific instructions for working on my ~/.claude configuration repository, but those instructions shouldn't apply when I'm working on other projects.

The problem is that ~/.claude/CLAUDE.md serves as both:

1. Global user instructions (applies everywhere)
2. Project instructions when working in ~/.claude

I need a way to separate these concerns.

Proposed Solution

Introduce a mechanism to define directory-specific CLAUDE.md files that only apply when Claude is opened in that specific directory, without propagating to other projects.

Possible approaches:

1. New filename convention: Support a different filename (e.g., CLAUDE.local.md or PROJECT.md) in ~/.claude that only applies to that directory
2. Setting for custom filepath: Ability to set a custom filepath for CLAUDE.md in settings.local.json

Example desired behavior:

• ~/.claude/CLAUDE.md → Global instructions (current behavior, unchanged for other directories)
• ~/.claude/PROJECT.md → Set via settings.local.json`

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/5171
2. https://github.com/anthropics/claude-code/issues/10118
3. https://github.com/anthropics/claude-code/issues/2571

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[gw0]

Alternative proposal:

• Add env var to set the global user instructions file location (default ~/.claude/CLAUDE.md). When you work on your version-controlled ~/.claude you could change (or even disable the global user instructions).

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.