Terminals & shells

Your shell is the bottom layer

When Claude calls its Bash tool, the actual subprocess is your shell — not "bash" in the abstract. The command string Claude generates is interpreted by that shell's quoting rules, glob expansion, variable substitution, and aliases. Two different shells running the "same" command can produce different results, sometimes spectacularly so.

Three places this matters most:

• Permission patterns. "Bash(curl:*)" matches what Claude prints into the shell. PowerShell users get curl.exe there; bash users get curl. Same allowlist, different match.
• Hooks. A hook command in settings.json is shell-interpreted before it runs. 2>/dev/null doesn't work in PowerShell; $VAR doesn't work in fish; backticks behave differently across them.
• Status line and prompt customisation. The status line config you put in settings.json is fine cross-shell, but if you customise via shell prompt integration, that integration is per-shell.

PowerShell 7

The modern Windows shell. PowerShell 7 (sometimes called pwsh) is a cross-platform Microsoft shell — it runs on Windows, macOS, and Linux. Don't confuse it with the older powershell.exe (5.1) that ships with Windows by default. Claude Code prefers 7 if it's installed.

What's distinctive

• Objects, not text. Pipes pass typed objects between commands, not byte streams. Get-Process | Where-Object {$_.CPU -gt 100}.
• Pipeline chains. && and || work the same as bash (since v7).
• Verb-Noun command names. Get-ChildItem, Set-Location, Remove-Item. Plus aliases — ls, cd, rm — that map to those cmdlets but with different semantics from POSIX counterparts.
• Variables with sigils. $var, $env:NAME for env vars, $null, $true.
• Backtick is the escape, not backslash. Line continuation uses `. Newline in a string is `n.
• Quoting. Single quotes are literal; double quotes interpolate. Inside double quotes, $ needs escaping with backtick.

Cross-platform note

PowerShell 7 on macOS/Linux means you can theoretically use the same shell everywhere. In practice few people do — the rest of the Unix toolchain expects bash/zsh, and PowerShell on Linux is missing a lot of muscle memory.

Hooks in PowerShell

"hooks": {
  "Stop": [{
    "matcher": "",
    "hooks": [{
      "type": "command",
      // Note: powershell -c, with `$null` for swallowing output
      "command": "powershell -c \"[console]::Beep(880,200); curl.exe -s -d 'done' ntfy.sh/walhus 2>`$null\""
    }]
  }]
}

Bash

The default on most Linux distributions, the most widely-targeted shell for hook scripts, and the one Claude Code conceptually means when it generates "bash" commands. Available everywhere: Linux native, macOS via Homebrew (or the old 3.x system bash), Windows via Git Bash or WSL.

What's distinctive

• Plain text pipes. Stream-oriented; tools chain through stdin/stdout.
• POSIX-compatible. Most "bash" scripts also work in dash, ash, ksh. Predictable.
• Set -euo pipefail. The four-letter mantra: exit on error, unset variables, pipe failures. Put it at the top of every script.
• Heredocs. <<EOF ... EOF for multi-line input. Use single-quoted <<'EOF' if you don't want variable expansion.
• Globbing. *, ?, [abc], plus extglob (shopt -s extglob) for richer patterns.

Bash on macOS — version matters

