[DOCS] `--safe-mode` flag and `CLAUDE_CODE_SAFE_MODE` env var undocumented in CLI reference, env-vars, and troubleshooting pages

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

• The "CLI flags" table in cli-reference.md (which is the authoritative list of claude flags)
• The environment variables table in env-vars.md (for CLAUDE_CODE_SAFE_MODE)
• The "Test against a clean configuration" section in debug-your-config.md (which currently documents only the manual CLAUDE_CONFIG_DIR workaround)
• The troubleshooting pages troubleshooting.md and troubleshoot-install.md (which link to the broader troubleshooting guide but never point to a "disable all customizations" path)

Current Documentation

The v2.1.169 changelog entry reads:

"Added --safe-mode flag (and CLAUDE_CODE_SAFE_MODE) to start Claude Code with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled for troubleshooting"

The flag itself does not appear anywhere in the docs mirror. The closest existing guidance is in docs/code.claude.com/docs/en/debug-your-config.md, which currently documents only a manual workaround:

"If targeted checks don't isolate the cause, or your configuration is in an unknown state, compare against a session that loads nothing from your usual setup. Point CLAUDE_CONFIG_DIR at an empty directory to bypass everything under ~/.claude, and launch from a directory that has no .claude folder, .mcp.json, or CLAUDE.md so project configuration is also skipped. ``bash cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude `` The clean session has no user or project settings, hooks, MCP servers, plugins, or memory."

The CLI reference flags table (docs/code.claude.com/docs/en/cli-reference.md lines 49-117) is sorted alphabetically and lists every other claude flag — including related "isolation" flags such as --bare (line 58), --setting-sources (line 105), --strict-mcp-config (line 107), and --disable-slash-commands (line 68) — but does not list --safe-mode.

The environment variables table in docs/code.claude.com/docs/en/env-vars.md lists dozens of CLAUDE_CODE_* variables (including CLAUDE_CODE_SIMPLE, CLAUDE_CODE_SKIP_PROMPT_HISTORY, and CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) but does not include CLAUDE_CODE_SAFE_MODE.

What's Wrong or Missing?

A. The --safe-mode flag is not listed in the CLI reference

A user reading cli-reference.md cannot discover --safe-mode from any link, search, or table entry. The flag's sole mention in the entire docs mirror is the v2.1.169 changelog line. There is no description of what it disables (CLAUDE.md, plugins, skills, hooks, MCP servers) and no usage example such as claude --safe-mode or claude --safe-mode -p "query".

B. CLAUDE_CODE_SAFE_MODE is not listed in the env-vars reference

The environment-variables page is the canonical reference for CLAUDE_CODE_* settings. The new env var is not documented there, so users who know to set environment variables for troubleshooting cannot find this option.

C. The "Test against a clean configuration" section does not mention the new flag

debug-your-config.md is the page that describes how to bisect configuration problems. Its "Test against a clean configuration" section only shows the multi-step CLAUDE_CONFIG_DIR=/tmp/claude-clean workaround. A user following that page to troubleshoot would not learn that v2.1.169 introduced a one-step equivalent (claude --safe-mode) that does not require a temporary directory or shell dance. Given that the changelog explicitly markets safe-mode as a "troubleshooting" feature, this is the page that should mention it most prominently.

D. The troubleshooting pages do not link to safe-mode

troubleshooting.md and troubleshoot-install.md are the entry points for users who hit unexpected Claude Code behavior. Neither mentions --safe-mode as a recommended first step before deeper debugging.

Suggested Improvement

Option A: Comprehensive fix

Add three documentation updates, all referencing the v2.1.169 changelog:

1. In docs/code.claude.com/docs/en/cli-reference.md, add a new row to the "CLI flags" table (alphabetically between --resume and --session-id):

| `--safe-mode` | Start Claude Code with CLAUDE.md, plugins, skills, hooks, and MCP servers all disabled, for troubleshooting configuration issues. Equivalent to setting `CLAUDE_CODE_SAFE_MODE=1`. Added in v2.1.169 | `claude --safe-mode` |

1. In docs/code.claude.com/docs/en/env-vars.md, add a new row to the environment variables table (near the other CLAUDE_CODE_* troubleshooting variables such as CLAUDE_CODE_SIMPLE):

| `CLAUDE_CODE_SAFE_MODE` | Set to `1` to start Claude Code with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled. Equivalent to passing `--safe-mode` on the command line. Added in v2.1.169 | `CLAUDE_CODE_SAFE_MODE=1 claude` |

1. In docs/code.claude.com/docs/en/debug-your-config.md, replace or augment the "Test against a clean configuration" section so it leads with the new flag:

"The fastest way to test against a clean configuration is claude --safe-mode (added in v2.1.169). It starts Claude Code with all customizations disabled — CLAUDE.md, plugins, skills, hooks, and MCP servers — for a single session, so you can tell whether a problem is caused by your configuration without changing your working directory or settings. If you want the same behavior in a non-interactive environment, set CLAUDE_CODE_SAFE_MODE=1. For the manual CLAUDE_CONFIG_DIR approach, see below."

Option B: Minimum fix

Add a single sentence to the existing "Test against a clean configuration" section in debug-your-config.md pointing at the new flag, and add the --safe-mode row to the CLI reference flags table. Leave env-vars.md for a later pass.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | 49-117 | "CLI flags" table — --safe-mode row is missing; alphabetically belongs between --resume (line 103) and --session-id (line 104) |
| https://code.claude.com/docs/en/env-vars | 297 area | Environment variables table — CLAUDE_CODE_SAFE_MODE row is missing |
| https://code.claude.com/docs/en/debug-your-config | 69-83 | "Test against a clean configuration" section — only documents the manual CLAUDE_CONFIG_DIR workaround |
| https://code.claude.com/docs/en/troubleshooting | 13-14 area | Top-level troubleshooting table — does not link to safe-mode |
| https://code.claude.com/docs/en/troubleshoot-install | 9 | "see Troubleshooting" pointer — does not mention safe-mode |
| https://code.claude.com/docs/en/changelog | 14 | Sole mention of the flag, as the v2.1.169 changelog entry |

Total scope: 6 pages affected, but the three primary fixes are in cli-reference, env-vars, and debug-your-config.

Related flags for context:

• --bare (cli-reference.md:58) — "Minimal mode: skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster". This is the closest existing analog and should be cross-referenced in any new --safe-mode documentation.
• CLAUDE_CODE_SIMPLE (referenced in cli-reference.md:58) — Equivalent env var to --bare. The new CLAUDE_CODE_SAFE_MODE should follow the same naming/positioning pattern.

Version: v2.1.169 (June 8, 2026)