What is CLAUDE.local.md?

Q: Is CLAUDE.local.md gitignored automatically?

No — you add it to .gitignore yourself. Until you do, it's an ordinary tracked file and git will happily commit it. The .local in the name is a convention, not automatic privacy.

Q: Does CLAUDE.local.md override CLAUDE.md?

No. Both files load and stack together — CLAUDE.md first, then CLAUDE.local.md — so your personal notes add to the shared brief rather than replacing it. Where they say different things, the later, more specific instruction is the one Claude reads last.

Q: Where do I put personal instructions that apply to every project?

Use your user-level memory file at ~/.claude/CLAUDE.md. It loads for every Claude Code session on your machine, across all repos — whereas CLAUDE.local.md is scoped to the one project it sits in.

CLAUDE.local.md is your personal, gitignored version of CLAUDE.md — machine-local Claude Code instructions that never reach the team. When and how to use it.

CLAUDE.mdis the file you commit so every teammate's Claude Code gets the same brief. But some of what you'd tell Claude is only true on your machine — a local API port, the path to a scratch folder, a habit nobody else needs. CLAUDE.local.md is where that goes: same format, loaded the same way, but private to you.

CLAUDE.local.md vs CLAUDE.md

File	In git?	Who it's for	What goes in it
`CLAUDE.md`	Yes — checked in	The whole team	Shared conventions, build & test commands, the repo’s skip list
`CLAUDE.local.md`	No — you gitignore it	Just you, on this machine	Personal paths, local URLs, private test data, your own overrides

Both load at the start of every Claude Code session for that project. CLAUDE.md is read first, then CLAUDE.local.md — they stack together rather than one replacing the other, so your personal notes add to the shared brief instead of overwriting it.

What to put in it

Local-only values — a sandbox URL, a database port, the path to a scratch directory that exists only on your machine.
Personal test data or fixtures you reach for but the team hasn't standardized on.
Your own working notes for this repo — a reminder to run a particular script, a warning about a step that's flaky on your setup.
Personal read/skip overrides — a directory you want Claude to always skip, or a file the shared config ignores but you want read, just for you.

What doesn't belong here is anything the team should share — build commands, code conventions, the repo-wide ignore list. Those go in the committed CLAUDE.md (or AGENTS.md) so everyone benefits.

How to set it up

Create CLAUDE.local.md at your repo root, next to CLAUDE.md. Same Markdown; write plain instructions.
Add it to .gitignoreso it never gets committed. This is the step people miss — the file isn't private until you ignore it.
That's it. Claude Code picks it up on the next session, right after CLAUDE.md.

# .gitignore
CLAUDE.local.md

# CLAUDE.local.md
- The API runs locally on port 8788, not 3000.
- Scratch data lives in ~/dev/scratch — safe to overwrite.
- Skip the /vendor-sandbox folder; it's my local experiment.

When to reach for something else

Same preferences across every project? Put them in ~/.claude/CLAUDE.md, your user-level file that applies to all repos. CLAUDE.local.md is per-project; ~/.claude/CLAUDE.md is you, everywhere.
Don't want a separate file? A committed CLAUDE.md can import one with @path — e.g. @~/.claude/my-notes.md pulls in a home-directory file. Importing from outside the project triggers a one-time approval prompt; CLAUDE.local.mdavoids that because it's already local.
Working in multiple git worktrees of the same repo? Each worktree has its own CLAUDE.local.md — they don't sync. For the same personal notes everywhere, keep them in ~/.claude and import them.

Common questions about CLAUDE.local.md

Is CLAUDE.local.md gitignored automatically?

No — you add it to .gitignoreyourself. Until you do, it's an ordinary tracked file and git will happily commit it. The .local in the name is a convention, not automatic privacy.

Does CLAUDE.local.md override CLAUDE.md?

No. Both files load and stack together — CLAUDE.md first, then CLAUDE.local.md — so your personal notes add to the shared brief rather than replacing it. Where they say different things, the later, more specific instruction is the one Claude reads last.

Where do I put personal instructions that apply to every project?

Use your user-level memory file at ~/.claude/CLAUDE.md. It loads for every Claude Code session on your machine, across all repos — whereas CLAUDE.local.md is scoped to the one project it sits in.

Should I commit CLAUDE.local.md so my team gets it?

No — that defeats its purpose. If instructions should be shared, put them in the committed CLAUDE.md (or AGENTS.md) instead. CLAUDE.local.md exists precisely for the things that should stay on your machine.

New to the shared file it complements? Start with how to write a CLAUDE.md, or see CLAUDE.md vs AGENTS.md if you're deciding which shared file your project needs.