[FEATURE] Add support for `~/.claude/CLAUDE.local.md` as a machine-specific global configuration file that complements the existing `~/.claude/CLAUDE.md`.

Resolved 💬 4 comments Opened Dec 26, 2025 by serenNan Closed Feb 14, 2026

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/Miniconda on one machine, /opt/miniconda3 on 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:

  1. Not sync CLAUDE.md and maintain separate copies manually
  2. Create CLAUDE.local.md in every single project (repetitive)
  3. 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 .md instruction 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 .md instruction 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.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