zsh-compat

zsh Compatibility — Shell Pitfalls Reference

Claude Code's Bash tool inherits the user's shell. On macOS (default since Catalina), that shell is zsh. Many common bash patterns silently break in zsh. This reference covers the most dangerous differences.

Enforcement

The enforce-zsh-compat.sh PreToolUse hook (ZSH-001) catches five common issues at runtime:

• Check A: Bare status= variable assignment → denied
• Check B: Unprotected glob in for ... in GLOB; do → auto-fixed with setopt nullglob
• Check C: ! [[ ... ]] history expansion → auto-fixed by rewriting to [[ ! ... ]]
• Check D: \!= escaped not-equal in [[ ]] conditions → auto-fixed by stripping backslash
• Check E: Unprotected globs in command arguments (rm, ls, cp, etc.) → auto-fixed with setopt nullglob

This skill teaches the correct patterns so the hook rarely fires.

Pitfall 1: Read-Only Variables

zsh reserves several variable names as read-only built-ins. Assigning to them is a fatal error.

Variable	zsh meaning	Error message
status	Last exit code ($?)	read-only variable: status
pipestatus	Pipeline exit codes	read-only variable: pipestatus
ERRNO	System errno value	read-only variable: ERRNO
signals	Signal name array	read-only variable: signals

Fix

Rename the variable. Use descriptive compound names:

# BAD — fatal in zsh
status=$(jq -r '.status' "$f")

# GOOD — compound name, clear intent
task_status=$(jq -r '.status' "$f")
wf_status=$(jq -r '.status' "$f")
completion_status=$(curl -s "$url")
tstat=$(grep -c 'done' "$f")

Pitfall 2: Glob NOMATCH

In bash, when a glob matches no files, it's passed through as a literal string. In zsh, the NOMATCH option (on by default) makes this a fatal error. Affects both for loops and command arguments. Three fix options: (N) qualifier (preferred), setopt nullglob, or existence check. Note: 2>/dev/null does NOT help — the error is at parse time.

See glob-nomatch-patterns.md for the full deep dive with 3 fix patterns.

Pitfall 3: Word Splitting

In bash, unquoted variables are split on $IFS (spaces, tabs, newlines). In zsh, unquoted variables are NOT split by default.

files="file1.txt file2.txt file3.txt"

# In bash: loops 3 times (word splitting)
# In zsh: loops 1 time (no word splitting — treats as single string)
for f in $files; do
  echo "$f"
done

Fix

Use arrays instead of space-separated strings:

files=(file1.txt file2.txt file3.txt)
for f in "${files[@]}"; do
  echo "$f"
done

Pitfall 4: Array Indexing

Shell	First element	Array declaration
bash	${arr[0]}	arr=(a b c)
zsh	${arr[1]}	arr=(a b c)

Fix

Avoid index-based access. Use "${arr[@]}" for iteration (works in both).

Pitfall 5: = Filename Expansion

In zsh, =command expands to the full path of the command. This can break commands that use = in unexpected positions.

# Potentially surprising in zsh:
echo =ls
# zsh outputs: /bin/ls

This rarely affects generated code but can cause confusion in path handling.

