Why Not Load Everything?

An intuitive idea: since Claude needs to understand my codebase, why not just load all the code into the context window?

The answer is: you can’t. For three reasons:

• Context window limits: Even with a 200K token context window, a mid-size project (100,000 lines of code) easily exceeds this limit. One line of code consumes roughly 3-5 tokens, so 100K lines means 300K-500K tokens — far beyond the context window capacity.
• Cost is prohibitive: Every token has a cost. Loading the entire codebase means paying for irrelevant code on every conversation turn. If you just want to tweak a button’s style, why pay for database migration scripts?
• Noise drowns the signal: Even if it could fit, massive amounts of irrelevant code dilutes the truly important information. The model’s ability to find key code in a sea of noise degrades sharply — this is the “needle in a haystack” problem.

So Claude Code employs a smarter strategy: on-demand retrieval. Instead of moving every book into the room, go to the library when needed, find that book, and turn to the right page.

The Search Toolkit: Glob, Grep, Read

Claude Code’s core ability to understand codebases is built on three search tools. Each has its strengths, and used together they work like an experienced developer navigating a codebase.

Glob: Find Files by Pattern

Glob is a file path pattern-matching tool. When you know what type of file you’re looking for but aren’t sure where it lives, Glob is your first choice.

// Find all TypeScript files
Glob("**/*.ts")
→ src/index.ts, src/utils/helper.ts, src/services/user.ts, ...

// Find all React components under components/
Glob("src/components/**/*.tsx")
→ src/components/Button.tsx, src/components/Modal.tsx, ...

// Find all test files
Glob("**/*.test.{ts,tsx}")
→ src/__tests__/user.test.ts, src/components/Button.test.tsx, ...

// Find config files
Glob("*config*")
→ tsconfig.json, tailwind.config.ts, vite.config.ts, ...

Grep: Search File Contents

Grep is a content search tool with full regex support. When you know a keyword exists in the code but don’t know which file, Grep is the weapon of choice.

