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.

Reason 1: the Bash tool is not bash

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.

Reason 2: the userland is BSD

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

What Claude writes	What macOS does
sed -i 's/a/b/' file	creates file-e, edits the original, exits 0
date -d yesterday +%F	date: illegal time format
stat -c %s file	stat: illegal option -- c
sed -E 's/\s+/_/'	doesn't match — BSD sed has no \s

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.

Why you can't fix this in your shell profile

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.

What actually works

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

The shell: CLAUDE_CODE_SHELL

First, get a bash worth pointing at:

brew install bash

This step is easy to skip, and skipping it quietly undoes the rest. macOS does ship a /bin/bash, but it's 3.2, from 2007 — Apple froze it when bash moved to GPLv3 and has never shipped a newer one. It has no mapfile, no ${x^^}, no associative arrays. Switching the Bash tool to "bash" without installing one just moves you from a modern zsh to an 18-year-old bash, which is worse.

Then, CLAUDE_CODE_SHELL in the env block of settings.json. It's read 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 there means the first bash on PATH — Homebrew's 5.x now that you've installed it, not Apple's 3.2. Set SHELL alongside it, or the model's own environment summary keeps telling it the shell is zsh.

The tools: CLAUDE_ENV_FILE

Same shape — install first:

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

Each of those formulas ships a libexec/gnubin directory containing the GNU builds under their plain names — sed, not gsed. That directory is the thing you put on PATH; nothing is symlinked or copied, so a later brew install or brew uninstall takes effect at the next session with no step in between.

Getting it onto the agent's PATH is where CLAUDE_ENV_FILE comes in. A SessionStart hook may append shell statements to the file that variable 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}"

(One directory per installed formula, in practice.) If you'd rather do both halves in one go:

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

The result

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:

	Without	With
Shell	zsh 5.9	bash 5.3.15
sed --version	sed: illegal option -- -	GNU sed 4.10
date --version	date: illegal option -- -	GNU coreutils 9.11
awk --version	error	GNU Awk 5.4.1
date -d yesterday +%F	error	2026-09-08

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.

Packaged

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

One deliberate omission: 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.

Upstream

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

• anthropics/claude-code#91498 — the Bash tool runs the login shell (not my issue; I found it afterwards)
• anthropics/claude-code#95705 — the userland is BSD and nothing says so

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.