Claude Code grep Skips Gitignored Files: 2 of 7 Found

I made a small test folder with the word needle in seven files. From my own terminal, grep -rl needle . listed all seven. From inside a Claude Code session, the same command in the same directory listed two, then exited 0 with nothing on stderr. Nothing in that output tells the agent, or you, that five files were skipped.

The grep in Claude Code's Bash tool is not your grep. On native macOS and Linux builds it is a shell function that runs the ugrep engine bundled in the claude binary with --ignore-files, so it honors .gitignore. It also skips binary files. The same swap changes find, and it works in the other direction as well: GNU-only flags that fail on a stock Mac succeed in the agent's shell, then fail in the script the agent writes for you.

Where the wrapper comes from

Every Bash tool call sources a snapshot file under ~/.claude/shell-snapshots/. On this Mac mini (Claude Code 2.1.284, macOS 26.4.1, zsh) the snapshot ends with a block titled # Shadow find/grep with embedded bfs/ugrep. The grep half, trimmed:

function grep {
  ...
  ARGV0=ugrep "$_cc_bin" -G --ignore-files --hidden -I \
    --exclude-dir=.git --exclude-dir=.svn --exclude-dir=.hg \
    --exclude-dir=.bzr --exclude-dir=.jj --exclude-dir=.sl "$@"
}

The Claude Code changelog entry for 2.1.117 explains why: "the Glob and Grep tools are replaced by embedded bfs and ugrep available through the Bash tool." The dedicated search tools were removed from native builds (Windows and npm installs stayed the same), and plain grep and find became the search path. In the session, type grep prints grep is a shell function, and grep --version prints ugrep 7.8.4. /usr/bin/grep --version still says BSD grep 2.6.0-FreeBSD.

Each flag changes what a search can return:

Flag	What it does	What goes missing
--ignore-files	Reads .gitignore files found while recursing	Build output, node_modules, logs, .env
-I	Treats files with a NUL byte or invalid UTF-8 as binary and skips them	Text files with one stray NUL
--exclude-dir=.git and 5 more	Skips VCS metadata	Hooks and config inside .git
--hidden	Searches dotfiles	Nothing (this one adds files)

Seven files, two found

The lab was a git init folder with a .gitignore of node_modules/, dist/, *.log and .env. Here is what each grep saw:

Adding --include='*.log' made it worse: zero lines and exit 1 from the wrapper, one line and exit 0 from /usr/bin/grep. A search limited to ignored files returns the exact output of a search that found nothing.

I ran more cases to find the rules:

• Naming the path still works. grep -c needle debug.log returned 1, and grep -rl needle node_modules found the file. The ugrep help text says the ignore globs apply to files "encountered in recursive searches". Only the walk skips files.
• A git repo is not required. In a plain directory with a .gitignore and no .git, ignored files were still skipped.
• .ignore files are not read. Only .gitignore is the default.
• find does not ignore anything. The bfs wrapper listed node_modules and dist. So the agent can find a file and then fail to grep it.
• \grep does not bypass it in zsh. A backslash skips aliases, not functions. Still two files.
• These do bypass it: command grep, /usr/bin/grep, any -z flag (the function hands those to the real grep), bash -c '...', and any script run as a file. grep -r --no-ignore-files gets six of seven; -I still drops the binary.

What it hid in my own repo

This business runs from one repository on this Mac, driven by scheduled Claude Code sessions. I compared the wrapper with command grep -rl --exclude-dir=.git for three strings that matter:

Search	Wrapper	Real grep	Files the wrapper missed
SUPABASE_URL	25	30	.env, 4 tool-state JSON files
Affiliate tag	58	61	.env, the scheduler log, a seed SQL file
STATS_ADMIN_KEY	11	13	.env, the seed SQL file

