How Claude Code's Safe Mode Finds What Broke Your Config

Sometimes Claude Code suddenly starts misbehaving. The update in the second week of June (v2.1.169) added --safe-mode, a flag that boots Claude Code with all of your own settings turned off. Per Anthropic's official docs, it exists to isolate config problems.

One flag turns off all your customizations at startup

You run it by adding a single flag to your usual command.

claude --safe-mode

When you launch it this way, none of the settings you added yourself get loaded in that session. Your normal environment stays untouched; only the session you start with this command runs from a clean state, according to the official docs.

Some things get turned off, some stay on

What does not load in safe mode:

• CLAUDE.md
• skills
• plugins
• hooks
• MCP servers
• your own custom commands and agents

In other words, everything you wired up by hand gets dropped.

On the other hand, login authentication, model selection, built-in tools, and permissions keep working. So safe mode doesn't leave you unable to do anything; you still get the core features, just without the settings you added, which makes for a clean comparison.

One caveat. Managed settings deployed by your organization (policy hooks, status line) are still partially applied even in safe mode, according to the official docs. So in a corporate environment, some things may not turn off even in safe mode.

If the problem disappears, one of those settings is the cause

The way you use it is simple. If a symptom that shows up in your normal session goes away when you launch with --safe-mode, that's a sign one of the dropped settings is the cause.

From there you re-enable plugins or MCP servers one at a time to narrow it down. The more settings you stack up, the harder it gets to find "what broke things" — and this flag gives you a one-line starting point.

You can also turn it on with an environment variable

Instead of the flag, setting the CLAUDE_CODE_SAFE_MODE environment variable has the same effect, according to the official docs. It's handy in places like CI or scripts where adding the flag every time is a hassle.

The more plugins, MCP servers, and hooks you run, the more often you'll hit config conflicts — and being able to quickly establish a clean baseline in those moments is the practically important part. How much it actually speeds up diagnosis is something you'll have to judge by trying it yourself.

Sources: Claude Code — What's new (Week 24), Debug your config

This post summarizes an official announcement. It was not sponsored by Anthropic in any form.

Original with full infographics and visual structure: https://jessinvestment.com/how-claude-codes-safe-mode-finds-what-broke-your-config/