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

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

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

It's correct. It's the form you'll find in half the StackOverflow answers, blog posts and Dockerfiles out there. 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:

sed: 1: "config.yml": command c expects \ followed by text
date: illegal option -- d
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.

sed -i is the one worth internalising. BSD sed -i reads the next argument as a backup suffix, always. Write -i -e 's/a/b/' and the suffix is -e: the script is read from the following argument, the file is edited in place, exits 0, and a copy named file-e appears beside it. That is literally where the -e in the filename comes from. Write plain -i 's/a/b/' and the suffix is s/a/b/, so the filename becomes the script and sed fails on its first letter. One form fails loudly, the other succeeds and litters. An agent that checks the exit code sees success on the second 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. The Bash tool will pick them up. So will everything else in your terminal, and that's the problem: a profile can't give only Claude Code the GNU tools.

Your profile reaches the Bash tool one way only: through the terminal that launched claude, which ran the profile and passed its PATH on. An export there changes sed for every script, Makefile and muscle-memory command in that terminal, not just for the agent. Launch Claude Code from the desktop app or an IDE and there's no terminal in the chain at all.

The natural next step is to scope it with if [ -n "$CLAUDECODE" ]. That doesn't work either, and this is the non-obvious bit. Claude Code captures a shell snapshot when a session starts and replays it before every Bash call. It does run your profile to build that snapshot, with CLAUDECODE=1 set, so the guard fires. But the export PATH line in the snapshot is written from Claude Code's own inherited environment, not from the shell it just captured, so whatever that run added is dropped. The captured login shell is asked for its own PATH only on Windows. And in your terminal, the one place the export would stick, CLAUDECODE isn't set, so it never runs.

I verified this rather than assuming it. I put a probe in both ~/.bashrc and ~/.zshrc that logged CLAUDECODE, prepended one directory unconditionally and another only when CLAUDECODE was set. On Claude Code 2.1.282, in a bash session and a zsh session, the capture shell sourced the file with CLAUDECODE=1, and neither directory reached the Bash tool.

So your profile isn't being ignored. It runs. But only the PATH you launched claude with reaches the tool, never what the profile adds during the capture.

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}"

The hook writes one such line covering the gnubin directory of every formula that is actually installed.

That path is the Apple Silicon one. On an Intel Mac, or with an x86_64 Homebrew under Rosetta, the prefix is /usr/local, and a PATH entry pointing at a directory that isn't there fails quietly — sed stays BSD and nothing says so. The hook detects the prefix instead of hardcoding it, by probing the filesystem rather than asking brew: a hook launched from the desktop app or an IDE doesn't necessarily have brew on PATH either.

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:

Your own terminal is untouched. sed still resolves to /usr/bin/sed in your shell, and gsed and gdate still work the way you're used to.

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.