Debug your Claude Code configuration

When Claude ignores an instruction, or a hook, skill or MCP server you set up does nothing, the cause is usually one of three things: the file did not load, it loaded from a different place than you expected, or another file overrode it. Claude Code has commands that show what it actually loaded, so you can stop guessing.

Step 1: see what loaded

Run /context first. It breaks down what fills the context window: the system prompt, tools, MCP tools, subagents, memory files, skills and the conversation. If your CLAUDE.md or a skill is missing from the list, it did not load. Then use the command for the specific thing:

/memory: where your memory files are, with a way to open each one.
/skills: the skills available from project, user and plugin sources.
/hooks: the hooks that are active.
/mcp: connected MCP servers and their status.
/permissions: the allow and deny rules in effect.
/status: which settings sources are active, including whether managed settings apply.
/doctor: a checkup that looks for invalid settings files and other problems, and proposes fixes.
/debug: turns on debug logging for the session and asks Claude to read it.

Folder-level CLAUDE.md files in subdirectories load on demand, not at session start, so they do not appear in /context until Claude reads something in that folder.

It loaded but Claude still ignores it

Then the problem is probably how the instruction is written, not whether it loaded. The documentation lists three causes: the instruction is vague enough to read two ways, two files contradict each other, or the file has grown so long that individual rules get less attention. See the memory guide. And if something must happen every time, do not rely on CLAUDE.md: permissions and hooks enforce limits whatever Claude decides. This guide explains which to use.

Settings: which value wins

Settings merge across managed, user, project and local scopes. Managed settings apply first when present. Among the rest, local overrides project, and project overrides user. Command-line flags and environment variables can override again. So a value you set is often just being overridden somewhere else. Run claude doctor in your terminal for read-only diagnostics, including invalid settings files, without starting a session. More in the settings guide.

MCP servers that do not show up

Servers in a project's .mcp.json need a one-time approval. If you dismissed the prompt, approve the server from /mcp.
A server that fails to start is marked failed in /mcp. Relative paths in command or args are a common cause, because they resolve from where you launched Claude Code, not from the .mcp.json file.
Connected but zero tools: choose Reconnect in /mcp. If it stays at zero, run claude --debug=mcp and read the server's errors in the debug log.
Project servers belong in a .mcp.json at the repository root, under the mcpServers key, not inside .claude/ and not in settings.json.

See adding an MCP server.

Hooks that never fire

Run /hooks. If your hook is not listed, it did not load. Hooks go under the "hooks" key in a settings file, not in a standalone file. If it is listed but never fires, look at the matcher:

Use a single string, not a JSON array. To match several tools, join them with |, for example "Edit|Write".
Matching is case-sensitive. Tool names are capitalized: Bash, Edit, Write, Read.
A misspelled tool name matches nothing, and the hook fails silently.

To watch it live, start a session with claude --debug and trigger the tool call. The log shows which matchers were checked and the hook's exit code. See the hooks guide.

Other usual suspects

Permissions or hooks you put in ~/.claude.json are ignored. That file holds app state. They belong in ~/.claude/settings.json, a different file.
A value in settings.json seems ignored: check settings.local.json, which overrides it.
A skill does not appear in /skills: it must be a folder with a SKILL.md inside, such as .claude/skills/name/SKILL.md, not a loose name.md. See writing a skill.
A subagent ignores CLAUDE.md: the built-in Explore and Plan agents skip it at startup, so restate the instruction in your prompt. For your own subagent, put critical instructions in the agent file. See writing a subagent.
A Bash(rm *) deny rule does not stop /bin/rm or find -delete, because Bash rules match the literal command text. For a hard guarantee, use a hook or the sandbox. See the permissions guide.

Test against a clean configuration

Start with claude --safe-mode. It launches a session with your customizations turned off: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles and keybindings. Login, model choice, built-in tools and permissions work as normal, and managed policy from your organization still applies. If the problem disappears, it is one of the things that were switched off, and you can check them one by one with the steps above.

If it persists, start with none of your own configuration at all. In an empty directory, point Claude Code at a fresh config folder and turn off project settings:

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

In PowerShell, set $env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config" first. It stays set for that window until you run Remove-Item Env:CLAUDE_CONFIG_DIR. Expect the first-run setup screens again; that tells you the clean folder is in use. If the problem is gone there, copy your files across one at a time to find the culprit. If it stays, the cause is outside your own configuration, for example managed settings or an environment variable.

Good to know

This page covers configuration. Installation and login problems have their own troubleshooting pages.
Some commands and fixes depend on your version, so run claude --version and check the documentation if one is missing.

Try it on something harmless

Run /context and find your CLAUDE.md in the list.
Run /doctor and read what it reports.
Run claude --safe-mode once and notice what is missing.

This follows Anthropic's documentation on debugging your configuration as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.