// Find a class definition
Grep("class UserService")
→ src/services/user-service.ts:15: export class UserService {

// Find all call sites of a function
Grep("handleSubmit\(")
→ src/components/LoginForm.tsx:42: onClick={handleSubmit}
→ src/components/RegisterForm.tsx:38: onSubmit={handleSubmit}

// Find TODO comments
Grep("TODO|FIXME|HACK")
→ src/utils/cache.ts:23: // TODO: implement cache invalidation
→ src/api/auth.ts:67: // FIXME: token refresh race condition

Read: Read File Contents

Read is the precision tool. When you already know which file to examine, Read lets you view all or part of its contents.

// Read an entire file
Read("src/services/user-service.ts")
→ (returns full file contents)

// Read only a specific line range (useful for large files)
Read("src/services/user-service.ts", offset=100, limit=50)
→ (returns lines 100-150)

The Search Pipeline

These three tools form a broad-to-narrow search pipeline:

Agentic RAG: Agent-Driven Retrieval

Traditional RAG (Retrieval-Augmented Generation) systems typically rely on vector embeddings: convert code chunks into vectors, store them in a vector database, then search by semantic similarity. Claude Code does not use this approach.

Instead, Claude Code employs a tool-driven retrieval approach we call “Agentic RAG” — the AI itself decides what to search for, how to search, and how deep to go. This is not pre-built indexing followed by queries, but real-time, dynamic, multi-step exploration.

Let’s walk through a complete example. When the user says “Add a bulk delete users method to UserService,” Claude’s search process looks like this:

User: "Add a bulk delete users method to UserService"

Step 1: Understand the task, locate the target file
Claude thinks: "I need to find the UserService definition"
→ Grep("class UserService")
→ Result: src/services/user-service.ts:15

Step 2: Read existing code, understand patterns
Claude thinks: "I need to understand the style of existing methods"
→ Read("src/services/user-service.ts")
→ Found: has a deleteUser(id) method, uses Repository pattern

Step 3: Trace dependencies, understand the data layer
Claude thinks: "deleteUser calls UserRepository, I need to check its interface"
→ Grep("class UserRepository")
→ Result: src/repositories/user-repository.ts:8
→ Read("src/repositories/user-repository.ts")
→ Found: Repository has deleteById method, but no bulk delete

Step 4: Check test files, learn testing conventions
Claude thinks: "I should look at how existing tests are written"
→ Glob("**/*user-service*.test.*")
→ Result: src/__tests__/user-service.test.ts
→ Read("src/__tests__/user-service.test.ts")
→ Learned: Tests use Jest + mock Repository

Step 5: Synthesize all information, start coding
Claude now has enough context:
- UserService structure and style
- Repository interface and patterns
- Testing conventions
→ Write bulkDeleteUsers method
→ Add deleteByIds to Repository
→ Write corresponding tests

Note the key characteristics of this process:

• Goal-driven: Every search has a clear purpose, nothing is random browsing
• Iteratively deepening: From class definition to method implementation, from service layer to data layer, progressively deeper
• Context accumulation: Each search result informs the next decision
• Minimal loading: Only reads files that are truly needed, no wasted context window

This is what “Agentic” means — the AI is not passively receiving retrieval results, but actively planning and executing search strategies.

Code Intelligence / LSP

Text search is powerful, but it has blind spots. When you search for handleClick, you might find the definition, call sites, mentions in comments, or even coincidental matches in strings. What you need is semantic-level understanding — what is a definition, what is a reference, what is a variable’s type.

This is where Language Server Protocol (LSP) and code intelligence tools come in.

LSP provides capabilities including:

• Go to Definition: Jump from a function call to its definition. No more guessing which file handleSubmit is defined in.
• Find References: Find every location where a symbol is used. Want to know everywhere UserService is referenced? One command finds them all.
• Type Information: Understand the types of variables and functions. This is essential for understanding code interfaces.
• Symbol Search: Search across the entire project by symbol name, not by text.

In practice, Claude Code combines text search and code intelligence. Text search handles fast, broad sweeps; code intelligence provides precise semantic understanding. They complement each other, forming a comprehensive picture of the codebase.

Context Compaction

Even with on-demand retrieval, long conversations still exhaust the context window. Every tool call result, every file read, consumes precious context space. When the conversation gets long enough, Claude Code triggers Context Compaction.

How Context Compaction works:

1. Detection: Automatically triggers when context window usage approaches the limit
2. Summarization: Intelligently summarizes earlier conversation messages — retains key information (decisions made, files modified, problems encountered), removes redundant details
3. Replacement: Replaces original messages with summaries, freeing context space
4. Continuation: Conversation continues seamlessly — the user barely notices the compaction

Context Compaction is like a person taking notes: you don’t remember every word of a conversation, but you remember the key conclusions and decisions. This allows Claude Code to keep working efficiently through long coding sessions.

Search Strategies in Practice

Now that we understand the tools, let’s look at how Claude Code combines these search strategies in real-world scenarios.

Strategy 1: Broad to Narrow

This is the most common pattern. Start with Glob for a global view, narrow down with Grep, then deep-dive with Read.

// Task: "Refactor all API calls in the project"

// Step 1: Broad sweep — find all potentially relevant files
Glob("src/**/*api*")
Glob("src/**/*service*")
Glob("src/**/*fetch*")

// Step 2: Precise targeting — search for specific API call patterns
Grep("fetch\(|axios\.|api\.get|api\.post", "src/")

// Step 3: Deep understanding — read key files
Read("src/lib/api-client.ts")      // API client wrapper
Read("src/services/user-api.ts")   // Typical API service

Strategy 2: File Names as Signals

Good project structure is the best documentation. File names and directory structures contain rich semantic information.

// Looking for database-related code?
Glob("**/*database*")
Glob("**/*migration*")
Glob("**/prisma/**")
Glob("**/schema*")

// Looking for auth-related code?
Glob("**/*auth*")
Glob("**/*login*")
Glob("**/*session*")
Glob("**/middleware/*")

Strategy 3: Follow Import Chains

Dependencies between code form a graph. Following import statements reveals all related modules.

// Start from the entry point
Read("src/pages/dashboard.tsx")
→ Found: import { UserCard } from '../components/UserCard'

Read("src/components/UserCard.tsx")
→ Found: import { useUser } from '../hooks/useUser'

Read("src/hooks/useUser.ts")
→ Found: import { UserService } from '../services/user-service'

// Now you understand the entire dependency chain:
// Page → Component → Hook → Service

Strategy 4: Test Files as Usage Manuals

Test files are the best documentation for understanding how a module is used. They contain concrete input/output examples and edge cases.

// Not sure how to use a function? Find its tests first
Glob("**/*user-service*.test.*")
Read("src/__tests__/user-service.test.ts")

// Test files tell you:
// - What the function's input parameters are
// - What the expected return values are
// - What the edge cases are
// - How errors are handled

These strategies are not used in isolation — in a real task, Claude typically combines multiple strategies flexibly, much like an experienced developer rapidly building understanding in a new project. The key principle is: every search has a clear purpose, every read accumulates context.