Find the Config Breaking Claude Code With Safe Mode

On the same machine, every other project works fine. Only this one repository throws errors whenever Claude Code calls a tool. You start a new session, the problem disappears for a while, then comes back a few turns later. The project has a CLAUDE.md, a few Skills, two Hooks, a plugin, and three MCP servers, and any of them could be the culprit.

The obvious move is to turn things off one by one, delete them one by one, or just start over with a clean configuration directory. The problem goes away, but you can't say which item caused it, and you'll run into it again. Worse, a fresh session that works for a while is easy to mistake for a fix.

The reliable way is a controlled comparison:

• start with claude --safe-mode and see whether the problem survives with all customizations off;
• if it disappears, go back to normal mode, restore one category of customization at a time, and run the same shortest reproduction;
• when restoring a category brings the problem back, narrow down within that category;
• once you've found and fixed the cause, walk the original failure path again and confirm the original checks are working too.

Keep the original configuration throughout and change one condition at a time, and the experiment's conclusion will hold up.

01 What Safe Mode Can Rule Out

If the problem only happens in one project and you can't tell whether CLAUDE.md, a Skill, a plugin, a Hook, or MCP is behind it, start with:

claude --safe-mode

The Claude Code CLI reference lists what it turns off: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes and keybindings, the status line, LSP servers, and auto memory don't load, while authentication, model selection, built-in tools, and permissions work normally.

The official configuration debugging guide adds one point: safe mode still applies managed hooks and settings policy from your organization, while managed plugins, skills, CLAUDE.md, and MCP servers are turned off. So if the problem persists in safe mode, also consider managed policy, permissions, and authentication.

02 Restore One Category at a Time

When the problem disappears in safe mode, the scope has narrowed, but the specific item isn't known yet. In the guide's words, if the problem disappears in safe mode, you've narrowed the cause to one of the items you turned off, and you then use the check for that item to find it.

Go back to normal mode, restore one category at a time, and run the shortest reproduction:

1. CLAUDE.md
2. Skills
3. Hooks
4. Plugins
5. MCP

When restoring a category brings the problem back, narrow it down further, such as to a specific group of Hooks. Change only one key condition per comparison. How to write the shortest reproduction and assign symptoms to layers is covered in troubleshooting Claude Code errors layer by layer.

03 Keep the Original Configuration During Comparison

Keep the original configuration throughout the comparison. A temporary configuration directory or a clean working directory may change authentication, discovery paths, and the environment all at once, so it doesn't count as changing a single variable. Record each change and the conditions you kept, then explain how far the experiment narrows things down.

The guide also puts the "none of your own configuration" test after safe mode: only if the problem persists in safe mode, or you suspect your settings files themselves, do you start once in an empty directory with a fresh CLAUDE_CONFIG_DIR and --setting-sources user to see whether the problem follows. That step changes the configuration directory, project settings, and working directory at once, so its conclusion can only tell you whether the problem is related to your own configuration, not which item it is.

04 A Fresh Session Can Hide a Problem That's Still There

Each session recovery tool does one job:

These tools help tidy a session. If a configuration error is still there, go back and fix the configuration. That "new session works for a while" in the opening may only mean the long context from the old session was cleared; the Hook or MCP server that triggers the problem is still there, and once its event fires again, the problem returns. Things working for a while after a restart doesn't show the root cause is gone.

05 Verify the Fix Along the Original Failure Path

After fixing, repeat the shortest reproduction you originally recorded. Keep only the necessary changes, and confirm:

1. the original error no longer appears;
2. the expected behavior actually happens and isn't silently skipped;
3. no new failure in the log has replaced the original error;
4. the fix still holds in a new session or after a restart;
5. no bigger risk was introduced by loosening permissions or disabling checks.

Items 2 and 5 are the easiest to overlook. Disabling a Hook that throws errors can remove its check at the same time: the error message goes away, and so does the protection against the write it was meant to stop. Only when the original block or formatting comes back and produces the expected result can you confirm this path is fixed. If the culprit turns out to be a same-named Skill shadowing the project version, fixing and verifying it is covered in Claude Code Skill missing from the slash menu?.

Safe mode narrows the suspects, restoring one category at a time finds the specific item, and retesting along the original path confirms the fix. When what should be blocked is blocked again and what should be formatted is formatted again, that path is truly back to normal.