config

File	Location	Scope / Use
`~/.claude.json`	Home directory	Main global config. Holds projects-map, MCP servers, tool permissions, etc. Anthropic+3Scott Spence+3Reddit+3
`~/.claude/settings.json`	`~/.claude` subdirectory in home	User global settings. Overrides defaults but is over‐ridden by more specific project settings. Anthropic+1
`~/.claude/settings.local.json`	`~/.claude` subdirectory in home	User local preferences. Not committed. More specific than `settings.json`. Anthropic+1
`.claude/settings.json`	Inside project directory	Shared project settings (committed). Overrides user global/local. Anthropic+1
`.claude/settings.local.json`	Inside project directory	Project‐specific non-shared settings. For experimenting, private overrides. Anthropic

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
MCP entries in `~/.claude.json` or other user/project settings files	As above	For MCP servers in user or global scope. Anthropic+1

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
Subagents: Markdown files with YAML frontmatter in ~/.claude/agents/ (global) or .claude/agents/ (project). Define custom AI assistants. Anthropic
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