CLAUDE.local.md: Personal Overrides Without the Noise
CLAUDE.local.md is a gitignored project file for personal developer instructions that shouldn't pollute the team's shared CLAUDE.md. This article covers what it's for, why it should stay out of git, practical use cases, and how it sits in the overall configuration cascade.
Quick Reference
- →CLAUDE.local.md lives in the project root alongside CLAUDE.md — but is gitignored
- →It combines with (does not replace) other CLAUDE.md files — all files load together
- →Use it for: personal preferences, machine-specific paths, instructions you're testing before sharing
- →It should be in .gitignore — it's personal, not team config
- →More specific CLAUDE.md files override more general ones when there are conflicts
- →Partly superseded by using @file imports in CLAUDE.md for per-developer content
- →User-level ~/.claude/CLAUDE.md is better for preferences that apply across all projects
- →CLAUDE.local.md is for this-project + this-developer combinations only
In this article
What CLAUDE.local.md Is
CLAUDE.local.md is a project-scoped personal instructions file. It lives in the same directory as your project's CLAUDE.md but is excluded from version control — it is your personal layer on top of the shared project config.
The key distinction: CLAUDE.md is team knowledge. CLAUDE.local.md is personal knowledge. If an instruction is useful for everyone on the project, it goes in CLAUDE.md. If it's only useful for you — your setup, your machine, your preferences in this project — it goes in CLAUDE.local.md.
| CLAUDE.md | CLAUDE.local.md | ~/.claude/CLAUDE.md | |
|---|---|---|---|
| Committed to git? | Yes | No (gitignored) | No (global) |
| Who sees it? | Everyone on the team | Only you, this project | Only you, all projects |
| Best for... | Team conventions, architecture | Personal per-project settings | Personal global preferences |
| Override priority | Medium | Medium (same level, more specific wins) | Lowest |
Adding CLAUDE.local.md to .gitignore
Before using CLAUDE.local.md, make sure it's gitignored. Accidentally committing it exposes your personal instructions, machine-specific paths, and any debugging notes you added.
If you create CLAUDE.local.md before adding it to .gitignore, git will track it. Run `git status` before committing and verify it is not staged. Add it to .gitignore and run `git rm --cached CLAUDE.local.md` if it was accidentally staged.
What to Put in CLAUDE.local.md
CLAUDE.local.md is most useful for three categories of content:
Personal preferences for this project
Preferences that contradict the team's CLAUDE.md defaults, or that you want only when working on this project (not all projects). For example: 'In this project I prefer more verbose error messages' or 'I'm learning the new auth flow — explain reasoning more than usual'.
Machine-specific context
Paths, tool locations, or environment details specific to your local machine. For example: 'The local dev database is at postgresql://localhost:5434/acme_dev (non-standard port because I run multiple Postgres instances)'. The team's CLAUDE.md uses the standard port — yours differs.
Testing instructions before sharing
New instructions you're evaluating before proposing to the team. Try them in CLAUDE.local.md to verify they improve Claude's behavior. If they do, move them to CLAUDE.md in a PR.
How CLAUDE.local.md Combines with Other Files
CLAUDE.local.md does not replace CLAUDE.md — all loaded CLAUDE.md files combine. Their contents are merged into context together. When the same topic is covered in multiple files, the more specific file takes precedence on that topic.
CLAUDE.local.md is at the same hierarchy level as project CLAUDE.md (both are project-scope), but it loads alongside it. For conflicts, the more specific instruction wins. In practice, this means your personal overrides in CLAUDE.local.md will shape Claude's behavior for topics you've addressed, while the team's CLAUDE.md shapes everything else.
If a preference applies to every project (not just this one), it belongs in ~/.claude/CLAUDE.md (user global), not CLAUDE.local.md. CLAUDE.local.md is for the combination of 'this project' + 'my personal setup'. User global is for 'all my projects' + 'my personal setup'.
CLAUDE.local.md and Git Worktrees
If you use git worktrees (multiple checked-out versions of the same repo in different directories), CLAUDE.local.md can cause problems. The file is in the project root of one worktree — it doesn't automatically exist in other worktrees, and your personal settings won't apply consistently.
For worktree users, the official recommendation is to use @file imports in CLAUDE.md instead — importing a personal file that lives outside the repo directory and is symlinked or referenced consistently. This is why CLAUDE.local.md has been 'partly superseded' in the docs for users with complex git setups.
Best Practices
Do
- ✓Add CLAUDE.local.md to .gitignore before creating the file
- ✓Use it for personal preferences, machine-specific paths, and experimental instructions
- ✓Graduate instructions to the shared CLAUDE.md once you've verified they help the whole team
- ✓Use ~/.claude/CLAUDE.md for preferences that should apply to all your projects
- ✓Keep it short — CLAUDE.local.md is for overrides, not a full configuration file
Don’t
- ✗Don't commit CLAUDE.local.md — it's personal and machine-specific
- ✗Don't duplicate content from CLAUDE.md — CLAUDE.local.md is for additive and overriding content only
- ✗Don't use CLAUDE.local.md for team conventions — those go in the shared CLAUDE.md
- ✗Don't confuse CLAUDE.local.md (project-scoped, personal) with .claude/settings.local.json (project-scoped, settings)
Key Takeaways
- ✓CLAUDE.local.md is project-scoped, personal, and gitignored — your personal layer on team config
- ✓It combines with (not replaces) other CLAUDE.md files — all load together
- ✓Best for: personal preferences for this project, machine-specific paths, experimental instructions
- ✓Add it to .gitignore before creating it to avoid accidental commits
- ✓For preferences that apply to all projects, use ~/.claude/CLAUDE.md instead
Video on this topic
CLAUDE.local.md: Personal Overrides That Stay Off Git
tiktok