What you will be able to do
- Use /memory, /hooks, /mcp, /permissions, /status and /doctor to see what a Claude Code session actually loaded before changing anything
- Explain why a settings value, memory file, permission rule or hook can be present on disk yet have no effect
- Tell apart a failed, an unapproved and a connected-but-zero-tools MCP server, and apply the right fix to each
- Isolate a configuration fault with safe mode and with a clean configuration directory
Key concept
Diagnose from what loaded, not from what you wrote — A file on disk only tells you what someone meant to configure. Before you edit anything, ask the running session what it actually loaded and which source won. Then narrow down the cause by turning customizations off.
1.Start from the symptom, then ask what loaded
Most Claude Code complaints like "it ignores my settings" come down to one of three things: the configuration was never read, it was read and then overridden, or it was read and matched nothing. Re-reading your own JSON can't tell these apart, because the file looks correct in all three cases. The session can tell them apart, since each kind of customization has a slash command that reports what is in effect right now.
| Command | What it shows |
|---|---|
| /memory | Memory file locations across user and project scopes, plus the auto memory folder and toggle |
| /skills | Available skills from project, user, and plugin sources |
| /hooks | Active hook configurations |
| /mcp | Connected MCP servers and their status |
| /permissions | Resolved allow and deny rules currently in effect |
| /status | Active settings sources, including whether managed settings are in effect |
| /doctor | Setup checkup: invalid settings files, unused extensions, duplicate subagent names, with proposed fixes |
| /debug [issue] | Turns on debug logging and asks Claude to diagnose from the log and settings paths |
Pick the command that matches the symptom. If a hook never fires, open /hooks. If a deny rule doesn't block, open /permissions. If you can't tell which layer is responsible, /status lists every settings source, including managed settings that no user file can override. A blank or unexpected result is your first real clue: you now know whether the problem is about loading, precedence or matching.
Checkpoint 1 of 8· Match them up
Something in your Claude Code configuration isn't taking effect. Match each slash command to what it reports about the running session.
Tap a term, then the definition that fits it.
Each command reports what the session actually loaded for one kind of customization, so you pick the one that matches the symptom. Use /status when you can't tell which settings layer is responsible, because it lists every source, managed settings included.
“/status | Active settings sources, including whether managed settings are in effect”Source: code.claude.com
Sources1
2.Settings, memory files and permission rules that silently miss
Precedence explains most "ignored" settings values. The order is settings.local.json, then the project settings.json, then the user ~/.claude/settings.json. A value one engineer keeps in their local file wins over what the team committed, and /status will still list the project file as active. A second common mistake is putting configuration in the wrong file. ~/.claude.json holds app state and UI toggles, while permissions, hooks and env belong in ~/.claude/settings.json. A rule added to the first file is never applied.
Memory files can be correct and still not be loaded yet. When Claude seems to ignore guidance, open /memory to see which files the session knows about. Writing that guidance well is covered under CLAUDE.md as implementation guidance. Two loading rules catch people out. A subdirectory's CLAUDE.md loads on demand, not at session start, so it only appears once Claude reads a file in that subdirectory. Subagents are the other case: the built-in Explore and Plan agents skip CLAUDE.md at startup, so restate a critical instruction in the delegating prompt. A custom subagent that sets omitClaudeMd skips it too.
Permission rules fail by not matching, not by erroring. How permission rules: allow, ask and deny are written is covered elsewhere. For diagnosis, the key fact is that a Bash rule matches the literal command string. Bash(rm *) therefore doesn't block /bin/rm or find -delete, and nothing warns you. Check /permissions for the resolved rules. When you need a hard guarantee, use a PreToolUse hook or the sandbox instead of a string pattern.
Checkpoint 2 of 8· Check yourself
Your team's deny rule Bash(rm *) shows up in /permissions. Claude still deleted files by running find . -name '*.tmp' -delete, and no warning appeared. What should you do?
The rule loaded correctly. It just matches the literal command string, so a different command that deletes files gets past it without any error. A hard guarantee needs a PreToolUse hook or the sandbox. ~/.claude.json holds app state, not permissions.
“Use a PreToolUse hook or the sandbox for a hard guarantee.”Source: code.claude.com
Checkpoint 3 of 8· Check yourself
/memory lists the project CLAUDE.md, and the main conversation follows its rule "never touch the generated/ folder". When you hand a search to the built-in Explore agent, that agent ignores the rule. What fixes this?
The built-in Explore and Plan agents skip CLAUDE.md at startup. They only see the rule if you put it in the prompt you delegate with. A subdirectory CLAUDE.md loads only when a file in that subdirectory is read, and only for the agent that reads it.
“For Explore or Plan, restate the instruction in your delegating prompt.”Source: code.claude.com
Checkpoint 4 of 8· Exam question
An admin sets model: claude-opus-4-8 in the project's .claude/settings.json so the whole team defaults to Opus. One engineer's sessions keep starting on Sonnet instead, and /status confirms project settings are being read. What is the most likely explanation?
Correct answer: A — The engineer has the same model key set in .claude/settings.local.json, which overrides the project-level settings.json.
- A. Correct. Among local, project, and user scopes, the closer scope (local) overrides the broader one (project). A model key duplicated in settings.local.json would take precedence over the project's settings.json even though /status confirms project settings loaded.
- B. Incorrect. The absence of an environment variable does not prevent Claude Code from reading a project-level setting; settings.json values apply without requiring a matching environment variable.
- C. Incorrect. There is no documented behavior where an older version silently ignores the model key; a stale or invalid model reference produces an explicit error rather than silent fallback to a different model.
- D. Incorrect. There is no time-based restriction limiting settings.json defaults to projects created after the setting was added; settings apply to the project directory regardless of when the file was written.
Sources1
3.Hooks that never fire
A hook that never runs usually produces no error at all, which is why it is hard to spot. The mechanics of hooks: actions that always run are covered elsewhere. For debugging, start with /hooks. If the hook is missing from that list, it wasn't loaded. If it is listed but never fires, its matcher matches nothing.
These causes come up again and again:
- Standalone file: the hook sits in its own file. Project and user hooks go under the
"hooks"key insettings.json; only plugins load a separatehooks/hooks.json. - Array matcher: the matcher is a JSON array instead of one string. Claude Code flags this as an invalid setting at startup and in
claude doctor. Under PreToolUse or PermissionRequest it also stops every other hook in that file from loading. - Lowercase name:
"bash"matches nothing, because matching is case-sensitive and tool names are capitalized (Bash,Edit,Write,Read). - Comma separator on an old version: before v2.1.191,
"Edit,Write"was evaluated literally and never matched."Edit|Write"works on every version. - Misspelled tool name: the matcher matches nothing, so the hook fails silently.
Checkpoint 5 of 8· Match them up
A teammate's hooks never run. Match each hook setup to what Claude Code does with it.
Tap a term, then the definition that fits it.
A hook that never fires has either not loaded (a standalone file, or a file broken by an array matcher under PreToolUse) or loaded with a matcher that matches nothing (lowercase name, or a comma on an old version). Neither case produces an error at runtime. An array matcher under PreToolUse is the worst case, because it takes down every other hook in the same file.
“If the array is under PreToolUse or PermissionRequest, none of that file’s other hooks load either.”Source: code.claude.com
Sources1
4.Three MCP failure states and their fixes
"The MCP server isn't working" can mean three different states, and each has a different fix. /mcp shows which one you are in. Apply the fix for that state; a fix for one of the others won't help.
| What /mcp shows | What it means | Fix |
|---|---|---|
| failed | The server process didn't start; relative paths in command or args are a frequent cause, because they resolve against the launch directory | Use absolute paths for local scripts; executables on PATH like npx or uvx work as-is |
| Not listed / disabled (project server) | The one-time approval prompt for a server in .mcp.json was dismissed | Approve it from /mcp |
| connected, zero tools | The server started but isn't returning a tool list | Select Reconnect; if still zero, run claude --debug=mcp and read the server's stderr in ~/.claude/debug/<session-id>.txt |
The zero-tools state is the one people misdiagnose most often. A connected server has already started, so path fixes and re-approval are both aimed at problems you don't have. The useful evidence is the server's own stderr, which only shows up in the debug log. Safe mode doesn't apply here either: it turns MCP servers off entirely, so a server that shows as connected is not running under safe mode.
A server that never appears at all usually means the config file wasn't read. Project servers belong in .mcp.json at the repository root, not under .claude/, and they must sit under mcpServers rather than a VS Code-style servers key. settings.json doesn't read an mcpServers key at all. If a server starts but is missing environment variables, set them per server inside its .mcp.json entry.
Checkpoint 6 of 8· Match them up
Each line below describes an MCP server that isn't working. Match each one to the fix that addresses it.
Tap a term, then the definition that fits it.
Each state needs its own fix. A server that is connected but lists zero tools has already started and been approved, so changing paths or approving it again won't help. The evidence you need is the server's stderr, which appears in the debug log.
“A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list. Select Reconnect from /mcp.”Source: code.claude.com
Checkpoint 7 of 8· Exam question
A team's project relies on an internal MCP server for ticket lookups. Running /mcp shows the server status as connected, but Claude reports it has no tools available from that server and cannot look up tickets. What is the correct next step to diagnose the failure?
Correct answer: A — Select Reconnect for the server from /mcp, and if the tool count stays at zero, run claude --debug mcp to see the server's stderr output.
- A. Correct. A server that shows connected but lists zero tools has started but isn't returning a tool list. The documented step is to select Reconnect from /mcp, and if the count stays at zero, run claude --debug mcp to inspect the server's stderr output.
- B. Incorrect. A relative path in command or args typically causes the server to fail to start entirely, which shows as failed in /mcp, not connected with zero tools. That is not the situation described here.
- C. Incorrect. Project-scoped approval does not silently expire; once approved, a server stays enabled. This does not explain a connected server returning no tools.
- D. Incorrect. Safe mode disables all MCP servers for the session, so the server would not show as connected at all, let alone connected with zero tools. This is not a diagnostic step for this symptom.
Sources1
5.Isolate the cause with safe mode or a clean config directory
Isolation is for when the reporting commands look normal but the problem persists. Safe mode is the quick first step. Start with claude --safe-mode, or set CLAUDE_CODE_SAFE_MODE, and CLAUDE.md, skills, plugins, hooks, MCP servers, and custom commands and agents all stay unloaded. Authentication, model selection, built-in tools and permissions keep working. If the problem goes away, one of the disabled customizations is responsible. The same test works for runaway CPU or memory: if usage drops in safe mode, start looking at plugins, MCP servers and hooks.
A clean configuration directory goes further and tells you which layer is at fault. Create an empty directory, then start Claude Code there with its config pointed at a fresh location and only user settings sources enabled:
mkdir -p ~/claude-clean/empty && cd ~/claude-clean/emptyCLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources userThen reproduce the problem. If it's gone, the cause is in your user or project configuration. Copy ~/.claude.json and the files in ~/.claude into the clean directory one at a time until the problem comes back. If none of them brings it back, move to the project directory and launch without --setting-sources user. If the problem persists even in the clean setup, the cause is outside user and project configuration. Run /status to check for managed settings, then look at your shell's environment variables.
Checkpoint 8 of 8· Fill the gap
Safe mode made the problem go away. You now want to find out which configuration layer causes it, so you launch from an empty directory with a fresh config location. Which value completes the launch command?
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources ? The clean run enables only user settings sources, so project and local settings are left out. If the problem doesn't come back after you copy in each user file, you then launch from the project directory without --setting-sources user to bring the project layer in. Managed settings can't be switched off from here. If the problem persists even in the clean setup, check /status for managed settings.
Source: code.claude.comSources
(2)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/debug-your-configOfficial docs
“Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
↩︎ Start from the symptom, then ask what loaded“Enables debug logging for the session and prompts Claude to diagnose using the log output and settings paths”
↩︎ Start from the symptom, then ask what loaded“~/.claude.json holds app state and UI toggles. permissions, hooks, and env belong in ~/.claude/settings.json.”
↩︎ Settings, memory files and permission rules that silently miss“Subdirectory files load on demand, not at session start”
↩︎ Settings, memory files and permission rules that silently miss“The built-in Explore and Plan agents skip CLAUDE.md at startup.”
↩︎ Settings, memory files and permission rules that silently miss“Bash rules match the literal command string, not the underlying executable”
↩︎ Settings, memory files and permission rules that silently miss“If the array is under PreToolUse or PermissionRequest, none of that file’s other hooks load either.”
↩︎ Hooks that never fire“Matching is case-sensitive. Tool names are capitalized: Bash, Edit, Write, Read.”
↩︎ Hooks that never fire“A server that fails to start shows as failed in /mcp.”
↩︎ Three MCP failure states and their fixes“If the prompt was dismissed, the server stays disabled until you approve it from /mcp.”
↩︎ Three MCP failure states and their fixes“run claude --debug=mcp and read the server’s stderr in the debug log at ~/.claude/debug/<session-id>.txt.”
↩︎ Three MCP failure states and their fixes“Problem persists: the cause is outside your user and project configuration.”
↩︎ Isolate the cause with safe mode or a clean config directory“Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
↩︎ Key concept“settings.local.json overrides settings.json, and both override ~/.claude/settings.json.”
↩︎ Exam trap 1“A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list.”
↩︎ Exam trap 2“A misspelled tool name produces a matcher that matches nothing, so the hook fails silently.”
↩︎ Exam trap 3“/status | Active settings sources, including whether managed settings are in effect”
↩︎ Checkpoint“settings.local.json overrides settings.json, and both override ~/.claude/settings.json.”
↩︎ Prediction“Use a PreToolUse hook or the sandbox for a hard guarantee.”
↩︎ Checkpoint“For Explore or Plan, restate the instruction in your delegating prompt.”
↩︎ Checkpoint“A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list. Select Reconnect from /mcp.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/whats-new/2026-w24Official docs
“If a problem disappears in safe mode, one of those surfaces is the cause.”
↩︎ Isolate the cause with safe mode or a clean config directory“Authentication, model selection, built-in tools, and permissions still work.”
↩︎ Isolate the cause with safe mode or a clean config directory