[FEATURE] Add support for `~/.claude/CLAUDE.local.md` as a machine-specific global configuration file that complements the existing `~/.claude/CLAUDE.md`.
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
Currently, Claude Code supports the following configuration hierarchy:
| File | Location | Loaded |
|------|----------|--------|
| Global instructions | ~/.claude/CLAUDE.md | ✅ |
| Project instructions | <project>/CLAUDE.md | ✅ |
| Project local instructions | <project>/CLAUDE.local.md | ✅ |
| Global local instructions | ~/.claude/CLAUDE.local.md | ❌ |
The missing piece is a global machine-specific configuration file.
I sync my ~/.claude/CLAUDE.md across multiple machines using git. However, some configurations are machine-specific:
- Conda/Python paths:
S:/Tools/Minicondaon one machine,/opt/miniconda3on another - Tool paths: Different locations for compilers, SDKs, etc.
- Environment activation commands: Different shell syntax (bash vs fish vs PowerShell)
- Local project directories: Machine-specific workspace paths
Currently, I have to either:
- Not sync
CLAUDE.mdand maintain separate copies manually - Create
CLAUDE.local.mdin every single project (repetitive) - Use git branches per machine (complex)
Proposed Solution
Support ~/.claude/CLAUDE.local.md with the following behavior:
- Loaded after
~/.claude/CLAUDE.md(so it can override global settings) - Not synced - users would add it to
.gitignore - Same format as existing
.mdinstruction files
Alternative Solutions
Support ~/.claude/CLAUDE.local.md with the following behavior:
- Loaded after
~/.claude/CLAUDE.md(so it can override global settings) - Not synced - users would add it to
.gitignore - Same format as existing
.mdinstruction files
Priority
Critical - Blocking my work
Feature Category
CLI commands and flags
Use Case Example
~/.claude/CLAUDE.md (synced across machines):
# Global Instructions
- Use conda for Python environments
- Always run tests before committing
~/.claude/CLAUDE.local.md (machine-specific, not synced):
# Machine-Specific Settings
- Conda path: `S:/Tools/Miniconda`
- Default shell: PowerShell
- Activation command: `conda activate base && python`
Additional Context
This would align with the existing pattern where .local.md files are for machine-specific overrides, just extending it to the global level.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