{"slug": "claude-code-safe-mode-find-which-customization-broke-your-agent", "title": "Claude Code Safe Mode: Find Which Customization Broke Your Agent", "summary": "Anthropic added --safe-mode to Claude Code v2.1.169 to help users isolate whether a customization layer—such as CLAUDE.md rules, hooks, skills, plugins, or MCP servers—is causing broken behavior. Running with the flag disables all customizations except managed settings, allowing users to re-enable layers one at a time to identify the source of the problem.", "body_md": "# Claude Code Safe Mode: Find Which Customization Broke Your Agent\n\nWhen Claude Code stops following your rules or tools behave unexpectedly, the hard part is knowing whether the model drifted or your customization stack broke. Anthropic added `--safe-mode`\n\nin v2.1.169 to answer that question with one flag: strip every customization layer and get a clean baseline.\n\nOne flag. Clean baseline. Re-enable layers one at a time until the symptom returns.\n\n## What “broken” looks like\n\nThese symptoms show up once a repo has a real customization stack — not day-one setup, but weeks of hooks, skills, and MCP servers layered on:\n\n**Ignored instructions.**`CLAUDE.md`\n\nsays “run tests before commit.” Claude commits anyway. Or a subdirectory rule never loads when you expect it to.**Wrong tool behavior.** A PreToolUse hook fires on every save instead of every commit. A deny rule doesn’t block the variant you actually typed.**Mystery MCP failures.** A server shows connected in`/mcp`\n\nbut returns zero tools. Or a relative path in`.mcp.json`\n\nworks from one directory and fails from another.**Runaway resource use.** High CPU or memory that doesn’t match the task size — often a plugin or hook loop, not the model.\n\nThe common thread: you can’t tell which layer owns the failure. Model? Permissions? A stale plugin? A hook matcher typo?\n\nSafe mode answers the first question: **is this your customization stack, or something else?**\n\n## What safe mode actually disables\n\nAs of June 2026, start Claude Code with:\n\n```\nclaude --safe-mode\n```\n\nOr set the environment variable for scripts and CI:\n\n```\nCLAUDE_CODE_SAFE_MODE=1 claude\n```\n\nBoth were added in [v2.1.169](https://github.com/anthropics/claude-code/releases/tag/v2.1.169) (Week 24, June 8–12). The [CLI reference](https://code.claude.com/docs/en/cli-reference) lists the full disable surface:\n\n| Disabled in safe mode | Still works |\n|---|---|\n`CLAUDE.md` and rules / auto-memory | Authentication |\n| Skills (project, user, plugin) | Model selection |\n| Plugins | Built-in tools |\n| Hooks (user/project) | Permissions (your allow/deny rules) |\n| MCP servers (user/project) | Managed settings policy (partial — see below) |\n| Custom commands and agents | |\n| Output styles, workflows, custom themes, keybindings | |\n| Status line and file-suggestion commands (unless policy-configured) | |\n| LSP servers |\n\n**Important nuance from the docs:** safe mode is not `--bare`\n\n. Managed settings deployed by your org still partially apply. Policy-configured hooks, status line, and file-suggestion commands can run even in safe mode. Managed plugins, managed skills, managed `CLAUDE.md`\n\n, and policy-configured MCP servers do not load. If you’re on Enterprise with org-managed config, a symptom that survives safe mode may still be policy — run `/status`\n\nto see what’s in effect.\n\nIf the problem **disappears** in safe mode, the cause is in one of the disabled surfaces. If it **persists**, look elsewhere: model behavior, rate limits, upstream outages, or environment variables outside your usual `~/.claude`\n\ntree.\n\n## The isolation playbook\n\nThe order below matches Anthropic’s [debug guide](https://code.claude.com/docs/en/debug-your-config) and common troubleshooting practice: start with surfaces that change behavior without obvious errors, then work toward integrations that are harder to inspect.\n\n### Step 0: Confirm the baseline\n\n```\nclaude --safe-mode\n```\n\nReproduce the symptom. Same repo, same prompt, same task.\n\n**Fixed?** Your stack is the suspect. Continue.**Not fixed?** Skip to[When safe mode isn’t the answer](#when-safe-mode-isnt-the-answer).\n\nFor comparison, run `/context`\n\nand `/memory`\n\nin a normal session later. Safe mode should show a stripped context — no skills, no MCP tools from your config.\n\n### Step 1: Re-enable one surface at a time\n\nExit safe mode. Restart a normal session and add layers back in this order:\n\n— Often involved when “Claude ignores my conventions.” Check`CLAUDE.md`\n\n/ rules`/memory`\n\nto confirm what loaded. Subdirectory`CLAUDE.md`\n\nfiles load on demand when Claude reads a file in that directory, not at session start.**Skills**— Run`/skills`\n\n. A skill can appear but never invoke if the description doesn’t match how you phrase the request, or if`disable-model-invocation`\n\nis set.**Hooks**— Run`/hooks`\n\n. Matcher typos fail silently: tool names are capitalized (`Bash`\n\n, not`bash`\n\n), and`matcher`\n\nmust be a string with`|`\n\n, not a JSON array. If the hook shows but doesn’t fire, restart with`claude --debug hooks`\n\nand trigger the tool call.**Plugins**— Marketplace plugins can drift across updates. Note the version when you isolate one.** MCP servers**— Run`/mcp`\n\n. Project servers in`.mcp.json`\n\nat the**repo root** need one-time approval. Relative paths in`command`\n\nresolve from your launch directory, not the config file location.\n\nAfter each layer, reproduce the symptom. **Stop when it returns.** The last layer you added is your failure receipt — write down the file, the version, and the exact behavior.\n\n### Step 2: Quarantine before you fix\n\nDon’t patch in place while you’re still guessing. Rename the suspect hook entry, move a plugin to a disabled list, or comment out one MCP server block. Confirm the symptom clears. Then fix properly.\n\n### Step 3: Deeper clean session (optional)\n\nIf safe mode fixed the problem but re-adding everything at once brings it back and you can’t isolate a single layer, Anthropic’s [debug guide](https://code.claude.com/docs/en/debug-your-config) recommends a fully clean config dir:\n\n```\ncd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude\n```\n\nThat bypasses everything under `~/.claude`\n\nand project `.claude`\n\n/ `.mcp.json`\n\n/ `CLAUDE.md`\n\n. Reintroduce files one at a time. On Linux and Windows you’ll log in again; on macOS credentials live in Keychain and carry over.\n\n## Example: hook matcher scope\n\nThis pattern appears often in hook troubleshooting — not a single logged incident, but a documented failure mode from the [hooks docs](https://code.claude.com/docs/en/hooks) and debug guide.\n\n**Symptom:** A PreToolUse hook intended to gate commits fires on every `Edit`\n\nand `Write`\n\n. Sessions feel sluggish; Claude pauses mid-refactor.\n\n**In safe mode:** Edits proceed normally. No hook pauses. Symptom gone.\n\n**After re-enabling hooks only:** Pauses return. Likely cause: matcher set to `\"Edit|Write\"`\n\nwhen the intent was commit-time checks only. The hook shows up in `/hooks`\n\n, so the problem is easy to miss. Narrow the matcher or add a commit-specific guard.\n\nSafe mode doesn’t repair the workflow — it identifies which layer to inspect next.\n\n## When safe mode isn’t the answer\n\nDon’t spend a troubleshooting session on config when the problem is upstream:\n\n**Model regressions or policy changes.** Different reasoning, different refusals, different tool choices with the same config. Compare across models; check release notes.**Rate limits and overload.**`429`\n\n,`529`\n\n, fallback model behavior. Safe mode won’t change API capacity.**Outages.** Check status and`/doctor`\n\nbefore you bisect hooks.**Search and discovery.** Missing`@file`\n\nresults or incomplete ripgrep on WSL — see[Troubleshooting](https://code.claude.com/docs/en/troubleshooting); that’s not a customization load issue.**Performance without a smoking gun.** Safe mode helps when[high CPU or memory](https://code.claude.com/docs/en/troubleshooting)drops after restart with`--safe-mode`\n\n. If usage stays high, run`/heapdump`\n\nnext — the cause may be context size, not a hook.\n\nIf safe mode and the clean-config session both fail, the cause is outside user and project files. Run `/status`\n\nfor managed settings, then check environment variables and the general troubleshooting page.\n\n## Preventing the next mystery regression\n\nSafe mode is reactive. A few habits reduce how often you need it:\n\n**Version-pin plugins** you rely on. “Latest from marketplace” and “works on my machine” diverge quietly.**Hook smoke tests.** After editing hooks, trigger the exact tool call once before trusting a long agent run.`claude --debug hooks`\n\nsurfaces matcher and execution issues early.**Document your isolation order** in the repo runbook so the next regression doesn’t start from scratch.**CI consideration:**`CLAUDE_CODE_SAFE_MODE=1`\n\ncan sanity-check that failures aren’t config-dependent before blaming a model change. Open experiment — not verified in a production pipeline here.\n\nFor harness design — when to let Claude write orchestration vs when to own it yourself — see [When to Let Claude Write the Harness](/blog/when-to-let-claude-write-the-harness/). For permission-mode defaults (auto vs default vs bypass), see [Cursor auto-review vs YOLO](/blog/cursor-auto-review-vs-yolo/). Safe mode is the troubleshooting counterpart: strip the harness until you find the broken layer.\n\n## Runbook checklist\n\nCopy this when Claude Code stops behaving:\n\n- Reproduce the symptom once (note exact prompt + tool call)\n-\n`claude --safe-mode`\n\n— same repro - If fixed: exit and re-enable CLAUDE.md → skills → hooks → plugins → MCP, one at a time\n- After each layer: repro again; stop when symptom returns\n- Quarantine the suspect layer; confirm fix; then patch properly\n- If not fixed in safe mode: check model/API/outage; try clean\n`CLAUDE_CONFIG_DIR`\n\n; run`/status`\n\nfor managed policy\n\n**What’s your isolation order?** And which surface has broken your setup — a hook matcher, a stale plugin, an MCP path that only works from one directory?", "url": "https://wpnews.pro/news/claude-code-safe-mode-find-which-customization-broke-your-agent", "canonical_source": "https://outofcontext.dev/blog/claude-code-safe-mode/", "published_at": "2026-06-19 00:00:00+00:00", "updated_at": "2026-06-25 08:48:43.454378+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/claude-code-safe-mode-find-which-customization-broke-your-agent", "markdown": "https://wpnews.pro/news/claude-code-safe-mode-find-which-customization-broke-your-agent.md", "text": "https://wpnews.pro/news/claude-code-safe-mode-find-which-customization-broke-your-agent.txt", "jsonld": "https://wpnews.pro/news/claude-code-safe-mode-find-which-customization-broke-your-agent.jsonld"}}