Claude Code Safe Mode: Fix a Broken Config Fast
claude --safe-mode launches with zero customizations active. If the problem vanishes, you know exactly which surface broke it — and this guide walks you through the fix.
Reviewed for accuracy by Evgenii Arsentev, PhD · 2026-06-24
Safe mode launches Claude Code with every customization turned off: no CLAUDE.md, no skills, no plugins, no hooks, no MCP servers, no custom commands or agents. Everything that's part of your personal setup disappears for that session. If the problem you're chasing goes away, one of those surfaces is the culprit — and you didn't have to delete or rebuild anything to find out.
I'm Evgeny. I've seen configurations grow quietly for months until they fight each other in ways nobody can explain. Safe mode is the fastest way to cut through that tangle — one flag, and you're back to factory defaults in seconds.
What does Claude Code safe mode actually disable?
What's off vs. what still works
- 1OFF: CLAUDE.md files — none of your project or personal instructions load.
- 2OFF: Skills and custom commands — your slash shortcuts and saved playbooks don't appear.
- 3OFF: Plugins — every plugin and its tools are stripped out.
- 4OFF: Hooks — nothing fires before or after tool use.
- 5OFF: MCP servers — no connected services. Claude Code's built-in tools only.
- 6OFF: Custom subagent definitions — your ~/.claude/agents/ and .claude/agents/ files don't load.
- 7STILL ON: Login, model selection, built-in tools, permissions.
- 8STILL ON: Managed settings from your organization (policy hooks and the status line still apply).
How do I start Claude Code safe mode?
claude --safe-mode
Add --safe-mode when you launch and everything from your personal setup is suspended for that session. Nothing is deleted; it all loads normally next time. Alternatively, set CLAUDE_CODE_SAFE_MODE=1 in your environment before launching — useful if you've wrapped claude in a script and want to test from the outside. Requires Claude Code v2.1.169 or later; run claude update first if you're on an older version.
When should I use safe mode?
Reach for safe mode whenever something feels 'off' and you can't tell if Claude is the problem or your configuration is. The telltale sign is that the behavior appeared without you changing Claude Code itself — you added a CLAUDE.md rule, installed a plugin, or wired up a new MCP server, and now Claude acts strangely. Safe mode answers the question 'is it Claude or is it my setup?' in one launch.
Claude ignores an instruction it used to follow. A tool call fires a hook that shouldn't be running. A plugin command doesn't appear or crashes. Claude's behavior changed after you copied someone else's CLAUDE.md. A new MCP server seems to confuse Claude's tool choices. Any of these: run safe mode first.
Problem disappears in safe mode — which surface broke it?
Narrow it down in five minutes
- 1Start with CLAUDE.md. Run /memory in a normal session and look at what loaded. A long or contradictory CLAUDE.md is the most common culprit — comment out sections and restart until the behavior changes.
- 2Check plugins. Run /plugin in a normal session and disable them one at a time. Restart after each removal.
- 3Check hooks. Run /hooks to see every active hook. A hook with a misspelled matcher can fire on every tool call or never fire. Try removing hooks from settings.json temporarily.
- 4Check MCP servers. Run /mcp and look for servers that show as failed or that recently changed. Disconnect them and retest.
- 5Check skills and custom agents. Run /skills and /agents. A skill with 'disable-model-invocation: false' (the default) can be triggered by Claude at unexpected moments.
Problem persists even in safe mode?
If the issue survives safe mode, it's not your personal configuration — it's outside your ~/.claude files. The next step is a completely clean session that also bypasses user settings. This is the nuclear option, but it's still harmless and reversible.
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
This points Claude Code at an empty directory for its config and launches from a folder with no .claude, no .mcp.json, and no CLAUDE.md. No settings, hooks, memory, MCP servers, or plugins load from your real account. On macOS your login carries over from the Keychain; on Linux and Windows you'll be asked to log in again. If the problem disappears here, the cause is somewhere in your ~/.claude files — bring them back one piece at a time. If it persists, check whether managed settings are in effect (/status) and look for environment variables that affect Claude Code.
Lab: reproduce a problem, then fix it
0/5Safe mode is the debugging tool I wish I'd had in my first months of building with Claude Code. When a configuration works for weeks and then suddenly doesn't, the temptation is to start over. Don't. One flag, one session, and you'll know in five minutes exactly which part of your setup needs attention — not all of it.
Author
Evgenii Arsentev
PhD · Chief Product Officer at a tech company
▌ Reading is the blue pill
Want to actually build this?
Guides explain. The free course transforms — personalized, gamified, and built to get you shipping fast.
◉ Start the free course →