Stop Claude Code's bash-style commands from failing in zsh on macOS.
On macOS, Claude Code's Bash tool runs your commands in zsh (SHELL=/bin/zsh),
but the model writes bash. zsh rejects a few everyday bash idioms:
grep -rn foo . --include=*.ts -> (eval):1: no matches found: --include=*.ts
ls libs/*/README.md -> (eval):1: no matches found: libs/*/README.md
echo ==== -> (eval):1: === not found
G="git -C repo"; $G log -> (eval):1: command not found: git -C repo
timeout 5 make -> (eval):1: command not found: timeout
anthropics/claude-code#103027 measured 51 failures per 1,000 Bash calls, and 76% of them silent: the error is in the output, but the command as a whole still exits 0, so the model carries on with wrong or missing results. The earlier report #67146 was closed as not planned. The author's own transcripts show the same thing: about 700 failures in about 25,000 Bash calls over 12 days.
This plugin adds a SessionStart hook. When the Bash tool shell is zsh, the hook
adds one line to CLAUDE_ENV_FILE (which Claude Code runs before every Bash tool
command) that sources lib/compat.zsh. That file sets a few
zsh options so zsh handles these idioms the way bash does:
| Option / shim | Effect | Fixes |
|---|---|---|
setopt NO_NOMATCH |
an unmatched glob is passed on literally, as in bash | --include=*.ts, ls dir/*/x |
setopt NO_EQUALS |
=word is no longer a command lookup |
echo ==== |
setopt SH_WORD_SPLIT |
an unquoted $VAR splits on spaces, as in bash |
G="git -C repo"; $G log |
timeout function |
defined only if no timeout exists: uses gtimeout if installed, else a small perl version (perl ships with macOS); exit 124 on timeout, like GNU |
timeout 5 make |
It only affects the shell behind Claude Code's Bash tool, including subagents. Your terminal is unchanged. Under bash it does nothing.
Each line was run as its own Bash tool call.
Without the plugin:
$ grep -rn foo . --include=*.ts
(eval):1: no matches found: --include=*.ts
$ echo ====
(eval):1: === not found
$ ls nope/*/README.md
(eval):1: no matches found: nope/*/README.md
$ G="echo -n hello"; $G world
(eval):1: command not found: echo -n hello
$ timeout 1 sleep 3; echo "timeout exit: $?"
(eval):1: command not found: timeout
timeout exit: 127
With the plugin:
$ grep -rn foo . --include=*.ts
src/app.ts:1:const foo = 1;
$ echo ====
====
$ ls nope/*/README.md
ls: nope/*/README.md: No such file or directory
$ G="echo -n hello"; $G world
hello world
$ timeout 1 sleep 3; echo "timeout exit: $?"
timeout exit: 124
The first failure in that run is a silent one: the tool call reported success even though grep never ran.
claude plugin marketplace add JasonGDG/claude-zsh-compat
claude plugin install zsh-compat@claude-zsh-compatThe fix applies from the next session you start.
Paste snippet/zshrc-snippet.zsh at the end of
your ~/.zshrc. It is guarded by [[ -n $CLAUDECODE ]], so it only runs when
Claude Code builds its shell snapshot, not in your terminal.
bin/zsh-slips (Python 3, no dependencies) scans your local transcripts in
~/.claude/projects (subagents included) and counts zsh errors per 1,000 Bash calls:
python3 bin/zsh-slips --since 2026-10-01It prints only counts and error categories. Add --examples to see sample
commands, or --json for machine-readable output. Run it again after a week with
the plugin to compare.
${!var}(bash indirect expansion) is a syntax error in zsh and no option fixes it. Use${(P)var}in zsh, oreval.$var:h,$B:path(zsh colon modifiers) and"$pat[...]"(zsh array subscript) are only fixed byKSH_ARRAYS, which also makes arrays 0-based like bash. That is closer to what the model writes, but it changes how any zsh function from your~/.zshrcthat Claude Code copies into its snapshot sees arrays, so it is off by default. To turn it on, add"env": { "ZSH_COMPAT_KSH_ARRAYS": "1" }to~/.claude/settings.json.NO_NOMATCHmeans a glob that matches nothing is passed on literally, as in bash. The command then fails with its own message (ls: nope/*/x: No such file or directory) instead of zsh's.SH_WORD_SPLITalso applies to commands written for zsh: an unquoted$varthat contains spaces is split. Quote variables ("$var") to be safe in both shells.- The perl
timeoutsupports-s,-k,--preserve-statusand--foreground; an unknown signal or option exits 125 without running the command. For full GNU behaviour,brew install coreutils(it is then used automatically). - Windows is not covered. Linux usually runs bash, where this plugin does nothing.
claude plugin uninstall zsh-compat@claude-zsh-compat
claude plugin marketplace remove claude-zsh-compatFor the manual version, delete the block between # >>> zsh-compat and
# <<< zsh-compat (and the if/fi around it) from ~/.zshrc.
test/run.sh # unit, hook, snapshot and zsh-slips tests
tools/make-snippet.sh # regenerate snippet/ after editing lib/compat.zsh
claude plugin validate . # manifest check
claude --plugin-dir . -p "run: echo ====" # try it without installingtest/run.sh also sources your newest Claude Code shell snapshot (a read-only copy)
together with the options and checks that ordinary commands (git, grep, find,
pipes, loops, arrays, here-docs) behave exactly as before.
MIT, see LICENSE.