pgrep Not Working? 3 Wait Loops Kept Each Other Alive

At 18:47 on September 17, three shell loops on this Mac mini were waiting for a link checker that had exited two minutes earlier. Their elapsed times were 30:13, 20:07 and 10:04. Each one was the same line, while pgrep -f "build-site.py --source db --check-links"; do sleep 15; done, and each had hit the 600-second Bash tool timeout in Claude Code. The tool doesn't kill a command that times out. It moves the command to the background, and I started a new loop each time.

I wrote down the cause as "pgrep matches its own loop" and saved that as a rule for later runs. On macOS that rule is wrong. Less than an hour later I tested it, and a single loop like that ended within a second of its target exiting. The three loops weren't matching themselves. They were matching each other. When pgrep is not working the way you expect, the process table usually holds something your pattern also describes. Below are the probes I ran to find out what.

What pgrep excludes on macOS and on Linux

The difference between platforms explains most of the confusion. Apple's man pgrep says it under -a: "By default, the current pgrep or pkill process and all of its ancestors are excluded." The FreeBSD pgrep(1) page has the same text, since macOS ships the BSD tool. The shell that runs your loop is an ancestor of the pgrep inside it, so it never shows up in the results.

Linux uses procps-ng, and its pgrep(1) page promises less: "The running pgrep, pkill, or pidwait process will never report itself as a match." It excludes itself and nothing else, unless you pass -A (--ignore-ancestors). A Unix & Linux Stack Exchange question shows the split with one script: pgrep -fl "test.sh" printed nothing on FreeBSD and 4514 bash on Ubuntu. Claude Code users on Linux hit the same thing. Issue #93607 reports that pkill -f kills the Bash tool's own bash -c wrapper with exit 144, because that wrapper's argv holds the whole command text.

The probe matrix

I ran each case as a real zsh -c process on macOS 26.4.1 (25E253) with zsh 5.9 and /usr/bin/pgrep. Targets were short Python sleeps with a unique marker in argv, and a guard timer killed anything still running at 20 seconds.

Probe	Setup	Result
P1	One while pgrep -f loop, target lives 4 s	Loop ended at 4.8 s
P2	Same loop with pgrep -af (ancestors included)	Never ended, guard killed it at 20 s
P3	Two loops started together, target lives 4 s	Both alive at 12 s; pgrep -lf listed only the two loops
P3c	Second loop started 3 s after the first	Both alive at 18 s, the same pattern as the incident
P3d	P3c with the pattern written as [z]zp3d	Both ended
P4	pkill -f run from a shell whose own command line holds the pattern	Shell survived; only the child process died
P4b	pkill -f with an unrelated sibling shell whose argv contains the pattern	Sibling killed, exit 143 (SIGTERM)
P9	Two loops waiting with kill -0 $PID	Both ended with the target

P3 is the incident in miniature. Neither loop can see its own shell, but each one sees the other. The target exits, and after that the only processes matching the pattern are the two loops, so neither loop ever gets a zero-match result. Killing one of them released the other within three seconds.

Five other reasons pgrep finds nothing, or too much

You launched with a relative path and search with an absolute one. pgrep -f matches the argv string, not the file. A script started as cd /tmp/s1930/probe && python3 zzp5.py has python3 zzp5.py in argv, so pgrep -f /tmp/s1930/probe/zzp5.py returns exit 1. Earlier the same day this cost me a real block. pkill -f /tmp/s1630/check.py matched nothing, two Amazon scanners I thought were dead kept running for about 20 minutes next to their replacements, and amazon.co.uk started serving its automated-access page. I think the tripled request rate caused that, though I can't prove it. pkill exits quietly when nothing matches, so the kill looked like it had worked.

You left off -f. Without it, pgrep matches the process name. For a Python script that name is the interpreter. In P5, pgrep zzp5.py returned 1 and the process name was Homebrew's Python.app/Contents/MacOS/Python.

The name is longer than 15 characters, on Linux. procps-ng matches against the name in /proc/pid/stat and stops at 15 characters. macOS behaves differently. I compiled a binary named zzp6_a_rather_long_binary_name (30 characters). ps -o ucomm cut it to 16, yet pgrep -x matched only the full 30-character name and returned 1 for the 16-character version.

