| File | Location | Scope / Use |
| ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.claude.json` | Home directory | Main global config. Holds projects-map, MCP servers, tool permissions, etc. [Anthropic+3Scott Spence+3Reddit+3](https://scottspence.com/posts/configuring-mcp-tools-in-claude-code?utm_source=chatgpt.com) |
| `~/.claude/settings.json` | `~/.claude` subdirectory in home | User global settings. Overrides defaults but is overβridden by more specific project settings. [Anthropic+1](https://docs.anthropic.com/en/docs/claude-code/settings?utm_source=chatgpt.com) |
| `~/.claude/settings.local.json` | `~/.claude` subdirectory in home | User local preferences. Not committed. More specific than `settings.json`. [Anthropic+1](https://docs.anthropic.com/en/docs/claude-code/settings?utm_source=chatgpt.com) |
| `.claude/settings.json` | Inside project directory | Shared project settings (committed). Overrides user global/local. [Anthropic+1](https://docs.anthropic.com/en/docs/claude-code/settings?utm_source=chatgpt.com) |
| `.claude/settings.local.json` | Inside project directory | Projectβspecific non-shared settings. For experimenting, private overrides. [Anthropic](https://docs.anthropic.com/en/docs/claude-code/settings?utm_source=chatgpt.com) |
---
## MCP & Tools-Related Files
|File|Location|Purpose|
|---|---|---|
|`.mcp.json`|Project root (when MCP servers defined with project scope)|Stores MCP server definitions shared across team. [Anthropic+1](https://docs.anthropic.com/en/docs/claude-code/mcp?utm_source=chatgpt.com)|
|MCP entries in `~/.claude.json` or other user/project settings files|As above|For MCP servers in user or global scope. [Anthropic+1](https://docs.anthropic.com/en/docs/claude-code/mcp?utm_source=chatgpt.com)|
---
## Other Supporting Files
- `CLAUDE.md` / `CLAUDE.local.md`: human-readable files with instructions, style guides, documentation that Claude loads into the context. Can be global (`~/.claude/`), project root, or repo subdirs. [Anthropic](https://www.anthropic.com/engineering/claude-code-best-practices?utm_source=chatgpt.com)
- Subagents: Markdown files with YAML frontmatter in `~/.claude/agents/` (global) or `.claude/agents/` (project). Define custom AI assistants. [Anthropic](https://docs.anthropic.com/en/docs/claude-code/settings?utm_source=chatgpt.com)
- **Settings**
- `~/.claude.json`
- `~/.claude/settings.json`
- `~/.claude/settings.local.json`
- `.claude/settings.json`
- `.claude/settings.local.json`
- **State / Metadata**
- `.claude/state.json`
- `.claude/connections.json`
- **Tools**
- `.claude/tools.json`
- `~/.claude/tools.json`
- **Workflows (optional)**
- `.claude/workflows.json`
- **Hooks**
- `.claude/hooks.json`
- `.claude/hooks.local.json`
- `~/.claude/hooks.json`
- `~/.claude/hooks.local.json`
- **Agents**
- `.claude/agents/*.json`
- `~/.claude/agents/*.json`
- **Human-readable guidance**
- `CLAUDE.md`
- `CLAUDE.local.md`
Hereβs the **override and load order hierarchy** Claude Code follows when resolving configuration. Think of it as layers, from lowest precedence (defaults) up to highest (your local overrides).
---
## 1. Built-in defaults
Hardcoded in the Claude Code binary. Provides baseline behavior if no config files exist.
---
## 2. Global (user) configs
Applied to all projects.
- `~/.claude.json` (main global)
- `~/.claude/settings.json`
- `~/.claude/tools.json`
- `~/.claude/hooks.json`
- `~/.claude/agents/*.json`
- `~/.claude/CLAUDE.md`
---
## 3. Global _local_ overrides
Take precedence over global shared. Private to your machine.
- `~/.claude/settings.local.json`
- `~/.claude/hooks.local.json`
- `~/.claude/CLAUDE.local.md`
---
## 4. Project configs
Checked into the repo, shared across the team.
- `.claude/settings.json`
- `.claude/tools.json`
- `.claude/hooks.json`
- `.claude/workflows.json`
- `.claude/agents/*.json`
- `.claude/CLAUDE.md`
---
## 5. Project _local_ overrides
Not shared, ignored by VCS. Highest precedence.
- `.claude/settings.local.json`
- `.claude/hooks.local.json`
- `.claude/CLAUDE.local.md`
---
## 6. Runtime / ephemeral
Not configs you edit, but saved state.
- `.claude/state.json` (chat threads, session info)
- `.claude/connections.json` (API keys, auth tokens)
---
### Final Rule
When the same key exists in multiple layers, Claude Code merges them in order above.
- **Later overrides earlier**.
- **Local beats shared**.
- **Project beats global**.
- **Explicit beats default**.
```
Built-in defaults
β
βββ Global (user) configs [shared]
β βββ ~/.claude.json
β βββ ~/.claude/settings.json
β βββ ~/.claude/tools.json
β βββ ~/.claude/hooks.json
β βββ ~/.claude/agents/*.json
β βββ ~/.claude/CLAUDE.md
β
βββ Global local overrides [private]
β βββ ~/.claude/settings.local.json
β βββ ~/.claude/hooks.local.json
β βββ ~/.claude/CLAUDE.local.md
β
βββ Project configs [shared, in repo]
β βββ .claude/settings.json
β βββ .claude/tools.json
β βββ .claude/hooks.json
β βββ .claude/workflows.json
β βββ .claude/agents/*.json
β βββ .claude/CLAUDE.md
β
βββ Project local overrides [private, gitignored]
βββ .claude/settings.local.json
βββ .claude/hooks.local.json
βββ .claude/CLAUDE.local.md
```
**Special case (not config, just state):**
```
.claude/state.json
.claude/connections.json
```