[DOCS] Config directory docs omit read-only/unwritable startup fallback

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

CLAUDE_CONFIG_DIR, plus startup troubleshooting for unwritable config directories

Current Documentation

The docs currently say:

CLAUDE_CONFIG_DIR — Override the configuration directory (default: ~/.claude). All settings, credentials, session history, and plugins are stored under this path. Useful for running multiple accounts side by side: for example, alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

The installation troubleshooting page also says:

The installer needs write access to ~/.local/bin/ and ~/.claude/ on macOS and Linux. On Windows the install location is under %USERPROFILE%, which is writable by your user by default, so this section rarely applies there. Check whether the directories are writable: test -w ~/.local/bin && echo "writable" || echo "not writable" test -w ~/.claude && echo "writable" || echo "not writable"

Debug your configuration also says:

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.

What's Wrong or Missing?

In v2.1.162, the changelog says:

Fixed a silent startup hang when the config directory is read-only or unwritable — Claude Code now starts with in-memory config and surfaces startup errors instead of showing a blank screen

The current docs explain where the config directory lives and how to override it, but they do not document the new startup behavior or the failure mode it addresses.

A. The runtime fallback is undocumented

Readers are not told that when the effective config directory is read-only or otherwise unwritable, Claude Code now starts with an in-memory config instead of hanging. That matters because settings, session state, and similar config-backed data will not persist for that run.

B. CLAUDE_CONFIG_DIR troubleshooting is incomplete

The docs mention install-time writability checks for ~/.claude, but they do not explain that the same startup problem can come from a custom CLAUDE_CONFIG_DIR path. Users who relocate their config can therefore get a startup error without documentation that connects it back to the configured directory.

C. Startup symptoms are not tied to a concrete remediation path

The docs do not explain that this was the root cause behind the prior blank-screen/silent-hang behavior, and they do not give a runtime-focused fix such as checking writability of the effective config directory or temporarily pointing CLAUDE_CONFIG_DIR at a writable location.

Suggested Improvement

Add a short note anywhere CLAUDE_CONFIG_DIR and startup troubleshooting are documented. For example:

If the effective Claude Code config directory is read-only or unwritable, Claude Code v2.1.162 and later starts with an in-memory config and shows a startup error instead of hanging or showing a blank screen. Changes from that session are not persisted.

Then add a remediation checklist:

• Check writability of the effective config directory, not just ~/.claude
• If CLAUDE_CONFIG_DIR is set, verify that path specifically
• Use a writable temporary directory (for example, CLAUDE_CONFIG_DIR=/tmp/claude-clean claude) to confirm the diagnosis

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/env-vars | 265 | CLAUDE_CONFIG_DIR describes relocation only |
| https://code.claude.com/docs/en/claude-directory | 1433-1435 | explains that ~/.claude paths move under CLAUDE_CONFIG_DIR |
| https://code.claude.com/docs/en/agent-view | 478-489 | background-session state is stored under the config directory |
| https://code.claude.com/docs/en/debug-your-config | 71-83 | recommends using an empty CLAUDE_CONFIG_DIR for a clean session |
| https://code.claude.com/docs/en/troubleshoot-install | 239-248 | only documents install-time writability checks for ~/.claude |
| https://code.claude.com/docs/en/troubleshooting | 22, 51-58 | generic claude doctor and hang guidance, but no config-directory startup failure note |

Total scope: 6 pages affected

Version context: v2.1.162 changelog entry: "Fixed a silent startup hang when the config directory is read-only or unwritable — Claude Code now starts with in-memory config and surfaces startup errors instead of showing a blank screen"