How Claude Code Reads Your Codebase

Claude Code doesn't just read your files — it explores them intelligently. When you ask Claude to "add authentication to the API," it doesn't randomly grep through thousands of files. It follows patterns, reads related modules, and builds a mental model of your codebase before making changes.

This lesson reveals the tool system powering that exploration: six core tools Claude uses to read, search, and modify your code. You'll learn not just what each tool does, but how Claude thinks when using them — and how to guide that exploration for better results.

The Tool System: Unix Philosophy for AI

Claude Code operates on a simple principle: one tool, one job, done well. Each tool in Claude's arsenal has a focused purpose:

• Read files
• Edit specific strings
• Write new files
• Glob for file patterns
• Grep for code patterns
• Bash for shell commands

When you ask Claude to do something, it autonomously selects the right tools. Ask it to "refactor the auth module," and Claude might:

1. Use Glob to find src/auth/**/*.ts
2. Use Read to examine auth/login.ts and auth/token.ts
3. Use Grep to find all imports of AuthService
4. Use Edit to update function signatures
5. Use Bash to run tests

You don't orchestrate this — Claude does. Your job is to guide the exploration, not micromanage the tools.

Core File Tools: Deep Dive

Read: The Explorer

Read is Claude's eyes into your codebase. It loads file contents so Claude can analyze code, understand structure, and make informed decisions.

Basic usage:

Read /path/to/file.ts

What makes Read powerful:

1. Line offsets for large files: If a file has 10,000 lines, Claude can read lines 500-600 instead of loading everything.

   Read /path/to/huge-file.ts (offset: 500, limit: 100)
   

2. Multimodal support: Read works with more than just text.

   • Images: Claude can read PNG, JPG files and describe what's in them.
   • PDFs: Specify page ranges for large documents (e.g., pages: "1-5").
   • Jupyter notebooks: Reads all cells with outputs, combining code and visualizations.

3. Auto-read with @ mentions: When you reference @file.ts in your message, Claude automatically reads it. No manual Read tool call needed.

Example scenario:

You: "Why is the homepage loading slowly? @src/app/page.tsx"

Claude automatically reads page.tsx, might notice a heavy component import, then reads that component file to diagnose the bottleneck.

Edit: The Surgeon

Edit performs precise, surgical changes to existing files. It uses an old_string/new_string pattern — like find-and-replace, but with context.

Basic pattern:

Edit /path/to/file.ts
  old_string: "function login(username: string)"
  new_string: "function login(username: string, rememberMe: boolean)"

Critical rules:

1. old_string must be unique: If the same string appears twice in a file, Edit fails. Provide more surrounding context to make it unique.

   Bad (ambiguous):

   old_string: "const API_URL"
   

   Good (unique):

   old_string: "const API_URL = 'https://api.example.com';\nconst TIMEOUT = 5000;"
   

2. Preserve exact indentation: The indentation in old_string must match the file exactly (spaces vs tabs, number of spaces).

3. replace_all for renaming: Use the replace_all: true flag to rename variables/functions across a file.

   Edit /path/to/file.ts (replace_all: true)
     old_string: "oldFunctionName"
     new_string: "newFunctionName"
   

When Edit fails, it's usually because:

• The old_string doesn't exist exactly as written (whitespace mismatch)
• The old_string appears multiple times (not unique)
• You included line numbers from Read output (strip those out)

Write: The Creator

Write creates new files or completely overwrites existing ones. Use it sparingly — prefer Edit for existing files.

Basic usage:

Write /path/to/new-file.ts
  content: "export const config = { apiUrl: '...' };"

Key restrictions:

1. Must Read before Write for existing files: Claude must read a file before overwriting it. This prevents accidental data loss.
2. No emoji by default: Claude won't add emojis to files unless you explicitly request them.
3. Prefer Edit over Write: Editing preserves file history better in git, and Edit fails gracefully if something's wrong.

When to use Write:

• Creating new configuration files (.env, tsconfig.json)
• Generating boilerplate (components, tests)
• Creating documentation that doesn't exist yet

When NOT to use Write:

• Updating existing code (use Edit)
• Refactoring (use Edit)
• Fixing bugs (use Edit)

Glob: The Pattern Matcher

Glob finds files by name pattern. It's fast, works on any codebase size, and returns results sorted by modification time (newest first).

Common patterns:

