Skip to content

About

Stop Claude Code's bash-style commands from failing in zsh on macOS (fixes globs, ====, word splitting, timeout)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

claude-zsh-compat

Stop Claude Code's bash-style commands from failing in zsh on macOS.

The problem

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.

The fix

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.

Before / after (real Claude Code 2.1.302 runs, claude -p)

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.

Install

As a Claude Code plugin (recommended)

claude plugin marketplace add JasonGDG/claude-zsh-compat
claude plugin install zsh-compat@claude-zsh-compat

The fix applies from the next session you start.

Manually, without the plugin

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.

Measure your own rate

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-01

It 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.

What it does not fix (known limits)

  • ${!var} (bash indirect expansion) is a syntax error in zsh and no option fixes it. Use ${(P)var} in zsh, or eval.
  • $var:h, $B:path (zsh colon modifiers) and "$pat[...]" (zsh array subscript) are only fixed by KSH_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 ~/.zshrc that 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_NOMATCH means 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_SPLIT also applies to commands written for zsh: an unquoted $var that contains spaces is split. Quote variables ("$var") to be safe in both shells.
  • The perl timeout supports -s, -k, --preserve-status and --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.

Uninstall

claude plugin uninstall zsh-compat@claude-zsh-compat
claude plugin marketplace remove claude-zsh-compat

For the manual version, delete the block between # >>> zsh-compat and # <<< zsh-compat (and the if/fi around it) from ~/.zshrc.

Development

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 installing

test/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.

License

MIT, see LICENSE.

About

Stop Claude Code's bash-style commands from failing in zsh on macOS (fixes globs, ====, word splitting, timeout)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages