[DOCS] Native macOS/Linux builds still document `Glob` and `Grep` as separate tools
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/tools-reference
Section/Topic
Built-in tools table and search-tool availability/platform behavior
Current Documentation
The docs currently say:
|Bash| Executes shell commands in your environment. See [Bash tool behavior](#bash-tool-behavior) | |Glob| Finds files based on pattern matching | |Grep| Searches for patterns in file contents |
The SDK docs also still describe Glob and Grep as direct built-in tools:
| Glob | Find files by pattern (**/*.ts,src/**/*.py) | | Grep | Search file contents with regex |
No code.claude.com page currently documents the native macOS/Linux bfs / ugrep search behavior.
What's Wrong or Missing?
Changelog v2.1.117 says native macOS and Linux builds replace the separate Glob and Grep tools with embedded bfs and ugrep exposed through the Bash tool, while Windows and npm-installed builds stay unchanged.
The current docs still present Glob and Grep as normal built-in tools without any platform note, so they describe outdated behavior for native macOS/Linux builds.
This is especially misleading in pages that describe available tools, permissioning, or SDK allowedTools examples, because users on native macOS/Linux builds need to understand that search now routes through Bash instead of separate Glob/Grep tool calls.
Suggested Improvement
Update the tools documentation to add an explicit platform-availability note for search tools:
- Native macOS/Linux builds: file/content search uses embedded
bfsandugrepthrough the Bash tool rather than separateGlob/Greptool calls - Windows and npm-installed builds: existing
Glob/Grepbehavior remains unchanged
Then audit the pages that list built-in tools or show allowedTools examples so they either:
- reflect the platform split directly, or
- link back to a single authoritative availability note in
tools-reference
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | Built-in tools table still lists Glob and Grep as separate tools with no native-build caveat |
| https://code.claude.com/docs/en/how-claude-code-works | Search capabilities are still described generically as pattern/file-content search |
| https://code.claude.com/docs/en/agent-sdk/overview | Built-in tools table and allowedTools: ["Read", "Glob", "Grep"] example assume direct Glob/Grep availability |
| https://code.claude.com/docs/en/agent-sdk/agent-loop | Built-in tools and permission examples still describe Glob/Grep as direct search tools |
| https://code.claude.com/docs/en/agent-sdk/typescript | SDK reference still defines Glob and Grep tool inputs as standard built-in tools |
| https://code.claude.com/docs/en/agent-sdk/python | SDK reference still defines Glob and Grep input/output schemas |
Total scope: 6 pages affected
Source: Changelog v2.1.117
Exact changelog entry: Native builds on macOS and Linux: the Glob and Grep tools are replaced by embedded bfs and ugrep available through the Bash tool — faster searches without a separate tool round-trip (Windows and npm-installed builds unchanged)
Showing cached comments. Read the full discussion on GitHub ↗
7 Comments
Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.
still not addresses. Spent hours on trying to figure out whats wrong only to eventually realise Glob and Greb no longer exist as direct tools.
So many broken tool hooks that are hooks on grep/glob that never get hit and could never figure out why.
So how do people do search hooks now?
Confirming on v2.1.185 (native macOS), with some empirical detail that may help whoever picks this up.
The shim mechanism (for the docs fix): on native builds,
grepandfindare injected as shell functions in the session's shell snapshot that re-exec the Claude binary via argv0 as the embedded engines:grep→ugrep 7.5.0, invoked as:-G --ignore-files --hidden -I --exclude-dir=.git …find→bfs 4.1.1, invoked as:-S dfs -regextype findutils-default …Two things worth folding into the documentation:
grep→ugrep shim respects ignore files (--ignore-files), but thefind→bfs shim does not. So content search skips gitignored paths while file search traverses everything (e.g.node_modules). Worth documenting, since it surprises anyone expectingGlob-like behavior.rg≈ugrep(~0.45s); file-findfd≈bfs(~0.19s for equal work). The engines are genuinely top-tier — the only gap here is docs/guidance, not speed.Strong +1 on the core ask: the manuals need to be updated to reflect this change. Right now the tools-reference page still describes
Grepas a ripgrep-backed tool and listsGlob/Grepas available with no platform caveat, which is simply wrong on native builds. Until the docs, the SDK reference, and the model's own guidance all reflect thebfs/ugrep-via-Bash reality, users (and the model) keep rediscovering this the hard way.Also filed #69849 for the model-facing side: the model's guidance still references the removed
Glob/Greptools and it gets no runtime signal that they moved to Bash, so it keeps reaching for tools that don't exist on native builds.Closing for now — inactive for too long. Please open a new issue if this is still relevant.
This issue was incorrectly closed, despite having reproduction steps and Claude version. This behavior of the bot is tracked in https://github.com/anthropics/claude-code/issues/87647. Consider upvoting that issue for visibilty, maybe the bot behavior gets fixed.
Let's call this what it is: removing Grep and Glob as tools and burying the same functionality inside Bash is not a platform optimization, it's an unannounced API break dressed up as a changelog footnote in a docs issue.
If someone wanted a faster search engine, that's an internals swap — bfs/ugrep under the hood, same Grep/Glob interface on top. That's not a nice-to-have, it's the entire point of having a tool boundary. Instead, the public contract got collapsed into a raw shell string, and every consumer that reasoned about tool identity — permission rules, allowedTools lists, PreToolUse hooks — now has to regex a command string to guess what the model was actually trying to do. That's a regression in every one of those systems, silently, on one platform, with no migration path.
Shipping this as a one-line changelog entry and letting a docs issue be the place this surfaces is not a good look. If the tool surface is going to differ by platform, that's a breaking change and should be flagged as one — not something teams find out about because their hooks quietly stopped firing.