What settings.local.json is in Claude Code and how it differs from settings.json
Where .claude/settings.local.json sits in settings precedence, how "don't ask again" writes to it, and why Claude Code uses your global git excludes, not .gitignore.
Contents
Look inside a .claude/ directory and you may find a settings.local.json next to settings.json. Claude Code generates it, and it is your personal settings file — a different job from the settings.json your team shares.
In short: settings.json is the team's rules, tracked in git; settings.local.json is your own additions, kept out of git.
KEY POINT
What you will learn
- What each file is for, and where they sit in settings precedence
- How "don't ask again" writes into
settings.local.json - Which git mechanism actually keeps the local file out of your commits
How the two files differ
.claude/settings.json | .claude/settings.local.json | |
|---|---|---|
| Role | Settings shared across the project | Your personal additions |
| In git | Yes, commit it | No — Claude Code keeps it out when it creates the file |
| How it appears | You write it | Created automatically when you choose "don't ask again" |
| Precedence | Lower | Higher |
When the same key is set in both, the value in settings.local.json wins. Permission rules are a different matter: they are evaluated deny, then ask, then allow, so a local allow rule cannot carve an exception out of a project deny rule.
用語解説
Settings precedence, highest first: managed settings, then the command line (claude --settings), then project local (.claude/settings.local.json), then shared project (.claude/settings.json), then user (~/.claude/settings.json). A key set at a higher level overrides the same key set lower down.
What "don't ask again" does
When you choose "Yes, and don't ask again" for a Bash command, Claude Code saves that approval here as an allow rule:
{
"permissions": {
"allow": [
"Bash(npm run test:*)",
"Bash(git diff:*)"
]
}
}The list grows without you noticing, so review it with /permissions from time to time and delete what you no longer want. When you wonder why some command runs without a prompt, this file is the first place to look.
One useful property: while the file stays untracked, its allow rules apply without the workspace-trust step Claude Code requires for the committed project file. If you track the file in git, the trust step applies to it too.
What belongs where
| Setting | Where it goes |
|---|---|
| Deny rules everyone must follow (no reading secrets, no force push) | settings.json |
| Allow rules that are safe for anyone (lint, tests) | settings.json |
| Shared hooks (format after edit) | settings.json |
Allow rules for your own speed (git commit, npm install) | settings.local.json |
Your own defaultMode, such as acceptEdits | settings.local.json |
| Hooks and environment variables specific to your machine | settings.local.json |
Keeping the team's settings.json on the cautious side and letting individuals loosen things locally is the arrangement that holds up best.
How it stays out of git
This is the part that surprises people. Claude Code does not edit your repository's .gitignore. The first time it writes settings.local.json in a git repository that doesn't already ignore it, it adds **/.claude/settings.local.json to your global git excludes file, so the file stays out of your commits in every repository.
That file is core.excludesFile when your global git config sets it to an absolute or ~-prefixed path; otherwise it is $XDG_CONFIG_HOME/git/ignore, or ~/.config/git/ignore when XDG_CONFIG_HOME is unset.
A global exclude doesn't travel with the repository
Because the pattern lives in your own global excludes, a teammate who clones the repository does not inherit it. If you created the file by hand and Claude Code hasn't written to it yet, nothing has been excluded at all. To cover everyone, add the path to the repository's .gitignore as well:
.claude/settings.local.jsonCLAUDE.local.md, the personal notes file, is also meant to stay out of git — worth adding to the same place.
Related settings
For how to write allow, ask and deny rules and how to design the set as a whole, see the parent article, Design permissions in Claude Code's settings.json.
Summary
settings.jsonis shared through git;settings.local.jsonis personal and kept out of it- "Don't ask again" appends an allow rule to
settings.local.json; review it with/permissions - Precedence runs managed, command line, project local, shared project, user — and deny rules still win over ask and allow wherever they are written
- Claude Code excludes the file through your global git excludes, not the repository's
.gitignore, so add it to.gitignoretoo if the whole team should ignore it
FAQ
- Do I have to create settings.local.json myself?
- No. Claude Code creates it the first time you choose "Yes, and don't ask again" at a permission prompt. Creating it by hand is fine too, but then you have to ignore it yourself.
- Will settings.local.json get committed?
- Not if Claude Code created it. The first time it writes the file in a git repository that doesn't already ignore it, it adds the pattern to your global git excludes file, not to the repository's .gitignore. If you created the file by hand, add it to .gitignore yourself.
- Can a local allow rule undo a deny rule the project sets?
- No. Permission rules are evaluated deny, then ask, then allow, and the first match in that order decides, so a project deny rule still blocks the call.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.