Glob "**/*.ts"              # All TypeScript files
Glob "src/**/*.tsx"         # All TSX files in src/
Glob "**/*.test.ts"         # All test files
Glob "components/**/Button*" # All Button-related files in components/

When to use Glob:

• Finding files by naming convention (e.g., all *.config.js files)
• Listing files in a directory
• Discovering related files (e.g., all components in a folder)

Glob vs Grep:

• Glob: Matches file names/paths
• Grep: Searches file contents

Example workflow:

You: "Find all API route files"
Claude: Glob "src/app/api/**/*.ts"
Result:
  - src/app/api/auth/route.ts
  - src/app/api/users/route.ts
  - src/app/api/posts/route.ts

Grep: The Code Hunter

Grep searches file contents using regex. It's powered by ripgrep (fast, powerful, designed for code search).

Three output modes:

1. files_with_matches (default): Returns file paths that match.

   Grep pattern="AuthService"
   Result: src/auth/login.ts, src/auth/token.ts, src/app/api/auth/route.ts
   

2. content: Shows matching lines with context.

   Grep pattern="function.*login" output_mode="content" context=2
   Result:
     src/auth/login.ts:15
     14:  */
     15: function loginUser(username: string, password: string) {
     16:   return authService.authenticate({ username, password });
   

3. count: Shows number of matches per file.

   Grep pattern="TODO" output_mode="count"
   Result: src/auth/login.ts (3), src/app/page.tsx (1)
   

Advanced features:

1. Regex support: Use full regex syntax.

   Grep pattern="log.*Error"  # Matches logError, logger.Error, etc.
   

2. Glob filtering: Search only specific file types.

   Grep pattern="useState" glob="**/*.tsx"
   

3. Type filtering: Use common file type shortcuts.

   Grep pattern="def " type="py"  # Only Python files
   

4. Case-insensitive: Use the -i flag.

   Grep pattern="api_key" -i=true  # Matches API_KEY, api_key, ApiKey
   

5. Multiline matching: For patterns spanning multiple lines.

   Grep pattern="interface.*\\{[\\s\\S]*?email" multiline=true
   

Example scenario:

You: "Where do we use the old API endpoint?"
Claude: Grep pattern="api.old-domain.com" output_mode="content"
Result: Shows all files + line numbers where the old endpoint appears.

Bash: The Swiss Army Knife

Bash executes shell commands. Use it for git operations, running tests, npm commands, docker, and anything else you'd do in a terminal.

Common use cases:

1. Git operations:

   bash

   git status
   git log --oneline -10
   git blame src/auth/login.ts
   git diff main...feature-branch

2. Running tests:

   bash

   npm test
   pytest tests/
   cargo test

3. Package management:

   bash

   npm install axios
   pip install requests
   cargo add tokio

4. Build operations:

   bash

   npm run build
   docker build -t myapp .

Key features:

1. Timeout support: Commands timeout after 2 minutes by default (configurable up to 10 minutes).
2. Background execution: Use run_in_background: true for long-running commands.
3. Working directory persists: Each Bash call remembers the current directory.
4. Quoted paths for spaces: Always use quotes for paths with spaces.

   bash

   cd "/Users/name/My Documents"  # Correct
   cd /Users/name/My Documents    # Wrong — will fail

What NOT to use Bash for:

• Reading files (use Read)
• Searching files (use Grep)
• Editing files (use Edit)
• Finding files (use Glob)

Use the specialized tools — they're faster, safer, and designed for the task.

How Claude Explores: The Gather Phase

When you ask Claude to do something, it doesn't jump straight to code changes. It enters a gather phase — autonomously exploring your codebase to understand what needs to happen.

Example exploration flow:

You: "Add a forgot password feature to the auth system"

Claude's gather phase:

1. Glob src/auth/**/*.ts → Discovers auth module structure
2. Read auth/login.ts → Understands current login flow
3. Read auth/token.ts → Sees how tokens are generated
4. Grep "sendEmail" → Finds existing email service
5. Read services/email.ts → Understands email infrastructure
6. Bash git log --oneline src/auth/ → Checks recent auth changes
7. Read auth/register.ts → Finds pattern for new auth endpoints

Now Claude has enough context to propose a solution: create auth/forgot-password.ts, add a password reset route, integrate with the email service, and follow the existing auth patterns.

You didn't tell Claude to do any of that exploration — it inferred what to read based on the task.

Guiding Exploration: Make Claude Smarter

Claude explores autonomously, but your guidance makes it faster and more accurate. Here's how to steer the exploration:

1. Use @ Mentions to Point Claude

The most powerful navigation tool: @ mentions.

Examples:

"Explain how @src/auth/login.ts works"
"Why is @components/Header.tsx re-rendering so often?"
"Compare @old-api.ts and @new-api.ts"
"Look through @screenshots/error.png and debug the issue"

When you use @, Claude automatically reads that file/directory. No need to say "read the file first."

2. Be Specific About Location

Vague request:

"Find the login code"

Claude might search the entire codebase, finding 10 files with "login" in them.

Specific request:

"Look at the auth module in src/auth/ and find the login handler"

Claude starts in the right directory, saving time and tokens.

3. Reference Patterns

If your codebase has established patterns, point Claude to examples.

Example:

"Create a new widget for hot dogs. Follow the same pattern as @widgets/HotDogWidget.php"

Claude reads the example widget, extracts the pattern (file structure, naming conventions, methods), and applies it to the new widget.

4. Point to Git History

For complex refactors or debugging, git history is gold.

Example:

"Look through git history of ExecutionFactory.php — when did the performance regression start?"

Claude runs:

git log --oneline src/ExecutionFactory.php
git show <commit-hash>

And pinpoints when the issue was introduced.

5. Start Broad, Then Narrow

For unfamiliar codebases, use a funnel approach:

1. Broad overview: "Give me an overview of the project structure"
2. Module-level: "Explain the auth module"
3. Function-level: "How does token refresh work in auth/token.ts?"

Each level gives Claude more context for the next.

Large Codebase Strategies

When working with massive projects (10,000+ files), standard exploration hits limits. Here's how to stay efficient:

1. Use Subagents for Exploration

Create a subagent to explore and report back. This keeps your main conversation context clean.

Example:

You: "Create a subagent to map out the auth system and summarize how it works"

The subagent explores, reads 20 files, and returns a summary. Your main agent doesn't pay the token cost for all that reading.

2. Leverage CLAUDE.md

A well-written CLAUDE.md file in your project root acts as a map.

Example CLAUDE.md snippet:

## Project Structure
- `src/auth/` - Authentication (login, token refresh, password reset)
- `src/api/` - API routes (REST endpoints)
- `src/db/` - Database layer (Prisma ORM)
 
## Key Patterns
- API routes: `src/api/<resource>/route.ts`
- Components: `src/components/<name>/<Name>.tsx`
- Tests: `__tests__/<name>.test.ts`

Claude reads this first, navigates faster, and asks fewer clarifying questions.

3. Use Directory @ Mentions for Listings

Reference directories to get a file listing:

"What's in @src/components?"

Claude lists files without reading contents — useful for getting oriented.

4. Incremental Context Building

Don't ask Claude to understand the entire codebase at once. Build context incrementally:

Session 1: "Map out the auth module" Session 2: "Now explain how auth integrates with the API layer" Session 3: "Show me how errors are handled across auth and API"

Each session builds on the last, and you can save summaries to CLAUDE.md for future reference.

Permission System Overview

Not all tools are created equal. Some read data (safe), others modify files or execute commands (potentially dangerous).

Permission tiers:

1. No permission required: Read, Glob, Grep
2. Permission required: Edit, Write, Bash

Approval modes (Shift+Tab to cycle):

• Ask mode: Claude asks before running Edit/Write/Bash
• Autorun mode: Claude runs Edit automatically (still asks for Bash)
• Full auto mode: Claude runs everything without asking

Best practice for learning: Start in Ask mode. See what Claude wants to do before approving. Once you trust it, move to Autorun.

Exercise: Navigate a Real Project

Let's apply what you've learned. Find a project on your machine (or clone a public repo) and try these tasks:

Reflection questions:

• How many tools did Claude use for each task?
• Did @ mentions make Claude's exploration more accurate?
• Were there moments where Claude read irrelevant files? How could you have guided it better?

What's Next

You've mastered how Claude reads and explores codebases. Next lesson: Writing Features from Scratch — where you'll learn to build complete, multi-file features by decomposing requirements into clear steps, guiding Claude to follow existing codebase patterns, and verifying each piece as you go.

The exploration skills you just learned become the foundation for everything that follows.