Claude Code Config File Location: Every File and Path on macOS, Linux and Windows (2026)

The main Claude Code config file is ~/.claude/settings.json, your user settings for every project. Each project can add .claude/settings.json (shared, committed) and .claude/settings.local.json (personal, not committed). Claude Code also keeps ~/.claude.json for sign-in state and MCP servers, and organizations can deploy a managed-settings.json in a system folder. On Windows, ~ means %USERPROFILE%.

Below is every file location in one place, with the operating-system paths for the ones that differ. All paths come from the official Claude Code documentation at code.claude.com (settings, the .claude directory reference, memory, MCP and authentication pages), checked on 2026-09-26.

Claude Code config file location at a glance

In that table, ~/.claude is the .claude folder in your home directory, and a bare .claude is the folder inside your project.

Settings files: user, project, local and managed

Most people searching for "the config file" want settings.json, and there are four of them.

• User: ~/.claude/settings.json. Applies to you in every project on the machine. Claude Code creates it the first time you change a /config option it stores in user settings, such as the theme, and writes your default model there when you pick one with /model.
• Shared project: .claude/settings.json. Lives in the repository and is meant to be committed so everyone who clones it gets the same permissions and hooks.
• Local project: .claude/settings.local.json. Your own overrides for one project. When Claude Code writes this file itself, for example after you answer "Yes, and don't ask again" to a permission prompt, it adds it to your global git excludes. If you create it by hand, add it to .gitignore yourself.
• Managed: managed-settings.json. Deployed by an administrator. The file-based location depends on the operating system:

The official docs note that Claude Code does not read the legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json. Managed policy can also arrive through MDM or server-managed settings, in which case there may be no file on disk at all.

When the same key is set in more than one file, the order from highest to lowest is: managed settings, command-line arguments, local project, shared project, user. Files merge key by key rather than replacing each other; the mechanics are in Claude Code configuration: the layers and how they merge.

~/.claude.json: the global config file

~/.claude.json sits in your home directory, next to the ~/.claude folder rather than inside it. Claude Code writes it for itself, and the documentation says you don't need to edit it. It holds:

• your sign-in session,
• MCP server configurations for the user and local scopes,
• per-project state such as trust decisions,
• the global config keys that /config writes for you.

If this file cannot be parsed, Claude Code copies the broken version to ~/.claude/backups/ and asks whether to fix it by hand or reset it. Recent backups are kept in the same folder, so a bad edit is recoverable.

Where MCP server configuration lives

MCP servers are not configured in settings.json. Where they are stored depends on the scope you pick when adding one:

• Project scope: .mcp.json at the project root, shared with everyone through version control.
• Local scope (the default for claude mcp add) and user scope: stored in ~/.claude.json.
• Managed: managed-mcp.json in the same system folder as managed-settings.json.

A committed .mcp.json with a live token inside it is a leaked token, so keep credentials in the local or user scope.

CLAUDE.md and other instruction files

Instruction files are separate from settings. The memory documentation lists these locations:

Where Claude Code stores your login

According to the authentication docs:

• macOS: the encrypted macOS Keychain. If the Keychain rejects the write, for example when it is locked in an SSH session, Claude Code falls back to ~/.claude/.credentials.json with file mode 0600.
• Linux: ~/.claude/.credentials.json with file mode 0600.
• Windows: %USERPROFILE%\.claude\.credentials.json, restricted to your user account by the profile folder's permissions.

These files are managed through /login and /logout. If you are routing requests to a custom endpoint, the docs point to the ANTHROPIC_BASE_URL environment variable instead of editing credential files; see Claude Code proxy configuration.

Everything else under ~/.claude

The .claude directory reference lists more files that can live in ~/.claude/ (global) or in a project's .claude/ folder:

• skills/<name>/SKILL.md and commands/*.md: prompts you invoke with /name
• agents/*.md: subagent definitions
• output-styles/*.md: response style instructions
• rules/*.md: topic-scoped instructions
• keybindings.json and themes/*.json: global only
• projects/<project>/memory/: auto memory, global only

Session transcripts and other application data also live under ~/.claude, in plaintext.

Moving the config folder with CLAUDE_CONFIG_DIR

Set the CLAUDE_CONFIG_DIR environment variable to keep the home-directory files somewhere else. Claude Code then stores your settings, session history and plugins there, and keeps .credentials.json under that directory too. Project and local settings files cannot set this variable, so export it in the shell that launches Claude Code.

How to check which file is actually in effect

Knowing the path is half the job; the other half is confirming that the value you wrote is the one being used.

1. Run /status inside Claude Code. The Setting sources line names the managed source that applies to you, if there is one.
2. Settings files are strict JSON. A trailing comma or a // comment makes the file invalid, and Claude Code reports a Settings Error at the next start.
3. Claude Code reloads most settings edits without a restart, but a few keys are read only at session start. When in doubt, start a new session.
4. After a non-interactive -p run that seems to ignore a setting, run claude doctor to see what was dropped.

FAQ

Where is the Claude Code config file on Windows?

In %USERPROFILE%\.claude\settings.json for user settings, with project files in the project's .claude folder. Managed settings go in C:\Program Files\ClaudeCode\managed-settings.json.

Where does Claude Code store MCP server configuration?

Project-scoped servers are in .mcp.json at the project root. Local- and user-scoped servers are stored in ~/.claude.json, not in settings.json.

Is there a Claude Code config.json?

The official file reference does not list one. The files are settings.json (user and shared project scope), settings.local.json, the organization-deployed managed-settings.json, and the global ~/.claude.json.

Why didn't my change to settings.json take effect?

Usually the same key is set in a higher-precedence file, such as local project or managed settings, or the file is not valid JSON. Check /status rather than re-reading the file you edited.

Pointing Claude Code at a gateway from the right file

If you route Claude Code through a relay endpoint, the base URL and credential go in the env block of ~/.claude/settings.json for every project, or .claude/settings.local.json for one project, never in the committed .claude/settings.json. ROIBest AI provides Anthropic-compatible and OpenAI-compatible endpoints that work with that setup; running Claude Code with alternative models explains what changes when you swap the endpoint.