Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Rename `Bash` tool — it actually runs the user's login shell (zsh on macOS), not bash [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52521•Fetched 2026-04-24 06:04:58
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
kevin-jacobson-at-wistiakevin-jacobson-at-wistia
Participants
kevin-jacobson-at-wistiakevin-jacobson-at-wistia
Timeline (top)
labeled ×3

The Bash tool in Claude Code is named after bash but in practice launches commands in the user's configured login shell — on macOS, that's zsh by default. The tool's own description acknowledges this ("The shell environment is initialized from the user's profile (bash or zsh)"), but the identifier itself is never updated, which is misleading for new users and surprises experienced ones who configure hooks or permissions.

Root Cause

The Bash tool in Claude Code is named after bash but in practice launches commands in the user's configured login shell — on macOS, that's zsh by default. The tool's own description acknowledges this ("The shell environment is initialized from the user's profile (bash or zsh)"), but the identifier itself is never updated, which is misleading for new users and surprises experienced ones who configure hooks or permissions.

Code Example

# From within Claude Code's Bash tool:
echo \"ZSH_VERSION=\$ZSH_VERSION  BASH_VERSION=\$BASH_VERSION  shell=\$SHELL  ps=\$(ps -p \$\$ -o comm=)\"

---

ZSH_VERSION=5.9  BASH_VERSION=  shell=/bin/zsh  ps=/bin/zsh
RAW_BUFFERClick to expand / collapse

Summary

The Bash tool in Claude Code is named after bash but in practice launches commands in the user's configured login shell — on macOS, that's zsh by default. The tool's own description acknowledges this ("The shell environment is initialized from the user's profile (bash or zsh)"), but the identifier itself is never updated, which is misleading for new users and surprises experienced ones who configure hooks or permissions.

Reproduction

On a default macOS install:

# From within Claude Code's Bash tool:
echo \"ZSH_VERSION=\$ZSH_VERSION  BASH_VERSION=\$BASH_VERSION  shell=\$SHELL  ps=\$(ps -p \$\$ -o comm=)\"

Output:

ZSH_VERSION=5.9  BASH_VERSION=  shell=/bin/zsh  ps=/bin/zsh

No bash in the pipeline — it's zsh the whole way down, including .zshrc sourcing, aliases, functions, asdf/nvm, etc.

Why it matters

  • Misleading to new users. "Bash" implies a specific shell; the tool actually honors whatever's in $SHELL.
  • Documentation drift. Teaching materials, blog posts, and this very repo's examples all reference "Bash commands," but the commands are running in zsh for most macOS users.
  • Config surface references the name. .claude/settings.json uses Bash(git *) style allow/deny rules; hooks reference it by name. Renaming is breaking, which is likely why it's stuck.

Proposal

Two options, pick one or do both:

  1. Add an alias. Register the tool under a more accurate name (Shell, Execute, or similar) while keeping Bash as a deprecated alias for backward compatibility in settings/hooks. Announce a long deprecation window.
  2. Update the description and docs to be more prominent about the behavior. At minimum, surface "runs under your login shell (bash or zsh)" earlier/bolder in the tool description that Claude sees, and mention it in the permissions and hooks docs.

Option 1 is the right long-term fix; option 2 is the cheap immediate improvement.

Environment

  • Claude Code 2.1.118
  • macOS 25.4.0 (Tahoe)
  • Default shell: zsh 5.9

extent analysis

TL;DR

Update the tool's name or description to reflect that it runs commands in the user's configured login shell, which is zsh by default on macOS.

Guidance

  • Consider adding an alias for the tool with a more accurate name, such as Shell or Execute, to improve clarity for new users.
  • Update the tool's description and documentation to prominently mention that it runs under the user's login shell, which may be zsh or bash.
  • Review and update any teaching materials, blog posts, and examples that reference "Bash commands" to reflect the actual shell being used.
  • Consider announcing a deprecation window for the old Bash name to allow users to update their settings and hooks.

Notes

The proposed solutions aim to address the misleading naming and documentation issues, but may require additional changes to settings and hooks to ensure backward compatibility.

Recommendation

Apply workaround: Update the description and docs to be more prominent about the behavior, as this is a cheap immediate improvement that can be done while considering the long-term fix of renaming the tool.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#authentication issue#prompt issue#agent setup#task chaining#parallel task

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING