GrepTool: Search content

GrepTool is responsible for searching for text or regex patterns within file contents.
In real-world usage, it's often Claude Code's first step for troubleshooting, understanding code, and locating implementations.

If you break down Claude Code's common actions, you'll find that many rounds of conversation actually follow this pattern:

1. First Grep
2. Then Read
3. Then decide whether to Edit

So GrepTool is essentially a "clue discoverer" in the main loop.

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(),
})

This shows that GrepTool does more than just "search for a word"; it also supports:

• Filename filtering
• File type filtering
• Viewing only matching files
• Viewing content context
• Viewing match counts
• Pagination and truncation
• Multiline mode

In other words, it's a ripgrep search engine wrapped in a structured interface.

The most critical import in the source code is:

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

Anthropic didn't let the model run rg directly in Bash; instead, it wrapped ripgrep as a formal tool.
The benefits of this approach are direct:

• The permissions system recognizes it as "content search"
• Output modes are more controllable
• Context results are easier to trim
• The UI can render them more reasonably

There's a very critical default value in the source code:

const DEFAULT_HEAD_LIMIT = 250

The comment is quite straightforward:
An unlimited grep can easily overwhelm the context.

So GrepTool inherently does two things:

• Limits result volume by default
• Supports offset pagination to continue viewing

This is crucial because Claude Code is essentially playing a game with limited context.
If a search tool doesn't help control the volume, it will quickly bog down the conversation.

The source code breaks down the output modes into:

• content
• files_with_matches
• count

Behind these three modes lie three completely different work goals:

• files_with_matches: I first need to know which files are relevant
• content: I want to view the context around the matches
• count: I want to know the scope of impact or match volume

This is also what makes Claude Code more advanced than "having an AI run rg and manually read the terminal output."
It doesn't just have one tool; it enables a single tool to support different intents internally.

These two tools are often compared side-by-side:

• GlobTool: Search by path/filename
• GrepTool: Search by content

You can think of it this way: Knowing what a file looks like -------------> GlobTool

Knowing what keywords are in the content --------> GrepTool

In real tasks, GrepTool is typically used more frequently.
Because most of the time, you know:

• A certain function name
• A certain API path
• A certain error message
• A certain piece of copy/text

rather than an exact filename.

Like GlobTool, GrepTool explicitly declares itself as:

isConcurrencySafe() {
  return true
}

isReadOnly() {
  return true
}

This means the main thread can more boldly send out multiple search requests in parallel.
This greatly helps Claude Code's exploration efficiency.

For example, if a user says:

After logging in successfully, why does it still redirect back to the login page?

A very typical path for Claude Code would be:

1. Use GrepTool to search for login, redirect, and route protection logic
2. Use FileReadTool to read a few key matching files
3. Use GrepTool again to search for the state source
4. Finally locate the root cause

You'll notice that here, GrepTool isn't an auxiliary tool; it's the starting point of the investigation chain.

Functionally it might suffice, but at the system level, it's different.
GrepTool is more controllable, saves more context, and better supports subsequent reasoning.

That's not right.
It actually supports different output modes, context ranges, pagination, and file filtering.

Not entirely.
It's also frequently used for:

• Confirming which areas a change affected
• Checking if a name has been fully removed from the project
• Verifying whether refactoring was applied everywhere

If you compress Claude Code's search capability into a single sentence:

GrepTool is the most frequently used content-location tool in the main loop, wrapping ripgrep into a formal search capability that supports pagination, trimming, and structured context injection.

Many source code analysis tasks truly begin with GrepTool.