Grep vs Glob vs Read: Searching a Codebase with Claude Code's Built-in Tools

1.Six tools that do most of the work

Claude Code comes with many built-in tools. For work inside a codebase, six of them handle nearly everything. The tools reference gives each a one-line description: Read "Reads the contents of files", Write "Creates or overwrites files", Edit "Makes targeted edits to specific files", Bash "Executes shell commands in your environment", Grep "Searches for patterns in file contents", and Glob "Finds files based on pattern matching".

The how-it-works page sorts these capabilities by job: file operations, search and execution. It describes search as the ability to "find files by pattern, search content with regex, explore codebases". Those are two different verbs, and each one belongs to a different tool.

The reference also lists which tools need permission, and that split gives you a useful mental model. Read, Grep and Glob need no permission. They only look, so they are cheap to call while you are still figuring out what to change. Edit, Write and Bash change files or run arbitrary commands, so they are gated. The same table notes that Glob and Grep are "Absent by default on macOS, Linux, and WSL". Whether you have them depends on how the session is set up. Configuring tools is covered in another lesson. This one is about choosing the right tool when they are available.

Sources12

2.Grep for what's inside files, Glob for what files are called

The choice comes down to one question: is the thing you're matching in the file's path, or in its text?

Glob takes a pattern such as **/*.ts, plus an optional path that defaults to the current working directory. Use it whenever a naming convention carries the answer, for example test files (**/*.test.tsx), every file with a given extension, or files in a certain directory layout. If the project pairs Button.tsx with Button.test.tsx, two Glob calls give you both lists of names, and you can compare them without opening a single file.

Grep takes a pattern that is a regular expression, such as TODO.*fix. It also takes an optional path and an optional glob filter, so you can restrict a content search to, say, *.ts files. Use Grep when the evidence is inside the code: every caller of a function, the place an error message is raised, every file that imports a module.

Two other Grep parameters are worth knowing. output_mode can be content, files_with_matches or count, and the default is files_with_matches. So a plain Grep call returns a list of files, not the matching lines. Ask for content when you need to see the lines themselves, or count when you only need a number. Grep also supports case-insensitive search (-i) and multiline matching.

Sources3

3.Prefer the dedicated tools over shell equivalents

Bash can run find, grep, cat and sed, so technically it could handle every search and edit itself. Claude Code deliberately steers away from that. One changelog entry records that system prompts were improved to guide the model toward "using dedicated tools (Read, Edit, Glob, Grep) instead of bash equivalents (cat, sed, grep, find)", which cut down on unnecessary Bash calls.

The tools reference gives a practical reason as well. Bash needs permission, while Read, Grep and Glob do not. The dedicated tools also have structured inputs that shell one-liners lack. Read takes an optional offset (the line number to start from) and limit (how many lines to read), so you can view part of a large file without piping it through head or sed. Grep has output_mode and a glob filter.

Bash is still the right tool for real execution. The how-it-works page lists that category as "Run shell commands, start servers, run tests, use git". Use Bash for those jobs. Searching and reading belong to the dedicated tools.

Sources432

4.Build understanding incrementally: search, then read

Reading every file in a repository up front fills the context window with code that probably doesn't matter. The documented workflows do it the other way round. The how-it-works page walks through fixing a failing test: run the test suite, read the error output, search for the relevant source files, read those files, edit them, then run the tests again. Search comes before reading, and the search decides which files get read.

The common-workflows guide gives the same advice: "Start with broad questions, then narrow down to specific areas". Its example prompts escalate from finding the files that handle authentication to tracing "the login process from front-end to database". In tool terms, Grep finds an entry point, such as a route handler or a function name. Read opens that file. Its imports name the next files to open, and you Read those in turn. Each read is chosen by what the previous one showed you.

The skills docs bake this order into an example research skill that runs in an Explore subagent:

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Sources56

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.To find files that follow a naming convention (like *.test.tsx), Grep the codebase for the word "test".Why is that wrong?

   A naming convention lives in the file path, so Glob is the direct tool. Grep searches file contents and would match any file that happens to contain the word.

   Covered in Grep for what's inside files, Glob for what files are called

2. 2.Running find or grep through Bash is just as good as calling Glob or Grep, because the results are the same.Why is that wrong?

   Claude Code's guidance prefers the dedicated tools over their shell equivalents. Bash also needs permission, while Grep and Glob do not.

   Covered in Prefer the dedicated tools over shell equivalents