.env is missing from every row. If an agent is asked "is this key written anywhere besides .env?", the wrapper gives a comforting answer for the wrong reason. An agent checking where a secret has leaked gets a result that skips the most likely places: logs, dumps and build output, which are the files people gitignore. Issue #83326 reports the same thing from another user: secret scans that "report clean while missing .env".

My session transcripts cover the last 30 days, 13,540 Bash commands. 4,856 contain grep, 379 of them recursive, and only 45 call command grep or /usr/bin/grep. Most recursive calls are inside compound commands, so I cannot tell from the logs which ones came back short. That is the problem with this failure: a missed file and a missing file leave the same output.

The reverse trap: it works here, fails in your script

ugrep accepts GNU flags that BSD grep rejects, and bfs accepts -printf. In the agent's shell:

$ grep -oP 'API_KEY=\K\w+' src/app.js
needle
$ find . -name app.js -printf '%s %p\n'
15 ./src/app.js

Put the same grep line in check.sh and run bash check.sh. The script does not load the snapshot, so it gets /usr/bin/grep: grep: invalid option -- P, exit 2. /usr/bin/find answers -printf with unknown primary or operator. If an agent tests a pipeline inline and then saves it as a script, cron job or launchd task, the test proved nothing about the real run. Issue #77592 complains about a model writing grep -oP on Darwin. With the wrapper in place, that kind of mistake passes the agent's own check.

My transcripts had zero grep -P and zero find -printf in those 13,540 commands, so this direction has not hit me yet. The fleet already routes around BSD gaps; see timeout command not found on Mac and date: illegal option -- d. Other users are less lucky.

54 GitHub issues about the wrapper

To see how common this is, I searched the anthropics/claude-code tracker on 2026-09-29 with ten queries (ugrep, bfs, grep shim, grep shadow, shadow functions, embedded grep, shell snapshot grep, ignore-files, grep gitignore, find shadow), up to 100 results each. That gave 224 unique issues, 57 with a wrapper term in the title. I dropped three that were about something else, which left 54, sorted by hand:

Problem	Issues
Runaway memory or CPU (regex blowups, orphaned processes, huge scans)	27
Wrong or missing results, or wrong exit codes	14
Broken shells (bare exec, set -u, bash 3.2, loader paths)	11
Other (permission allowlist bypass, an opt-out request)	2

13 are open. Seven name gitignore or --ignore-files in the title, and five of those are still open, including #88279, which calls absence "unprovable". The request for a switch to turn the wrapper off, #69736, has been open since 20 June. The changelog shows fixes in the other buckets (2.1.121 falls back to installed tools when the binary is deleted, 2.1.235 makes pathological patterns fail fast), but I found no entry that changes the ignore flags.

What I do now

• Use command grep -r when checking that something is absent. A no-match from the wrapper only means "not in files git tracks, and not in binary files".
• Name the directory when the target is known to be ignored (grep -rn X dist/). Explicit paths are always searched.
• Test scripts as files. Run bash script.sh, not the pasted one-liner, before it goes into a scheduler.
• Tell the agent. One line in CLAUDE.md: "In the Bash tool, grep skips gitignored and binary files; use command grep to prove absence." This is cheaper than the silent errors, the same way a pipe hiding an exit code is cheaper to prevent than to debug.

For why the agent uses Bash grep at all, and not a language server, see Claude Code grep vs LSP. That post counts how often the agent reaches for Bash grep. This one is about what those calls can miss.

Sources: the lab and repo comparisons were run on 2026-09-29 on a Mac mini (macOS 26.4.1, build 25E253) inside Claude Code 2.1.284 (native build), with the snapshot function compared against /usr/bin/grep (BSD grep 2.6.0-FreeBSD) and /usr/bin/find. Flag meanings come from the bundled ugrep 7.8.4 --help text. Transcript counts come from parsing Bash tool calls in my own session logs (30-day retention, this session excluded). The issue count is my own search of the public tracker on the same day using the ten queries listed above. Buckets were assigned by title, so treat them as approximate. Version notes are quoted from the public changelog.