Codebase Navigation: How Claude Finds What It Needs
Claude Code doesn't fumble through your codebase — it uses specialized tools for different kinds of discovery. Learn how Glob, Grep, and Read work together, why Claude avoids Bash for file operations, and the orientation strategy Claude uses when dropped into a large unfamiliar repo.
Quick Reference
- →Glob finds files by name pattern — fast and permission-aware
- →Grep searches file contents by regex — far more efficient than Bash grep
- →Read is the only way to get full file contents — never uses Bash cat
- →Claude uses offset/limit with Read to read large files in targeted sections
- →Codebase orientation typically starts: Glob for structure → Read key config files → Grep for entry points
- →Dedicated tools (Glob, Grep, Read) have better permission handling than Bash equivalents
- →Bash is reserved for operations that require shell: running tests, git commands, build tools
- →For large repos, Claude builds a mental map before diving into individual files
In this article
Why Claude Avoids Bash for File Operations
You might expect Claude Code to use Bash for everything — it is a shell, after all. But Claude Code has dedicated tools for file operations (Glob, Grep, Read, Edit, Write), and it strongly prefers these over Bash for a specific reason: permission handling.
When Claude uses the Bash tool to run `grep -r 'pattern' .`, it triggers the same permission check as any shell command — which could require user approval depending on your permission mode. When Claude uses the Grep tool with the same query, it goes through a separate, pre-approved permission path designed specifically for content search. The result is the same, but the UX is cleaner and the tool results are better structured for Claude to parse.
| Operation | Dedicated Tool | Bash Equivalent | Why Use the Tool |
|---|---|---|---|
| Find files by pattern | Glob | find . -name '*.ts' | Sorted by modification time, cleaner output |
| Search file contents | Grep | grep -rn 'pattern' . | Structured results, better permission handling |
| Read a file | Read | cat file.ts | Supports offset/limit, integrated with Edit |
| Edit a file | Edit | sed or awk | Atomic, tracked by checkpoints, returns diff |
| Write a new file | Write | echo > or tee | Atomic, tracked by checkpoints |
Claude reserves the Bash tool for things that genuinely need a shell: running tests, executing build commands, git operations, installing packages, starting dev servers. File reading and searching use the dedicated tools.
Glob: Finding Files by Pattern
Glob is Claude's file discovery tool. It matches file paths against glob patterns and returns matching paths sorted by modification time — most recently modified files first. This sorting is intentional: recently modified files are often the most relevant ones.
Claude typically starts codebase orientation with a few broad Glob queries to understand directory structure before narrowing to specific files. It's the equivalent of a new engineer running `ls -la` and `tree` — a structural overview before diving in.
Grep: Searching File Contents
After finding the right files with Glob, Claude uses Grep to search their contents. Grep runs regex patterns across files and returns matching lines with context. The key advantage over Bash grep is output structure — results come back in a format Claude can parse efficiently.
Claude can filter Grep results by file type (e.g., only TypeScript files, only Python files) or by glob pattern (e.g., only files in src/api/). This prevents false positives from node_modules, build output, and lock files.
Read: Getting Full File Contents
Read is the primary tool for retrieving file contents. It reads files with line numbers prepended — useful for Edit operations, which reference line numbers to make targeted changes. Unlike Bash cat, Read integrates directly with the Edit tool's targeting system.
For large files, Read supports offset and limit parameters to read specific sections without consuming the full file content. Claude uses these when it knows which part of a file it needs — a specific function, a class definition, a config block — rather than reading the entire file.
Claude Code's Read tool can read image files (PNG, JPG) visually and PDF files. For large PDFs, you must specify page ranges. This matters when debugging UI issues where screenshots are more informative than code.
Orientation Strategy for Large Repos
When Claude Code is dropped into an unfamiliar large repo, it follows a consistent orientation strategy before attempting any task. This strategy minimizes wasted reads and builds a useful mental map efficiently.
Structure scan
Glob for top-level structure: `**/{package.json,pyproject.toml,Cargo.toml}`, `apps/*/`, `packages/*/`. This immediately reveals whether it's a monorepo, which apps exist, and what package manager is in use.
Config files
Read key config files: package.json (dependencies, scripts), tsconfig.json (TypeScript settings), .env.example (required env vars), CLAUDE.md (project-specific instructions). These give the most information per token.
Entry points
Grep for entry point patterns (`export default`, `app.listen`, `ReactDOM.render`, `main()`) and read the top-level index files. Entry points reveal the architecture style (REST API, CLI, frontend app, library).
Task-specific navigation
Once oriented, Claude navigates to the specific files relevant to the task using Glob and Grep. The orientation map is used to make these subsequent queries efficient.
A developer handed Claude Code a 200-file backend service they had never seen before, asking it to 'add pagination to the /products endpoint'. Before writing a single line, Claude ran: Glob for route files, Read on the routes index to find the products route, Read on the products controller to understand the current query shape, Grep for the database query pattern used elsewhere, Read on one existing paginated endpoint to see the expected response shape. Total: 5 targeted reads, zero wasted ones. The pagination was then implemented correctly on the first attempt.
Learn this in → Orientation reads are not waste — they are the investment that makes the action phase precise.
Best Practices
Do
- ✓Let Claude do its orientation reads — interrupting the gather phase leads to worse action-phase decisions
- ✓If you know exactly which files are relevant, tell Claude upfront to skip the discovery phase
- ✓Add CLAUDE.md with architecture overview to help Claude orient faster in every session
- ✓Use Glob patterns in your CLAUDE.md to point Claude at the right directories (e.g., 'API routes are in src/routes/')
Don’t
- ✗Don't ask Claude to read the entire codebase — ask it to solve a specific problem in specific files
- ✗Don't be surprised if Claude reads a file and then reads a section of it again — the second read is usually targeted on a specific line range
- ✗Don't override Claude's tool choices by insisting it use Bash grep instead of Grep — the dedicated tool works better
Key Takeaways
- ✓Glob, Grep, and Read are preferred over Bash for file operations — better permissions and structured output
- ✓Glob finds files by pattern, sorted by modification time (most recent first)
- ✓Grep searches contents with regex — Claude's primary cross-file symbol discovery tool
- ✓Read supports offset/limit for targeted reading of large files
- ✓Claude's orientation strategy: structure scan → config files → entry points → task-specific navigation
Video on this topic
How Claude Code Navigates Your Codebase
tiktok