The bash that ships with macOS is 3.2 (held back by Apple's licensing concerns). brew install bash gets you 5.x. Some script patterns (associative arrays, readarray) only work in 5+. If your hooks use modern bash, declare it: #!/usr/bin/env bash picks up the brew-installed one.

Bash on Windows

• Git Bash — comes with Git for Windows. Minimal, MSYS-based, fast.
• WSL bash — the real Linux bash, in WSL2. Heavier, slower to launch, but a real Linux.
• Cygwin bash — older, less popular now.

Claude Code on Windows usually finds Git Bash first. If you've installed WSL and want Claude to use that, set "shell" in settings.json explicitly.

Zsh

The default shell on macOS since Catalina (10.15). Mostly bash-compatible, with some quality-of-life upgrades around globbing, completion, and prompt customisation. The reason every Mac user's .zshrc looks slightly different is the plugin manager (oh-my-zsh, prezto, znap).

Bash vs zsh, for our purposes

• Mostly drop-in. A bash script with #!/usr/bin/env bash runs fine; a script with no shebang and bash-isms may work in zsh, depending on which bash-isms.
• Different word splitting. zsh doesn't auto-split unquoted variables the way bash does. Scripts that rely on for x in $list may break.
• Better globbing. zsh has extended glob qualifiers (*(.) for regular files, *(/) for directories). Don't use them in scripts you want bash-portable.
• Implicit cd. Type a directory name; zsh cd's into it. Cute, but breaks scripts that assume bare names are commands.

The portability rule

If a hook script uses any shell-specific syntax, give it an explicit shebang and run it as a file rather than inline. #!/usr/bin/env bash at the top of ~/.claude/hooks/notify.sh, then reference the file in settings.json.

"command": "$HOME/.claude/hooks/notify.sh"

Fish

Friendly Interactive Shell. Beautiful out-of-the-box autosuggestions, syntax highlighting, and a saner config language than bash. Not POSIX-compatible, which is the whole point and also the problem.

What changes

• No $VAR in unquoted lists. set var "a b"; echo $var prints "a b" as one argument, not two. Different from bash.
• No &&/|| until recently. Fish 3+ supports them; older versions used ; and / ; or.
• Functions, not aliases. Fish prefers persistent function definitions over .bashrc-style aliases.
• Universal variables. Set once with set -Ux, available in every fish on the machine.

Claude Code + fish

Claude Code's Bash tool still calls bash for its hooks (not fish), even if your interactive shell is fish. So most of this is irrelevant from the agent's perspective. It only bites if your shell PATH or env setup differs between fish and bash — keep critical PATH entries in ~/.config/fish/conf.d/ and mirror them in ~/.bash_profile if Claude needs them.

cmd.exe — don't

The classic Windows command processor. Older than PowerShell, slower than PowerShell, missing pipeline chains, weak quoting. Claude Code's Bash tool will use it if neither bash nor PowerShell is available, but you should never let that happen.

• Install PowerShell 7 on every Windows machine. winget install Microsoft.PowerShell.
• Install Git for Windows for Git Bash, or enable WSL.
• Set Windows Terminal default profile to PowerShell 7.

If you must use cmd for a specific reason (legacy script, a batch file invoked by Task Scheduler), wrap the invocation: cmd /c "old-script.bat" from inside PowerShell.

Terminal emulators

The shell is the program running your commands; the terminal emulator is the program drawing the window. They're orthogonal — you can run zsh inside any emulator. But the emulator matters for rendering, performance, and a couple of integration points (clickable URLs, OSC sequences, GPU acceleration, ligatures).

The Claude angle

Claude Code's TUI mostly renders identically across these. Where you might see differences:

• Image rendering in the terminal. Inline images (charts, screenshots) — only some emulators support them (Kitty graphics protocol, iTerm2's image escape). On others Claude falls back to ASCII.
• Hyperlinks. OSC 8 escape codes for clickable URLs — most modern emulators handle them. The classic Windows console (cmd window) doesn't.
• Performance for long output. GPU-accelerated emulators (Alacritty, Wezterm, Ghostty) handle huge log dumps without stuttering. Built-in Terminal.app stutters at ~10k lines.
• Status line rendering. The custom status line config in settings.json uses ANSI colour codes. All listed emulators handle them; some may render true-colour better than 8-colour fallback.

Quoting & escaping

The cross-shell ground truth: single quotes are literal; double quotes interpolate. Beyond that, the details vary.

JSON-in-shell escaping (settings.json hooks)

The hook command in settings.json is a JSON string that's parsed once and then shell-interpreted. That means every quote inside it needs JSON-escaping and shell-escaping. The combo is what trips people up most.

// run: powershell -c "[console]::Beep(880, 200)"
"command": "powershell -c \"[console]::Beep(880, 200)\""

The \" in the JSON becomes a literal " when Claude reads it; PowerShell then sees the outer "..." as one argument.

Permission patterns by shell

The Bash(cmd:*) pattern in settings.json matches against the literal command string Claude generates. That string is shaped by what shell it expects to talk to. Cross-shell allowlists need to list both forms.

The allowlist is OR-matched, so listing every form is harmless. Many WholeTech-style settings.json files just have both — curl and curl.exe, ls and Get-ChildItem, etc.

Hooks per shell

The hook command in settings.json runs through the shell Claude Code launches subprocesses with. Here's how the same hook looks across the four most common combinations.

The "beep when Claude stops" hook, four ways

bash / zsh (Linux, macOS)

"command": "printf '\\a'"

Or for a louder one on macOS:

"command": "afplay /System/Library/Sounds/Glass.aiff"

PowerShell 7 (Windows)

"command": "powershell -c \"[console]::Beep(880,200)\""

fish

"command": "fish -c 'printf \\a'"

(Note: hooks aren't usually run through fish; Claude's bash subprocess fires. Use this only if you've explicitly pointed Claude at fish.)

The portable hook

Put the platform-dependent logic in a script, reference the script from settings.json:

// ~/.claude/hooks/notify.sh — single shebang, branch internally
#!/usr/bin/env bash
case "$(uname)" in
  Darwin)  afplay /System/Library/Sounds/Glass.aiff & ;;
  Linux)   paplay /usr/share/sounds/freedesktop/stereo/complete.oga & ;;
  MINGW*|MSYS*|CYGWIN*) powershell.exe -c "[console]::Beep(880,200)" & ;;
esac
curl -s -d "[$(hostname)] claude finished" "$CLAUDE_NOTIFY_URL" >/dev/null 2>&1

// settings.json — same on every machine
"command": "$HOME/.claude/hooks/notify.sh"

Cross-shell portable scripts

Write hooks once; run them across the fleet. Four rules.

1. Use #!/usr/bin/env bash at the top of every script. Picks up the user's preferred bash (homebrew on Mac, system on Linux) and gives the rest of the file predictable semantics.
2. Branch on OS, not on shell. case "$(uname)" in Darwin) … ;; Linux) … ;; MINGW*) … ;; esac. Don't sniff the shell; the shell is bash by virtue of the shebang.
3. Quote every variable expansion. "$VAR", not $VAR. Stops word-splitting surprises across bash/zsh.
4. Set strict mode. set -euo pipefail at the top. Catches the bug where a hook silently failed and Claude kept marching.

The portable script skeleton

#!/usr/bin/env bash
set -euo pipefail

case "$(uname)" in
  Darwin)
    OS=mac
    ;;
  Linux)
    OS=linux
    ;;
  MINGW*|MSYS*|CYGWIN*)
    OS=windows
    ;;
  *)
    echo "unknown OS: $(uname)" >&2
    exit 1
    ;;
esac

# ... your logic here, branching on $OS ...

Profile files per shell

Each shell sources a different set of files at start-up. Knowing which ones makes the difference between "my PATH is correct" and "Claude can't find rclone."

The "where do I put env vars Claude needs" answer

• bash / zsh: ~/.profile (sourced by both at login).
• zsh-only: ~/.zshenv (sourced even non-interactively).
• fish: ~/.config/fish/conf.d/env.fish.
• PowerShell: $PROFILE.CurrentUserAllHosts.
• System-wide (any shell, any user): /etc/environment on Linux; launchctl setenv on macOS; setx VAR val in Windows env.

What goes wrong

The rest of the hub