[DOCS] Document CLAUDE_SECURESTORAGE_CONFIG_DIR (credential-store location override — widely used by ecosystem tooling, currently undocumented)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/env-vars (also affects https://code.claude.com/docs/en/authentication and https://code.claude.com/docs/en/claude-directory)

Section/Topic

Environment variables reference; Authentication → Credential management

Current Documentation

CLAUDE_CONFIG_DIR is documented (env-vars reference; the authentication page's credential-management section: "If you've set the CLAUDE_CONFIG_DIR environment variable on Linux or Windows, the .credentials.json file lives under that directory instead"; the .claude-directory page). CLAUDE_SECURESTORAGE_CONFIG_DIR appears nowhere in the documentation, although the CLI has recognized it since roughly v2.1.144 (per community release-diffing).

What's Wrong or Missing?

CLAUDE_SECURESTORAGE_CONFIG_DIR controls which credential store a session reads and writes, independently of CLAUDE_CONFIG_DIR — on macOS it selects a distinct Keychain entry (service Claude Code-credentials plus a hashed suffix derived from the directory value); on Linux/Windows it sets the directory containing .credentials.json. It is the only mechanism we found for keeping several logins alongside one shared configuration directory, and a sizable third-party ecosystem already depends on it via reverse engineering (account switchers, fleet managers, container wrappers, SDK supervisors — sample in Additional Context).

Because the semantics are undocumented, users hit sharp edges that documentation would prevent:

• Exact-string matching: the value is hashed verbatim (after NFC Unicode normalization) — no tilde expansion, no path canonicalization. Setting the variable to your default config directory's absolute path selects a different, empty credential store, which presents as a lost login.
• Empty string ≠ unset: an empty value pins the default credential store even when CLAUDE_CONFIG_DIR is set; merely unsetting the variable does not, because CLAUDE_CONFIG_DIR then drives the derivation.
• In-place overwrite hazard: running /login with a stale inherited value pointing at another account's directory silently overwrites that account's stored credential (that account must log in again).

Precedent: CLAUDE_CONFIG_DIR itself was community-discovered and undocumented until #33430 requested documentation; it is now covered in three places.

Suggested Improvement

Documentation in three places, matching how CLAUDE_CONFIG_DIR is covered:

1. Environment variables reference: a table row — purpose, default behavior (falls back to the CLAUDE_CONFIG_DIR-derived location), and the empty-string pin.
2. Authentication → Credential management: a short subsection — per-platform behavior (Keychain service selection on macOS; .credentials.json relocation elsewhere), precedence over CLAUDE_CONFIG_DIR, the exact-string matching caveat, a multi-account example (several accounts sharing one ~/.claude), and a warning about /login under a stale value.
3. .claude directory page: a one-line note that the credential store follows this variable rather than CLAUDE_CONFIG_DIR when set.

We have complete proposed text drafted for all three locations, verified against the shipped binary in 2.1.206/2.1.207 and 2.1.215, and are happy to contribute it here (or as a PR, if a docs-contribution path exists) — say the word.

Impact

Medium - Makes feature difficult to understand

Additional Context

Third-party tooling currently relying on the undocumented variable (sample): claudex-switch, agent-fleet, claude-pod, lightcode, ClaudeUI, comate, vibespace, hindsight and switchroom (which pin it to the empty string in their container/provider setups to force the default store), tokenmaxxing (which fails fast if it is set), and others surfaced by a GitHub code search for the variable name.

Related issues showing users and tools reasoning about credential state without documented semantics: #79222 (the /status/banner display bug this variable makes deterministic to reproduce — root cause traced there), and the symptom family #74217, #78838, #72552.