[DOCS] Contradiction in `CLAUDE_ENV_FILE` definition between Settings and Hooks documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

1. https://code.claude.com/docs/en/settings#bash-tool-behavior (Option 2) 2. https://code.claude.com/docs/en/hooks#persisting-environment-variables (SessionStart hooks)

Section/Topic

The definition and recommended usage of the CLAUDE_ENV_FILE environment variable.

Current Documentation

In Settings > Bash tool behavior (Option 2):

"Export the path to a shell script containing your environment setup: export CLAUDE_ENV_FILE=/path/to/env-setup.sh... Claude Code will source this file before each Bash command."

In Hooks > SessionStart (Persisting environment variables):

"SessionStart hooks have access to the CLAUDE_ENV_FILE environment variable, which provides a file path where you can persist environment variables for subsequent bash commands... Example: echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE""

What's Wrong or Missing?

There is a critical contradiction in how CLAUDE_ENV_FILE is defined:

1. The Settings guide treats it as an input variable: a pointer to a user's pre-existing, static setup script.
2. The Hooks reference treats it as an output/ephemeral file: a path where Claude (via hooks) appends raw exports to persist state.

The Danger: If a developer follows the "Settings" guide and points CLAUDE_ENV_FILE to their primary, version-controlled env-setup.sh script, any SessionStart hook they (or a shared project config) run will execute >> "$CLAUDE_ENV_FILE". This will append raw export strings directly to the user's source script, potentially corrupting it, adding duplicate entries, or leaking session-specific secrets into a permanent file.

Suggested Improvement

1. Clarify the System Role: Explicitly state that CLAUDE_ENV_FILE is intended to be a temporary session file managed by Claude Code.
2. Update Settings Guide: Change "Option 2" to advise users to let Claude manage the file path, and if they have an existing script, they should source it inside a hook or use a different mechanism.
3. Warning Callout: Add a "Warning" block to both sections:

> Warning: Do not point CLAUDE_ENV_FILE to an existing source script you wish to keep clean. Claude Code and its hooks may append text to this file to persist session state. If you have an existing setup script, source it within a SessionStart hook instead.

Suggested text for Settings > Option 2:

Option 2: Use a SessionStart hook to source your existing script Instead of pointing CLAUDE_ENV_FILE to your source code, use a SessionStart hook in .claude/settings.json to source your script into the Claude environment: ``json { "hooks": { "SessionStart": [{ "matcher": "startup", "hooks": [{ "type": "command", "command": "echo 'source /path/to/your/env-setup.sh' >> \"$CLAUDE_ENV_FILE\"" }] }] } } ``

Impact

High - Prevents users from using a feature

Additional Context

• Severity: High/Critical. Documentation that leads to the accidental modification of user-owned scripts/source files is a safety issue.
• Example of collision: A user sets CLAUDE_ENV_FILE=~/.bashrc. A SessionStart hook designed to set a temporary API_KEY will now append export API_KEY=... to the user's permanent .bashrc every time Claude starts.