claude-forkbomb-doctor

A one-file diagnose-and-fix for a nasty macOS Claude Code CLI fork-bomb: pressing Esc during a running Bash tool can make claude spawn hundreds of unreaped child processes per second until your Mac runs out of PIDs and needs a hard reboot.

Root cause is a PATH collision. Homebrew's proctools (pgrep/pkill) and coreutils (stdbuf) shadow Apple's BSD versions in /usr/bin. Claude Code calls those helpers expecting Apple/BSD semantics; against the Homebrew versions, its process management melts down.

The fix forces Apple's /usr/bin/{stdbuf,pgrep,pkill} ahead of Homebrew for your shell only — no uninstalling Homebrew, no touching the rest of your PATH.

---

Quick start

git clone https://github.com/vybzai/claude-forkbomb-doctor.git
cd claude-forkbomb-doctor

./claude-forkbomb-doctor.sh            # --check (default): are you exposed? (read-only)
./claude-forkbomb-doctor.sh --fix      # apply the mitigation (backs up your rc files first)
./claude-forkbomb-doctor.sh --revert   # undo everything

Read the script before running it — it's ~140 lines of plain sh, no dependencies.

---

Symptoms

You hit Esc during a Bash tool in claude --dangerously-skip-permissions and then:

• posix_spawn: Resource temporarily unavailable (errno 35) / fork: Resource temporarily unavailable
• thousands of <defunct> (zombie) processes, all parented to the claude process
• new terminals won't open; load climbs; the claude RSS balloons
• only killing claude or a reboot recovers

Are you exposed?

Run --check, or manually:

command -v stdbuf pgrep pkill

If any resolve into /opt/homebrew (or /usr/local), you're exposed. You most likely have the culprits if you've installed Homebrew proctools and/or coreutils.

What --fix does

1. Creates ~/bin/claude-system-tools/ with symlinks stdbuf/pgrep/pkill → /usr/bin/...
2. Prepends that dir to PATH (with an idempotent guard) in whichever of ~/.zshrc, ~/.bashrc, ~/.profile exist — backing up each file first (*.forkbomb-bak-<timestamp>).
3. Done. Homebrew and the rest of your developer PATH are untouched; only these three helpers are forced to Apple's versions.

It's idempotent (safe to re-run) and fully reversible with --revert.

Honesty / caveats

• Reproduced on Claude Code 2.1.114 on Apple-silicon macOS. It may already be patched in newer Claude builds — treat this as a mitigation for a known PATH trigger, not a claim that Claude is broken today. (Re-triggering the bomb to re-test is destructive, so we don't.)
• It reproduced in a heavily customized developer environment, not a fresh macOS user account — consistent with a Homebrew/PATH interaction. The doctor only acts if you're actually exposed.
• This is a community workaround. The real fix is upstream — the bug has been reported to Anthropic. See FORENSICS.md.

How it was found

FORENSICS.md has the full investigation: live process-monitor captures (10,264 zombies under a single claude parent, ~340 spawns/sec), the full ruled-out table, and the bisection that isolated it to PATH.

Also available

• Claude Code skill — drop skill/claude-forkbomb-doctor/ into ~/.claude/skills/ to harden a Mac via Claude itself. See PROMPT.md too.

License

MIT.