Why Claude Code keeps writing shell commands that fail on your Mac

Disclaimer: AI helped me write this since I am not that good with words :)

Claude wrote this, mid-task, while refactoring something unrelated:

sed -i 's/old/new/' config.yml

It's correct. It's the form you'll find in almost every StackOverflow answer, every blog post, every Dockerfile. It exited 0. And it left a file called config.yml-e sitting in my repo, because on macOS that command means something else entirely.

That's the good case, the one that leaves evidence. The louder failures look like this:

date: illegal time format
stat: illegal option -- c
sed: illegal option -- -
(eval):1: no matches found: nope*.txt

If you've used Claude Code on a Mac for more than a week, you've seen some of these. Claude writes a command, it fails, Claude apologises and writes a different one, and you lose thirty seconds and a bit of trust. It happens often enough to feel like the model being sloppy.

It isn't. There are two concrete, fixable reasons, and neither one is visible from inside a session.

Claude Code's Bash tool runs your login shell. On every Mac since Catalina, that's zsh.

So the tool named Bash, whose description begins "Executes a bash command," is handing your commands to zsh. Everything the model knows about bash — mapfile, ${x^^}, word splitting, how an unmatched glob behaves — is subtly wrong. That last one is a good example of how quiet this gets:

rm -f nope*.txt && echo "FOLLOW-UP RAN"

In bash, rm -f shrugs at the missing file and the follow-up runs. In zsh, nomatch is on by default, so the unmatched glob is a shell error, rm never runs, and the chain returns non-zero. Same line, opposite outcome, and the error you get back is prefixed (eval):1: — which tells you it went through eval, but never mentions zsh.

macOS ships BSD versions of the standard tools. Claude — like nearly every shell example ever written — assumes GNU.

sed -i is the one worth internalising. It doesn't fail. BSD sed -i reads the next argument as a backup suffix, so -i 's/a/b/' means "back up with suffix s/a/b/"... except it doesn't even do that here; it takes the empty string that follows -i, edits in place, and drops an -e file beside it. An agent that checks the exit code sees success and moves on.

This is the part that cost me an afternoon, and it's the reason a five-minute fix turns into a project.

The obvious move is to brew install coreutils gnu-sed and put the GNU binaries first on PATH in ~/.zprofile or ~/.bashrc. It has no effect whatsoever on the Bash tool.

Claude Code captures a shell snapshot when a session starts and replays it before every Bash call. The export PATH line in that snapshot is written from Claude Code's own process environment — not from the shell it captured in. The captured login shell is asked for its own PATH only on Windows.

I verified this rather than assuming it. I put a guard in my profile that appended a directory and logged when it ran. In the capture shell the guard fired — CLAUDECODE=1 was set, the profile executed, the directory was added. The resulting snapshot still came out without it.

So your profile isn't being ignored. It runs. Its PATH just never reaches the tool.

Two pieces of documented-but-obscure surface, one for each problem.

CLAUDE_CODE_SHELL This is read from the env block of settings.json before the shell is chosen, which is exactly why it works where a profile can't:

{
  "env": {
    "CLAUDE_CODE_SHELL": "bash",
    "SHELL": "bash"
  }
}

A bare bash means the first bash on PATH — Homebrew's 5.x, not Apple's 3.2. Set SHELL alongside it, or the model's own environment summary keeps telling it the shell is zsh.

CLAUDE_ENV_FILE A SessionStart hook may append shell statements to the file that CLAUDE_ENV_FILE names, and Claude Code sources that file after the snapshot, before every Bash call. So a PATH prepend written there wins:

export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:${PATH}"

Homebrew ships coreutils, findutils, gawk, gnu-sed, gnu-tar, gnu-which and grep with a libexec/gnubin directory containing the GNU builds under their plain names — sed, not gsed. Putting those directories on the agent's PATH gives it a GNU userland without symlinking anything or touching your own terminal.

brew install bash coreutils findutils gawk gnu-sed gnu-tar gnu-which grep

Measured on Claude Code 2.1.266, macOS 26.6, in a session started with no inherited PATH, from a directory with and without the config:

Your own terminal is untouched. sed still resolves to /usr/bin/sed in your shell, gsed and gdate still work the way you're used to, and nothing is copied or linked — a brew install or brew uninstall takes effect at the next session with no step in between.

I put both halves in a repo, because I was tired of pasting them into every project:

https://github.com/Baune8D/claude-code-macos (MIT)

As a plugin, once, for every repo you open:

/plugin marketplace add Baune8D/claude-code-macos
/plugin install claude-code-macos@claude-code-macos

then add that env block to ~/.claude/settings.json by hand. A plugin manifest has no env block, and CLAUDE_CODE_SHELL is read before the shell is chosen so no hook can write it either — which means a plugin install alone gets you the GNU tools while leaving you on zsh. There's a hook that tells you when that's the state you're in, rather than letting the session run half-fixed.

Or copy .claude/settings.json and .claude/hooks/ into a repo, which is the whole fix in one step and travels to everyone who clones it.

It's silent when it succeeds. It speaks once, at session start, when it can't deliver: Homebrew missing, a formula not installed, the Bash tool not running bash, or the bash that won still being Apple's 3.2. The agent gets the fact ("This session's sed is the macOS build, not GNU."), you get the fix (brew install gnu-sed).

grep and find Claude Code ships its own. Both are installed into the session as shell functions that re-exec the claude binary as ugrep and bfs — and a function beats a PATH lookup, so those two names stay Claude Code's however you arrange PATH.

An earlier version of my hook removed those functions. I took it back out after measuring: across a couple dozen common idioms (-rn, --include, -oP, \b, -A, -printf, -regex, -exec {} +) the engines never disagreed on syntax. Every difference was in ugrep's defaults — a bare grep -r honours .gitignore, skips binaries, and omits the ./ prefix. For an agent searching a repository, not walking node_modules is simply the better default.

The GNU grep and findutils formulas are still worth installing, because scripts, an explicit command grep, and the wrapper's own fall-through for -z/--null all resolve through PATH.

This should ideally not need a workaround, so both halves are filed:

Until one of those lands, this is what I run. If you've been quietly assuming Claude is just bad at shell on your machine — it's the environment, and it takes about two minutes to fix.