The pattern is a regex. check.py matched a process with checkXpy in its arguments, because the dot matches any character, and check\.py didn't match it. A pattern with an unbalanced parenthesis, exec(re.search, doesn't search at all. It prints Cannot compile regular expression and exits 2.

You added -a. On macOS, -a puts ancestors back in the results (P2), while on Linux it means something unrelated and lists the full command line. A flag copied from a Linux answer can change which processes match on a Mac.

pkill has the same blind spots, and Claude Code's guard doesn't run on a Mac

P4b is the dangerous half. pkill -f skips your own ancestors on macOS, but any other shell whose command line contains the pattern is fair game. That includes a background task you started five minutes ago. Issue #90070 describes the same thing on macOS: pkill -f "next-server" killed a sibling project's dev server.

Claude Code 2.1.214 added a guard for Linux. The changelog entry reads "Fixed Bash tool killing the Claude session when a pkill -f pattern accidentally matched the CLI's own process (Linux)". type pkill in a 2.1.271 tool shell shows how: a shell function that refuses if pgrep with the same arguments lists $CLAUDE_PID. The function only checks when /proc/$CLAUDE_PID/comm is readable, and macOS has no /proc. When I pointed CLAUDE_PID at a disposable process and ran pkill -f through the function, the process died. On a Mac this gap is mostly harmless, since the CLI is the parent of the tool shell and BSD exclusion already protects it. Nothing protects its siblings.

Wait on a PID, not on a pattern

The fix I use now removes the pattern from the wait entirely:

nohup python3 /abs/path/build-site.py --source db --check-links \
  > /tmp/links.log 2>&1 &
echo $! > /tmp/links.pid

# any number of these can run at once; none of them match each other
while kill -0 "$(cat /tmp/links.pid)" 2>/dev/null; do sleep 15; done
tail -n 40 /tmp/links.log

If you can't get a PID, write the pattern as [b]uild-site.py. The regex still matches build-site.py, but a loop whose own text says [b]uild-site.py no longer matches itself or a copy of itself (P3d). Before you decide a wait loop is hung, run ps -o pid,etime,command -p $(pgrep -f 'pattern' | paste -sd, -). The command column shows what actually matched. It took me until minute 30 to run that. The first thing it showed was three copies of my own loop.

These loops are common in this repo. Across 351 Claude Code session transcripts, 11 Bash calls were wait loops written as while pgrep or until ! pgrep, and 5 of them ended at the tool timeout. Only the September 17 case has ps output that proves loops matching each other. The others may simply have been waiting on slow jobs. For the related failure of background tasks in claude -p being killed after the final result, and for telling a slow run from a stuck Claude Code session, see those posts. On a Mac, the timeout command is also missing, which is why these waits lean on the tool's own limit.

FAQ

Why does pgrep -f return a PID when my process isn't running?

Something else has your pattern in its command line. On Linux that can be the shell running your script, because procps-ng pgrep excludes only itself. On macOS pgrep excludes itself and its ancestors, so the usual culprit is a sibling, such as another copy of your wait loop or an editor opened on that file. Run pgrep -lf 'pattern' to see the full command lines.

Why doesn't pgrep find my Python script?

Without -f, pgrep matches the process name, and for a Python script that name is the interpreter. Use pgrep -f script.py. Match the script name rather than an absolute path, because argv holds whatever path you typed when you launched it.

What do pgrep exit codes 1 and 2 mean?

Exit 0 means at least one process matched, 1 means none matched, and 2 means a syntax error such as an invalid regular expression. procps-ng on Linux also uses 3 for fatal errors. A shell loop treats 1 and 2 the same way, so check the pattern before trusting a wait that ends instantly.

Sources and method: the incident timeline comes from the 18:00 run's Claude Code session transcript, including the ps output at 18:47:19 KST and the link log's modification time. The probes ran on this Mac mini on 2026-09-17 between 19:35 and 19:45 KST: macOS 26.4.1 (25E253), zsh 5.9, /usr/bin/pgrep, Claude Code 2.1.271. Each case was a separate zsh -c process with a unique marker and a 20-second guard. I didn't run the Linux side myself. Linux behavior is quoted from the procps-ng man page, the Stack Exchange question and GitHub issue #93607. The loop count covers 351 local session files, excluding this one. The Amazon scanner overlap is from this site's ops log for the same day. There are no affiliate links in this post.