Pitfall 6: "!" History Expansion Before [[

In zsh, the exclamation mark at the start of a command is interpreted as history expansion (like !! or !$). When used for logical negation before [[ ]], it causes "command not found: !".

# BAD — zsh interprets "!" as history expansion
if ! [[ "$epoch" =~ ^[0-9]+$ ]]; then
  echo "not numeric"
fi
# zsh: (eval):1: command not found: !

# GOOD — negation inside [[ ]] (semantically equivalent for single expressions)
if [[ ! "$epoch" =~ ^[0-9]+$ ]]; then
  echo "not numeric"
fi

Why This Happens

In bash, the exclamation mark before [[ ]] is recognized as the pipeline negation operator. In zsh's eval context (which is how Claude Code's Bash tool executes commands), it can trigger history expansion before the parser reaches [[.

Fix

Move the negation inside [[ ]]. For single-expression conditionals, ! [[ expr ]] and [[ ! expr ]] are semantically equivalent.

Note: ! command (e.g., ! grep -q pattern file) is generally safe because the command name that follows is a real command. The issue is specifically ! [[ where zsh gets confused.

Pitfall 7: Escaped Not-Equal \!= in Conditions

In bash, \!= inside [[ ]] is valid — the backslash is silently ignored. In zsh, [[ ]] rejects it.

# BAD — fatal in zsh
if [[ "$owner" \!= "$session" ]]; then
  echo "mismatch"
fi
# zsh: (eval):1: condition expected: \!=

# GOOD — plain != works in both
if [[ "$owner" != "$session" ]]; then
  echo "mismatch"
fi

Why This Happens

LLMs trained primarily on bash examples sometimes emit \!= as a "safe" form of !=. In bash, the backslash is a no-op before != inside [[ ]]. In zsh, [[ ]] has its own parser that doesn't accept the escaped form.

Pitfall 8: Unprotected Globs in Command Arguments

Same NOMATCH issue as Pitfall 2, but in command arguments (rm, ls, cp, etc.) rather than for loops. Prefer find for cleanup commands or prepend setopt nullglob; for quick one-liners.

See glob-nomatch-patterns.md for examples and recommended approaches.

Pitfall 9: BSD date Lacks %N (Nanoseconds)

GNU date (Linux) supports %N for nanoseconds. macOS ships BSD date, which does not — %N is output as the literal letter N. This silently corrupts any arithmetic that depends on millisecond timestamps.

# BAD — on macOS, date outputs "1740000000N", arithmetic fails
echo $(($(date +%s%3N)))
# zsh: bad math expression: operator expected at 'N'

# GOOD — use $SECONDS (integer precision, zero-dependency)
start=$SECONDS
# ... work ...
elapsed=$(( SECONDS - start ))

# GOOD — gdate from coreutils (millisecond precision)
if command -v gdate &>/dev/null; then
  epoch_ms=$(gdate +%s%3N)
else
  epoch_ms=$(python3 -c 'import time; print(int(time.time() * 1000))')
fi

# GOOD — python3 one-liner (always available on macOS)
epoch_ms=$(python3 -c 'import time; print(int(time.time() * 1000))')

Why This Happens

macOS uses BSD date which only supports POSIX format specifiers. %N is a GNU extension. When BSD date encounters %3N, it interprets %3 (ignored or truncated) and outputs N literally. Wrapping in $((...)) then fails because 1740000000N is not a valid integer.

Fix Priority

Need	Solution	Precision
Elapsed time	$SECONDS	Integer seconds (no dependency)
Epoch milliseconds	gdate +%s%3N with fallback	Millisecond (requires brew install coreutils)
Epoch milliseconds	python3 -c 'import time; print(int(time.time() * 1000))'	Millisecond (always available)

Existing Codebase Patterns

• talisman-resolve.sh uses $SECONDS for coarse-grained stall detection
• rune-status.sh uses gdate with BSD date fallback for duration display

Quick Reference — Safe Patterns

Pattern	Bash-only	zsh-safe
Variable name	status=val	task_status=val
Glob loop	for f in *.md; do	for f in *.md(N); do
Negated [[	if ! [[ expr ]]; then	if [[ ! expr ]]; then
Word split	for w in $var; do	for w in ${(s: :)var}; do or use arrays
Array index	${arr[0]}	${arr[1]} or iterate with [@]
Glob in args	rm path/*	setopt nullglob; rm path/* or use find
Escaped !=	[[ "$a" \!= "$b" ]]	[[ "$a" != "$b" ]]
Millisecond timestamp	date +%s%3N	$SECONDS or gdate +%s%3N or python3

When This Matters Most

• Multi-agent workflows: LLM-generated Bash runs unsupervised on the user's shell
• Monitoring loops: Frequently iterate over tmp/ directories that may be empty
• State file parsing: Reading .rune-*.json files that may not exist yet
• Review/audit output: Checking verdict files that haven't been written yet

See Also

• CLAUDE.md Rule #8 — inline zsh compatibility rule
• enforce-zsh-compat.sh — ZSH-001 PreToolUse enforcement hook
• polling-guard skill — monitoring loop fidelity (orthogonal but often co-occurs)