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:
~/.claude/— your user directory: global defaults across every project..claude/(in the repo) — the project directory: shared, committed config.
Both directories hold the same kinds of things, and the contents merge with project taking precedence:
| Path | What it holds |
|---|---|
settings.json | Settings at that scope (user or project) |
settings.local.json | Personal, gitignored overrides (project dir only) |
CLAUDE.md | Memory / 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 |
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:
| Path | Role |
|---|---|
.mcp.json | Project-scoped MCP server definitions (repo root) |
~/.claude.json | OAuth session, MCP config, and app state (a file, not the dir) |
/Library/Application Support/ClaudeCode/managed-settings.json | Enterprise managed policy (macOS) |
/etc/claude-code/managed-settings.json | Enterprise managed policy (Linux / WSL) |
~/.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.
/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
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
.claude/settings.json." → Project MCP
servers live in .mcp.json at the repo root. Settings can approve them
(enableAllProjectMcpServers) but don't define them.~/.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).commands.json." → Each
command is its own .md file inside .claude/commands/ (user or project)./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.