DEV Community: Morten Larsen

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

Morten Larsen — Mon, 21 Sep 2026 20:14:48 +0000

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.

What Claude writes	What macOS does
`sed -i -e 's/a/b/' file`	creates `file-e`, edits the original, exits 0
`sed -i 's/a/b/' file`	`sed: 1: "file": command c expects \ followed by text`
`date -d yesterday +%F`	`date: illegal option -- d`
`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. 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. 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}"

The hook writes one such line covering the gnubin directory of every formula that is actually installed. 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`	`awk version 20200816`	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, 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.

Turn your ytt data values schema into a documentation site

Morten Larsen — Mon, 21 Sep 2026 19:59:08 +0000

If you template Kubernetes manifests with ytt, you probably have a data values schema. It starts small: a handful of keys with a #@schema/desc here and a #@schema/validation there. Then it grows. Ours, the deployment.yaml schema for every microservice at Dinero, ended up with a few hundred nested maps. At that size nobody opens the schema file to find out what a key does. They ask a colleague, or copy a value from another service and hope.

The frustrating part is that the answers were all in the schema. ytt's schema annotations carry a title, a description, a default, examples and validation rules for every value. We just had no way to read them that didn't involve scrolling through YAML.

So I built ytt-schema-docs, a small build step that renders a ytt data values schema as a static site. Here is the example site, generated from a deployment-style schema.

What you get

Every map in the schema becomes a table with one row per property: the name and title, the type as a badge, the default and constraints, and the description. Nested maps get their own table, and the property name links to it. Arrays of maps show up as name[].

A few things fall out of the annotations you already write:

#@schema/validation min=1, max=65535 renders as Minimum and Maximum chips. one_of= renders each allowed value as a chip. min_len= and max_len= work the same for strings and arrays.
A property is marked Required when its default fails its own validation. That is exactly the pattern the ytt docs recommend for required values: an empty string with min_len=1, a 0 with min=1, or a "" against a one_of list. A #@schema/nullable property defaults to null, which ytt does not validate, so it is never marked required.
#@schema/examples renders as a labeled example under the type.
HTML in descriptions is allowed, so <strong> and <br/> in a #@schema/desc do what you expect.
Giving a property the title __REMOVE_ME__ hides it and everything nested under it, for internal settings that should not be in the public docs.

Around the tables there is a sidebar listing every map, nested by depth, with a search box that filters on map and property names. The sidebar highlights the map you are reading as you scroll. The site follows your system's light or dark mode and has a toggle, and the tables stack into blocks on a phone.

How it works

The trick is that ytt can export its schema as OpenAPI v3:

ytt --file schema.yaml --data-values-schema-inspect --output openapi-v3

That gives you a standard document with properties, default, minimum, enum and so on, plus the ytt-specific x-example-description. From there it is ordinary web tooling:

A tiny ytt overlay patches the info block with the site title, description and version.
openapi-generator renders the document with a custom template. The template is little more than a page shell that embeds each schema as JSON.
A browser script dereferences the $refs, walks the maps depth first in schema order, and builds the tables and the sidebar with plain DOM APIs. Tailwind provides the styling.

Because it is a build step and not a ytt extension, it works with any ytt version that has the OpenAPI export, and it does not care how your templates are organised. Point it at the schema file and run npm run build.

Using it on your own schema

git clone https://github.com/Baune8D/ytt-schema-docs
cd ytt-schema-docs
npm install
# replace schema.yaml with yours, or change the path in package.json
npm run build

The site lands in dist as a single index.html with a script and a stylesheet next to it. Host it anywhere static files go. We serve ours from a small Node container next to the deploy CLI that owns the schema, and CI regenerates the OpenAPI export before every image build so the docs can never drift from the templates.

You need Node, ytt on your PATH, and a Java runtime for openapi-generator.

What I would like to hear

If you use ytt schemas, I am curious what you would want rendered differently, and whether the required-value rule matches how you write validations. Issues and pull requests are welcome on GitHub.