Claude Code Search (2026): The Complete Guide for Engineers Who Actually Use It
If you’ve ever dropped into a 500k-line monorepo and asked Claude Code to “find where the auth token gets refreshed,” you already know the answer matters a lot. Claude Code’s search capabilities are deeper than most engineers realize — and the gap between knowing the basics and knowing the full toolkit is the difference between ten seconds and ten minutes of context-gathering.
This guide covers every search mechanism available in Claude Code as of 2026: built-in glob and grep tooling, file tree exploration, semantic search via the MCP filesystem server, and the patterns that actually hold up in large codebases.
TL;DR
Large codebases make search hard because the relevant code is scattered, poorly named, or buried under framework boilerplate. Claude Code solves this with a layered search stack: glob for file discovery, grep for text pattern matching, and MCP filesystem integration for semantic file access — all invocable in natural language without leaving your terminal. After reading this guide you’ll know which tool fits which situation, how to combine them, and where each one hits its limits.
Quick answer: Claude Code search works through three built-in tool calls — Glob, Grep, and Read — plus an optional MCP filesystem layer that unlocks semantic and directory-tree queries. You invoke them via natural language; Claude picks the right one automatically or you can specify explicitly.
Why Claude Code Search Is Different From grep
The Problem Every Engineer Hits
You open an unfamiliar service, type grep -r "refreshToken" . and get 140 results across 40 files. Half are test fixtures, a quarter are log strings, and you still don’t know where the actual refresh logic lives. This is the classic grep problem: pattern matching tells you where a string appears, not what the code is doing.
Claude Code’s search is different in a meaningful way. When you ask “where does the auth token get refreshed?” Claude Code doesn’t just scan for refreshToken as a string. It uses grep and glob instrumentally — as tools to gather evidence — then reasons over the results to give you a directed answer. The Hacker News thread that called Claude Code search “insanely good for large codebases” was reacting to exactly this: the combination of fast file scanning with LLM-level synthesis of what it found.
What’s Actually Happening Under the Hood
Claude Code exposes three low-level search primitives to the model:
- Glob — resolves file path patterns (
**/*.ts,src/**/*controller*) - Grep — searches file contents for a regex or fixed string, returns matching lines with context
- Read — reads a file (or a range of lines) into context
On top of these, the MCP filesystem server adds higher-level operations: directory tree listing, recursive file listing, and structured file metadata — useful when you want Claude to build a mental model of a project’s structure before diving into specific files.
The model orchestrates these tools in sequence. A typical codebase search looks like: Glob to narrow candidate files → Grep to find relevant lines → Read to load the sections that matter. You never have to manage this pipeline manually.
Built-in Search Tools: Glob, Grep, and Read
Glob: Finding Files by Path Pattern
Glob is Claude Code’s file discovery tool. It resolves standard glob patterns against the working directory and returns matching paths.
# Example prompts that trigger Glob internally
"Find all TypeScript files in the src/api directory"
"Show me every file that has 'controller' in its name"
"List all .env files in the project"
What Claude Code runs internally:
Glob: src/api/**/*.ts
Glob: **/*controller*
Glob: **/.env*
You can also be explicit about what you want:
# Explicit glob request
"Use glob to find all files matching src/**/*.test.ts"
When to use Glob: Any time you’re looking for files by location or name — you know roughly where something lives but not the exact path. It’s fast (no file reading) and works well for “show me the structure of X module.”
H4: Glob Gotchas
Glob matches paths, not content. If a file contains the word “controller” but isn’t named *controller*, Glob won’t find it. For content-based search, you need Grep.
Also note that .gitignore patterns are respected by default. If a directory is gitignored, glob won’t traverse it unless you explicitly override — which you usually shouldn’t, since node_modules or vendor folders will drown results.
Grep: Searching File Contents
Grep is Claude Code’s text search tool. It accepts a pattern (string or regex) and optionally a file glob to constrain the search space.
# Prompts that trigger Grep
"Find all usages of refreshToken across the codebase"
"Where is the DATABASE_URL environment variable read?"
"Search for any TODO comments in the handlers directory"
The underlying tool call looks like:
Grep: pattern="refreshToken", include="**/*.ts"
Grep: pattern="DATABASE_URL", include="**/*.py"
Grep: pattern="TODO", include="src/handlers/**"
Results include file path, line number, and configurable lines of context around each match. Claude Code uses this context — not just the matching line — to reason about what it found.
When to use Grep: Any time you know what text you’re looking for but not which file it’s in. Works for variable names, function calls, error messages, config keys, comment strings.
H4: Making Grep Searches Precise
The single biggest win with Grep is combining it with a path filter. Without it, a search for "id" in a JavaScript project returns thousands of false positives. Three patterns that work well:
# Restrict to a directory
"Find usages of createUser but only in src/services"
# Restrict by file type
"Grep for 'expires_at' in Python files only"
# Combine a specific pattern with context
"Find where we call stripe.charge, show me 5 lines around each match"
The “5 lines of context” instruction is particularly useful — it’s the equivalent of grep -C 5 and gives Claude enough surrounding code to reason about what the call site is doing.
Read: Loading File Sections
Read is the most direct tool: it loads file content into Claude Code’s context. For search workflows, Read typically follows Glob or Grep — once you’ve identified the right file, you read the relevant section.
# Read a full file
"Read src/auth/token.service.ts"
# Read a specific line range
"Show me lines 45-120 of the user repository"
# Read multiple files
"Load both the UserService and AuthService files"
When to use Read explicitly: When you already know the file and want to examine a specific section without asking Claude to search first. Also useful when you want to compare two specific files side by side.
H4: Line-Range Reads for Large Files
For files over ~500 lines, asking Claude to read the whole thing wastes context. Be specific:
# Instead of:
"Read the entire payment processor module"
# Do this:
"Read payment_processor.py lines 1-50 to see the class structure,
then show me the charge() method specifically"
This two-step pattern — scan the structure first, then read the target section — mirrors how an experienced engineer reads unfamiliar code.
MCP Filesystem Integration: Semantic Search at Scale
The Model Context Protocol (MCP) is Anthropic’s open standard for giving language models structured access to external data sources. The MCP filesystem server extends Claude Code with additional file-system operations that go beyond what the built-in tools provide.
What MCP Filesystem Adds
The filesystem MCP server exposes these operations on top of the built-in Glob/Grep/Read stack:
| Operation | What it does |
|---|---|
list_directory |
Returns structured metadata for all entries in a directory |
directory_tree |
Returns the full recursive tree of a directory as JSON |
search_files |
Recursive case-insensitive filename search |
get_file_info |
File metadata: size, creation time, modification time, type |
list_allowed_directories |
Shows which directories Claude Code can access |
The directory_tree operation is especially useful at the start of a session. Instead of asking Claude to infer the project structure by crawling, you hand it the full tree upfront — which means subsequent Grep and Read calls have better context for interpreting what they find.
Setting Up MCP Filesystem
Add the filesystem server to your Claude Code MCP configuration. The config lives at ~/.claude.json (global) or .claude.json in your project root (project-scoped):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/your/project"
]
}
}
}
Restart Claude Code after editing the config. You can verify the server is connected by asking: “What MCP tools do you have available?” Claude should list read_file, list_directory, directory_tree, and search_files among others.
See the official Claude Code MCP setup documentation for full configuration options and troubleshooting.
H4: Scoping MCP Access
The filesystem server’s path argument controls what Claude Code can access. Pass the root of the repo you’re working in, not / — you don’t want Claude reading your ~/.ssh directory. For monorepos where you want to restrict access to a single service, pass the service directory path.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/you/projects/my-service"
]
}
}
}
Using directory_tree for Codebase Orientation
When you join a new codebase or service, this is the fastest orientation pattern:
# Step 1: get the tree
"Use directory_tree on the src directory and give me a one-paragraph summary
of the module structure"
# Step 2: drill into the module that matters
"Now grep for all usages of UserRepository across the services layer"
# Step 3: read the key file
"Load the UserRepository implementation"
This three-step sequence — orient, locate, read — consistently outperforms starting with a broad grep across an unfamiliar codebase.
Codebase Search Patterns That Actually Work
Pattern 1: Tracing a Data Flow End to End
One of the highest-value search tasks is tracing how a piece of data flows through the system — from API endpoint to database and back.
"I want to understand how a user's email gets updated.
Start from the API route definition, follow it through the service layer,
and find where it hits the database. Show me each step."
Claude Code will Glob for route files, Grep for the update endpoint, Read the handler, Grep for the service call, and so on — constructing the full chain. This typically involves 4-6 tool calls that would take a human engineer 15-20 minutes to replicate manually.
Pattern 2: Finding All Callsites of a Deprecated Function
Before removing a function or changing its signature, you need to know everywhere it’s called:
"Find every place in the codebase that calls sendEmail().
Include tests. I want file paths and line numbers."
Follow up with:
"Of those callsites, which ones pass a template parameter?
Which ones are fire-and-forget vs. awaiting the result?"
This second question is where Claude Code’s synthesis layer earns its keep — grep alone would just give you matching lines, not an analysis of the calling patterns.
Pattern 3: Security-Oriented Search
Searching for potential security issues by pattern:
# Find raw SQL strings (SQL injection risk)
"Grep for any string containing 'SELECT' or 'INSERT' in Python files
that aren't in the tests/ directory. Flag any that use string formatting
instead of parameterized queries."
# Find hardcoded credentials
"Search for any string that looks like an API key or secret —
patterns like 'sk-', 'Bearer ', or 'token' assigned to a variable."
# Find unvalidated inputs
"Find all FastAPI route handlers that accept request body parameters
but don't use a Pydantic model for validation."
These patterns work because Claude Code can evaluate what it finds — it’s not just returning grep results, it’s reasoning about whether the code is safe.
Pattern 4: Cross-Service Search in Monorepos
For monorepos with multiple services, scope your searches explicitly:
# Scope by service
"In the auth-service only, find where JWT tokens are validated"
# Cross-service for shared interfaces
"Find every service that imports from @company/shared-types and uses the UserEvent type"
# Find configuration inconsistencies
"Grep for DATABASE_POOL_SIZE across all service configs and compare the values"
Common Mistakes to Avoid
-
Searching without scoping —
grep "id"across a full JavaScript repo will return thousands of useless matches. Always add a directory or file type filter when the pattern is common. -
Asking for the full file when you need one function — Loading a 2,000-line service file when you need one 30-line method wastes context window. Ask Claude to find and read just the function.
-
Not using directory_tree for orientation — Jumping straight to grep on an unfamiliar codebase means you’re searching blind. One
directory_treecall at the start of a session dramatically improves the precision of everything that follows. -
Treating grep results as ground truth — If grep returns 0 results, it doesn’t mean the code doesn’t exist — it may be in a gitignored directory, behind a dynamic import, or named differently than expected. Ask Claude to suggest alternative search terms.
-
Skipping the “what did you find?” synthesis step — After a complex search, ask Claude to summarize what it found before diving into any individual file. This catches cases where the search results don’t actually answer your question.
Quick Reference
Search Tool Selection
| Goal | Tool | Example prompt |
|---|---|---|
| Find files by name/path | Glob | “Find all *.controller.ts files” |
| Find files containing text | Grep | “Where is createOrder called?” |
| Read a specific file | Read | “Load src/services/auth.ts” |
| Understand project structure | MCP directory_tree | “Show me the tree of src/” |
| Find file by name recursively | MCP search_files | “Find any file named config.yaml” |
| Get file metadata | MCP get_file_info | “When was auth.ts last modified?” |
Prompt Patterns That Work
# Scoped grep
"Grep for [pattern] in [directory] files only"
# Context-aware grep
"Find [pattern], show 5 lines of context around each match"
# Traced flow
"Start from [entry point] and trace [data/call] through to [destination]"
# Callsite analysis
"Find all callsites of [function], then tell me which ones [condition]"
# Structure first
"Show me the directory tree of [module], then grep for [pattern] within it"
MCP Config Location
| Scope | File path |
|---|---|
| Global (all projects) | ~/.claude.json |
| Project-scoped | .claude.json in project root |
FAQ
Q: How do I search a codebase in Claude Code?
Type a natural language search request directly in the Claude Code terminal — for example, “find all files that import from the auth module” or “search for usages of the deprecated sendEmail function.” Claude Code automatically uses its built-in Glob, Grep, and Read tools to locate relevant files and code. For more powerful codebase navigation, install the MCP filesystem server, which adds directory tree and semantic file search capabilities.
Q: Does Claude Code support grep for regular expressions?
Yes. The built-in Grep tool accepts both fixed strings and regular expressions. You don’t need to write the regex yourself — describe the pattern in natural language (“find any line that assigns a string starting with ‘sk-‘ to a variable”) and Claude Code will construct and run the appropriate regex. For complex patterns, you can also specify the regex explicitly: “grep for the pattern \bUSER_ID\s*=\s*\d+ in Python files.”
Q: What is the MCP filesystem server and do I need it?
The MCP filesystem server is an optional extension that gives Claude Code additional file-system operations: recursive directory trees, file metadata, and structured filename search. It’s built on Anthropic’s Model Context Protocol, an open standard for connecting LLMs to external data sources. For most single-service codebases, the built-in Glob/Grep/Read tools are sufficient. The MCP filesystem server becomes valuable for monorepos, when you need to build a structural overview of a large codebase quickly, or when you need file metadata (size, modification times) as part of your workflow.
Q: How do I find files by name in Claude Code?
Ask Claude Code to “find files named X” or “show me all files matching Y pattern.” Internally this uses the Glob tool with a pattern like **/*filename* or the MCP filesystem’s search_files operation if MCP is configured. Be as specific as you can — “find all files named auth.service.ts” is faster than “find auth files” because it generates a precise glob pattern that returns no false positives.
Q: Why does Claude Code sometimes miss search results?
The most common cause is gitignored directories. By default, Claude Code’s Glob and Grep tools respect .gitignore, so node_modules, vendor, dist, and similar directories are excluded. If you’re looking for something that might be in a build artifact or a vendored dependency, mention that explicitly. A second common cause is searching with a pattern that’s too specific — if you’re grepping for getUserById but the function is named getUser internally, you’ll get zero results. Ask Claude Code to try alternative patterns if an initial search comes up empty.
Q: Can I use Claude Code search across multiple repositories?
Claude Code operates on the working directory where it’s launched. For multi-repo searches, the most practical approach is to run Claude Code from a parent directory that contains all the repos as subdirectories, and configure the MCP filesystem server with that parent path as the allowed directory. Alternatively, use a monorepo setup where all services live under a single root. Cross-repo searches that span separate git repositories are not natively supported — each repo needs its own Claude Code session.
Going Further
The search capabilities described here are documented in the Claude Code official documentation and in Anthropic’s Model Context Protocol specification. The MCP filesystem server source is on GitHub and is actively maintained.
For engineers building on top of Claude Code programmatically, the Claude Code SDK exposes the same tool-calling interface that powers the search features described here — useful if you want to integrate codebase search into CI pipelines or custom developer tooling.
The fastest way to improve your Claude Code search workflow is to start every unfamiliar codebase session with a structure overview (directory_tree or “describe the module layout”) before asking any specific questions. This 30-second upfront investment consistently cuts the number of follow-up searches needed by half.
