Claude Code Config File Location: Where It Lives and How to Edit It

If you are looking for a file called config.json in an app-data folder, you will not find one. Claude Code does not store its settings in ~/Library/Application Support, ~/.config or %APPDATA%. It uses a small set of JSON files named settings.json, and which one a setting belongs in decides who that setting applies to.

Here is where they actually live, what each one controls, and which one wins when the same key is set in two places.

The short answer

There is also ~/.claude.json next to that directory. It holds state, not your preferences — it is written by Claude Code itself, and it is not the file you edit to change behavior.

Which file should a setting go in?

The three you will actually touch map onto three questions:

• Should this follow me everywhere? Theme, editor mode, default model, your own permission rules → ~/.claude/settings.json.
• Should everyone on the team get this? Shared permissions, hooks, telemetry, plugins → .claude/settings.json, committed to the repository.
• Is this just for me, just here? A personal override, or something you are testing before sharing → .claude/settings.local.json.

The split between the last two is the part people get wrong. A team file that sets "model": "claude-sonnet-5" does not stop you using Opus: put "model": "claude-opus-4-8" in your local file and only your sessions change, with no commit and no argument about it.

Precedence: what wins when two files disagree

Highest first:

1. Managed settings — deployed by your organization. Nothing you set overrides them.
2. Command line — claude --settings, for this session only.
3. Project local — .claude/settings.local.json.
4. Shared project — .claude/settings.json.
5. User — ~/.claude/settings.json.

The practical consequence is worth sitting with: a key in your user file is the weakest of the four you control. If a setting refuses to take effect, check whether the project you are sitting in sets the same key. A committed .claude/settings.json quietly beats your personal preferences, and that is deliberate.

Environment variables are not a level in this stack

This one catches people out, because it is decided per variable rather than by rank. ANTHROPIC_MODEL exported in your shell applies over the model key from any file. ANTHROPIC_DEFAULT_MODEL applies only when no file sets model at all. Same idea, opposite behavior — so check the specific pair you are using instead of assuming the shell always wins.

An env block written inside a settings file is a different thing again: that is an ordinary key, and it follows the five levels above.

Editing the file

There are two supported routes, and one command that does not exist.

For most options, run /config inside a session and change it from the menu. Claude Code creates ~/.claude/settings.json the first time you change an option it stores there, such as the theme. A few options — including Show tips — save to .claude/settings.local.json instead. So if you change something in /config and cannot find it in your user file, look in the project-local one before concluding it failed.

To edit by hand, open the file for the scope you want and add the key. For example, to let Claude Code run your lint and test commands without asking, and stop it reading .env files:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test:*)"],
    "deny": ["Read(./.env)"]
  }
}

Note that there is no claude config set command for this. If you have seen that syntax suggested elsewhere, it will not work.

Two failure modes worth knowing

Strict JSON, no exceptions

Settings files are strict JSON. A // comment or a trailing comma is a syntax error, and Claude Code reports the file as a Settings Error at the next start rather than silently ignoring it. If your settings stopped applying right after you edited them, check this first.

To see validation errors without starting a session:

claude doctor

It prints read-only diagnostics — install health, settings-file validation errors, and any warnings with suggested fixes. It is the fastest way to find out whether your file is being read at all.

Keeping the local file out of git

The first time Claude Code writes .claude/settings.local.json in a repository that does not already ignore it, it adds **/.claude/settings.local.json to your global git excludes file, so it stays out of your commits in every repository.

The gap is this: if you created the file by hand and Claude Code has not written to it yet, none of that happened. Add it to .gitignore yourself. It matters because the local file is exactly where personal overrides and standing command approvals collect.

On those approvals — when you answer “Yes, and don’t ask again” to a Bash permission prompt, Claude Code saves it as an allow rule in .claude/settings.local.json. If you started in a subdirectory of a git repository, it reads and writes that file at the repository root and applies the approval across the whole repository. That is a wider blast radius than a single prompt suggests, which is a good reason to read what you are approving.

Removing your configuration

To wipe settings, permissions, MCP server configuration and session history:

# macOS, Linux, WSL
rm -rf ~/.claude
rm ~/.claude.json

One caveat: the VS Code extension, the JetBrains plugin and the Desktop app also write to ~/.claude/. If any of them is still installed, the directory reappears the next time it runs.

Sources

• Claude Code docs — Settings files and precedence
• Claude Code docs — Settings reference
• Claude Code docs — Environment variables
• Claude Code docs — Advanced setup

Related reading