Claude Code --safe-mode: Troubleshoot Without Customizations

New Troubleshooting Mode for Complex Setups

Claude Code 2.1.169 introduces --safe-mode, a dedicated troubleshooting flag that starts the tool in a stripped-down state with every customization layer disabled. When a session launches with --safe-mode (or the equivalent CLAUDE_CODE_SAFE_MODE environment variable set), Claude Code skips loading CLAUDE.md files at all directory levels, ignores installed plugins and skills, bypasses hooks, and does not connect to any MCP servers.

Why This Matters

As Claude Code installations grow more elaborate, diagnosing unexpected behavior has become increasingly difficult. A session might behave strangely because of a hook that intercepts tool calls, a skill that injects conflicting instructions, a CLAUDE.md that overrides permissions, or an MCP server that returns unexpected data. Before this change, isolating the root cause required manually disabling each component one at a time: a slow, error-prone process.

With --safe-mode, developers now have a reliable first step: run the same task in safe mode and compare the results. If the problem disappears, the customization layer is at fault; if it persists, the issue is in the core tool. This binary split dramatically shortens the debugging cycle.

The companion disableBundledSkills setting (also added in this release) offers a more targeted option: it hides Claude Code's built-in bundled skills from the model without disabling user-defined customizations, useful for teams that want full control over what instructions the model sees.

How to Use It

# Start a session with all customizations disabled
claude --safe-mode

# Or set the environment variable
CLAUDE_CODE_SAFE_MODE=1 claude

This flag is additive with other flags and works in both interactive and headless (-p) modes.