Tools 工具组

GrepTool：搜索内容

它是 Claude Code 最常用的“找线索”工具之一

GrepTool 负责在文件内容里搜索文本或正则模式。
在真实使用里，它常常是 Claude Code 排查问题、理解代码和定位实现的第一步。

如果你把 Claude Code 的常见动作拆开看，会发现很多轮对话其实都是：

先 Grep
再 Read
再判断要不要 Edit

所以 GrepTool 本质上是主循环里的“线索发现器”。

看它的 schema，就知道它不是简单字符串搜索

tools/GrepTool/GrepTool.ts：

const inputSchema = z.strictObject({
  pattern: z.string(),
  path: z.string().optional(),
  glob: z.string().optional(),
  output_mode: z.enum(['content', 'files_with_matches', 'count']).optional(),
  '-B': z.number().optional(),
  '-A': z.number().optional(),
  '-C': z.number().optional(),
  '-n': z.boolean().optional(),
  '-i': z.boolean().optional(),
  type: z.string().optional(),
  head_limit: z.number().optional(),
  offset: z.number().optional(),
  multiline: z.boolean().optional(),
})

这说明 GrepTool 不只是“搜某个词”，它还支持：

搜文件名过滤
搜文件类型过滤
只看命中文件
看内容上下文
看匹配计数
分页和截断
多行模式

也就是说，它是一个被结构化封装过的 ripgrep 搜索器。

它的底层就是 ripgrep，但不是裸暴露

源码里最关键的导入是：

import { ripGrep } from '../../utils/ripgrep.js'

Anthropic 没有让模型直接去 Bash 里跑 rg，而是把 ripgrep 包装成了正式工具。
这样做的好处很直接：

权限系统能识别它是“内容搜索”
输出模式更可控
上下文结果更容易裁剪
UI 能做更合理展示

一张图看它的常见链路

加载图表中...

它在设计上很重视“结果控量”

源码里有一个非常关键的默认值：

const DEFAULT_HEAD_LIMIT = 250

注释写得很直白：
无上限的 grep 很容易把上下文塞爆。

所以 GrepTool 天生就做了两件事：

默认限制结果规模
支持 offset 分页继续看

这很重要，因为 Claude Code 本质上是在和有限上下文做博弈。
搜索工具如果不帮它控量，很快就会把对话拖垮。

它不只是“返回命中内容”，还区分三种模式

源码里把输出模式拆成：

content
files_with_matches
count

这三种模式背后对应的是三种完全不同的工作目标：

files_with_matches：我先知道哪些文件相关
content：我要看匹配周边上下文
count：我想知道影响范围或匹配规模

这也是 Claude Code 比“让 AI 跑 rg 然后自己读终端输出”更高级的地方。
因为它不是只有一个工具，而是让工具内部支持不同意图。

它和 `GlobTool` 的边界

这两个工具经常放在一起比较：

GlobTool：按路径/文件名找
GrepTool：按内容找

你可以这么理解：

加载图表中...

在真实任务里，GrepTool 的使用频率通常会更高。
因为大多数时候你知道的是：

某个函数名
某个 API 路径
某个报错信息
某个文案

而不是准确文件名。

它也是只读且可并行的

和 GlobTool 一样，GrepTool 也明确声明自己是：

isConcurrencySafe() {
  return true
}

isReadOnly() {
  return true
}

这意味着主线程可以更大胆地把多个搜索请求并行发出去。
这对 Claude Code 的探索效率很有帮助。

一次真实使用路径

比如用户说：

登录成功后，为什么还会跳回登录页？

Claude Code 很典型的路径会是：

GrepTool 搜 login、redirect、路由保护逻辑
FileReadTool 读取命中的几个关键文件
再用 GrepTool 搜状态来源
最后定位 root cause

你会发现，GrepTool 在这里不是辅助工具，而是调查主链的起点。

最容易误解它的地方

误解一：直接 Bash 跑 `rg` 就够了

功能上也许能凑合，但系统层面不一样。
GrepTool 更可控、更节省上下文、更利于后续推理。

误解二：Grep 只是“搜字符串”

不对。
它实际上支持不同输出模式、上下文范围、分页和文件过滤。

误解三：Grep 只是前期探索工具

也不完全。
它还经常被用于：

确认某次改动影响了哪些地方
看一个名字是否还残留在项目里
确认重构是否改全

小结

如果把 Claude Code 的搜索能力压缩成一句话：

GrepTool 是主循环里最常用的内容定位工具，它把 ripgrep 封装成了可分页、可裁剪、可结构化回注的正式搜索能力。

很多源码分析任务，真正开始于 GrepTool。