claude-code - 💡(How to fix) Fix [DOCS] Bash tool docs omit how shell snapshots preserve aliases and user functions

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Bash tool behavior

Current Documentation

The Bash tool docs currently say:

The Bash tool runs each command in a separate process with the following persistence behavior:

• When Claude runs cd in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings.
• Environment variables do not persist. An export in one command will not be available in the next.

Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set CLAUDE_ENV_FILE to a shell script before launching Claude Code, or use a SessionStart hook to populate it dynamically.

The Claude directory docs also say:

shell-snapshots/ | Captured shell environment used by the Bash tool. Removed on clean exit. The sweep clears any left after a crash.

What's Wrong or Missing?

Changelog v2.1.147 says:

Fixed shell snapshot dropping user functions whose names start with a single underscore, which broke aliases referencing them

The current docs mention shell snapshots and Bash persistence rules, but they never explain that the Bash tool's startup shell snapshot is expected to preserve user-defined shell functions and aliases loaded at startup.

That leaves an important gap:

A. The supported behavior is undocumented

Users cannot tell from tools-reference whether aliases and helper functions from their shell startup files are supposed to be available in Bash tool commands, or whether that behavior is incidental.

B. The troubleshooting model is incomplete

The docs explain cd carry-over, non-persistent export, and CLAUDE_ENV_FILE, but they do not explain how those rules relate to aliases or shell functions captured in the shell snapshot. When an alias depends on a helper function, users have no doc-backed way to reason about whether that should work.

Suggested Improvement

Add a short paragraph to Bash tool behavior that explains:

• Claude Code captures a startup shell snapshot for Bash tool commands.
• That snapshot includes shell definitions loaded at startup, including aliases and user-defined shell functions.
• Aliases that call helper functions are expected to work when those functions are present in the startup shell.
• Changes made inside one Bash command still do not persist to the next command, so per-session or per-directory updates should use CLAUDE_ENV_FILE or hooks.

Also expand the shell-snapshots/ entry in claude-directory so "captured shell environment" is concrete instead of generic.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Relevant release: v2.1.147