D3 · Claude Code › Cluster 2 · Settings & Configuration

2.4 · The .claude Directory & /config

Where everything lives

CONCEPT Two .claude/ directories: user and project

Almost everything Claude Code reads lives in a .claude/ directory. There are two of them, mirroring the settings scopes from 2.1:

Both directories hold the same kinds of things, and the contents merge with project taking precedence:

PathWhat it holds
settings.jsonSettings at that scope (user or project)
settings.local.jsonPersonal, gitignored overrides (project dir only)
CLAUDE.mdMemory / instructions at that scope
commands/Custom slash commands (one .md file each)
agents/Subagent definitions (one .md file each)
skills/Custom skills
hooks/Hook scripts referenced by the hooks setting
🔑 Hooks themselves are configured in settings.json under the hooks key; the hooks/ folder is just a convenient home for the scripts those hooks invoke.

CONCEPT Sibling files & the managed directory

A few important files live next to .claude/, not inside it:

PathRole
.mcp.jsonProject-scoped MCP server definitions (repo root)
~/.claude.jsonOAuth session, MCP config, and app state (a file, not the dir)
/Library/Application Support/ClaudeCode/managed-settings.jsonEnterprise managed policy (macOS)
/etc/claude-code/managed-settings.jsonEnterprise managed policy (Linux / WSL)
⚠️ Don't confuse ~/.claude/ (the directory of settings, commands, agents) with ~/.claude.json (a single file holding session/MCP state). Different things.

CONCEPT What /config does

/config is the in-app settings UI. Running it opens a tabbed interface where you can view status (version, auth) and change settings — model, theme, output style, and more — that reload without a restart. Editing settings.json by hand and using /config are two doors to the same config.

Use /config for quick, interactive tweaks; edit settings.json directly when you want the change committed to the repo and reviewed.

DIAGRAM The .claude layout at a glance

flowchart TD U["~/.claude/ (USER)"] --> US["settings.json"] U --> UM["CLAUDE.md"] U --> UC["commands/"] U --> UA["agents/"] U --> UK["skills/"] P[".claude/ (PROJECT, in repo)"] --> PS["settings.json (committed)"] P --> PL["settings.local.json (gitignored)"] P --> PM["CLAUDE.md"] P --> PC["commands/ · agents/ · skills/ · hooks/"] ROOT["repo root"] --> MCP[".mcp.json (project MCP servers)"] HOME["home"] --> STATE["~/.claude.json (session + MCP state)"] MGD["managed dir"] --> MP["managed-settings.json (enterprise policy)"] classDef user fill:#d4edda,stroke:#28a745,color:#155724; classDef proj fill:#cfe2ff,stroke:#3d7bfe,color:#0a3a9a; classDef top fill:#f8d7da,stroke:#dc3545,color:#721c24; class US,UM,UC,UA,UK user; class PS,PL,PM,PC proj; class MP top;

CODE Inspecting a project .claude directory

A typical committed layout — settings, memory, a custom command, and a subagent, plus the gitignored local file.

# from the repo root
$ tree -a .claude .mcp.json
.claude
├── settings.json          # committed team settings
├── settings.local.json    # gitignored personal overrides
├── CLAUDE.md              # project memory / instructions
├── commands
│   └── deploy.md          # /deploy slash command
├── agents
│   └── reviewer.md        # a custom subagent
└── skills
    └── changelog/
.mcp.json                  # project-scoped MCP servers

# open the interactive settings UI
$ claude
> /config                 # tabbed settings, live-reloads most changes

TRADE-OFFS Editing settings.json vs. using /config

✅ Edit settings.json directly

  • Committable and reviewable in version control
  • Scriptable; supports every key incl. hooks, permissions
  • Shareable with the whole team at project scope

⚠️ /config interactive UI

  • Fast, discoverable, live-reloads without restart
  • Great for personal/session tweaks (model, theme)
  • But: not everything is exposed; not a review artifact

EXAM TRAPS

Trap: "MCP servers are defined in .claude/settings.json." → Project MCP servers live in .mcp.json at the repo root. Settings can approve them (enableAllProjectMcpServers) but don't define them.
Trap: "~/.claude.json and the ~/.claude/ folder are the same thing." → One is a state file (session, MCP), the other is the config directory (settings, commands, agents, skills).
Trap: "Custom slash commands go in a top-level commands.json." → Each command is its own .md file inside .claude/commands/ (user or project).
Trap: "/config only shows read-only status." → It's an interactive editor: it changes settings and live-reloads most of them without a restart.

PRACTICE

Q1 · Where does a project-scoped MCP server get declared?

In .mcp.json at the repo root — not in settings.json. The enableAllProjectMcpServers setting can auto-approve the servers declared there.

Q2 · A teammate's custom /deploy command isn't showing up. Where should it live?

As deploy.md inside .claude/commands/ (project scope, committed) or ~/.claude/commands/ (user scope). Slash commands are individual Markdown files in a commands/ folder.

Q3 · What's the difference between editing settings.json and running /config?

Both change the same configuration. Editing settings.json is committable, scriptable, and covers every key; /config is an interactive UI for quick tweaks that live-reloads most changes without a restart.