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_tree call 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.

Claude Code Context Install (2026): A Complete Setup and Context Engineering Guide for Engineers

You’ve heard the hype. You’ve seen the demos. And then you actually tried to install Claude Code, get it pointed at your codebase, and have it do something useful — and hit a wall.

Maybe npm install -g @anthropic-ai/claude-code worked but the tool ignored your project structure. Maybe your CLAUDE.md got too long and the model started behaving strangely. Maybe you watched a subagent spawn and silently fail without any useful error.

This guide cuts through all of that. It covers the full path from a clean machine to a productive Claude Code workflow: install steps, CLAUDE.md architecture, context budgeting, hooks, and the subagent model — with concrete examples at each stage.

---

TL;DR

Claude Code is Anthropic’s terminal-based AI coding agent, installed via npm and authenticated with an Anthropic API key. The two biggest productivity levers aren’t in the install — they’re in (1) authoring a well-structured CLAUDE.md file that gives the model persistent context, and (2) understanding how context windows fill up so you don’t hit invisible limits mid-task. By the end of this guide, you’ll have a working install, a reusable CLAUDE.md template, and a mental model for the context engineering decisions that separate productive Claude Code users from frustrated ones.

Quick answer: Install with npm install -g @anthropic-ai/claude-code, run claude in your project root, and create a CLAUDE.md file there to give the model persistent project context. That’s the minimum viable setup.

---

Why Context Engineering Is the Real Learning Curve

Most engineers get the install right on the first try. The friction comes later — usually within the first hour of serious use.

GitHub Issues and community discussions consistently surface three pain points:

1. CLAUDE.md setup and context size limits. Engineers write a thorough CLAUDE.md — architecture decisions, coding conventions, environment variables, dependency notes — and then discover that Claude Code’s context window has a hard limit. Long CLAUDE.md files eat into the budget for actual code. The model starts losing track of earlier instructions. Tasks that worked yesterday start producing worse output today because the codebase grew and the context filled up.

2. Install steps on macOS and Linux. The npm install is straightforward, but first-time users frequently hit issues with Node version requirements, global npm permission errors on macOS, and PATH issues in non-standard shell setups (fish, zsh with unusual configs, or nix-managed environments).

3. Understanding subagents and hook configuration. Claude Code can spawn subagents — specialized instances that run subtasks in parallel or in sequence. This is powerful, but the failure modes are opaque. Hooks let you run pre/post commands around agent actions, but the configuration syntax isn’t obvious, and mistakes produce silent failures rather than clear errors.

None of these are blockers. They’re configuration problems with known solutions. Let’s work through all three.

---

Step 1: Install Claude Code

Prerequisites

Claude Code requires Node.js 18 or higher. Check your version:

node --version

If you’re below 18, update via nvm (recommended) or the official Node.js installer:

nvm install 20
nvm use 20

You also need an Anthropic API key. Claude Code calls the API directly — there’s no separate subscription at the tool level, but you’re billed for API usage per token.

Install the Package

npm install -g @anthropic-ai/claude-code

Fixing Permission Errors on macOS

If you hit EACCES: permission denied on a system-managed npm, don’t use sudo npm install -g. Instead, configure npm to use a user-writable directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Installing on Linux

The same pattern applies on Linux. If you’re using a package-manager-installed Node (apt, dnf), consider switching to nvm to avoid permission issues:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
npm install -g @anthropic-ai/claude-code

Authenticate

Set your API key as an environment variable. The recommended approach is adding it to your shell profile so it persists:

export ANTHROPIC_API_KEY="sk-ant-..."

Add this line to ~/.zshrc, ~/.bashrc, or ~/.profile depending on your shell.

Alternatively, Claude Code will prompt you for the key on first run and store it in its local config.

Verify the Install

claude --version

Then run it for the first time:

cd your-project-directory
claude

You’ll drop into an interactive session. Claude Code reads your current directory automatically. Type a question about your codebase to confirm it’s reading files correctly.

The official Claude Code documentation covers additional install options including enterprise proxy configurations.

---

Step 2: Understand the Context Window

Before writing a single line of CLAUDE.md, you need to understand what you’re working with.

Claude Code uses Claude models under the hood. The context window — the total amount of text the model can “see” at once — has a fixed token budget. Everything counts against it:

• The contents of your CLAUDE.md file
• The current conversation history
• Files the agent reads during a task
• Subagent outputs that get pulled back into the main session
• Tool call results (bash output, file reads, search results)

The window doesn’t scroll. Once it fills, older content gets truncated — and the model has no memory of it. This is the most common source of degraded performance mid-session.

Practical Implications

A CLAUDE.md file that reads like a comprehensive internal wiki — 3,000 tokens of architecture notes — leaves 197,000 tokens for the actual task on a 200k-context model. That sounds fine until the agent starts reading large source files, generating long diffs, and chaining tool calls. Context pressure builds fast.

The right mental model: CLAUDE.md is a context allocation decision, not a documentation exercise. Every sentence you add competes with actual code.

Monitoring Context Usage

Claude Code shows a context usage indicator in the UI. Pay attention to it during long sessions. When the indicator shows high usage, start a fresh session rather than pushing through — response quality degrades noticeably as context fills up.

---

Step 3: Write an Effective CLAUDE.md

CLAUDE.md is a markdown file placed at your project root (or at ~/.claude/CLAUDE.md for global settings). Claude Code reads it at the start of every session, making it the primary mechanism for persistent context.

What Belongs in CLAUDE.md

The goal is to give the model the information it couldn’t infer from reading your code — constraints, conventions, and environment facts.

High-value content:

## Tech Stack
- Backend: Python 3.11, FastAPI
- Database: PostgreSQL 15, SQLAlchemy 2.x with async sessions
- Testing: pytest, factory_boy for fixtures
- Deploy target: AWS Lambda (container image, not zip)

## Code Conventions
- All database queries go in `src/repositories/`, not in route handlers
- Use `src/services/` for business logic
- Type hints required on all public functions
- Error handling: raise domain exceptions from services, convert to HTTP responses in routes

## Environment
- Local dev: Docker Compose (`docker-compose up`)
- `.env.example` shows required vars — copy to `.env`, never commit `.env`
- Database migrations: `alembic upgrade head`

## What NOT to Do
- Never use synchronous SQLAlchemy calls in async route handlers
- Don't put business logic in Pydantic models
- Don't modify migrations that have already been applied to staging

Low-value content to avoid:

• Project history (“we used to use Django but switched in 2023”)
• Aspirational statements (“we aim for full test coverage”)
• Information the model can read from package.json, pyproject.toml, or README
• Lengthy API documentation for libraries the model already knows

Layered CLAUDE.md Strategy

For large codebases, use a hierarchy:

project-root/
├── CLAUDE.md              # Top-level: stack, conventions, critical constraints
├── src/
│   ├── api/
│   │   └── CLAUDE.md      # API-specific rules, route conventions
│   └── workers/
│       └── CLAUDE.md      # Worker-specific patterns, retry logic

Claude Code reads subdirectory CLAUDE.md files when it navigates into those directories. This keeps top-level context tight while providing depth where needed.

CLAUDE.md Size Budget

A practical ceiling is 500-800 tokens for a top-level CLAUDE.md (roughly 400-600 words). Beyond this, you’re paying a fixed per-session tax for diminishing returns. If your CLAUDE.md is growing beyond this, it’s a signal to move documentation into code comments, README sections, or subdirectory CLAUDE.md files.

Check your CLAUDE.md token count with any tokenizer. Anthropic’s tokenizer documentation covers the approach for Claude models.

---

Step 4: Structure Your Workflow

Claude Code works best when you treat it as a collaborator that handles discrete, well-defined tasks — not as an autopilot you set running on an entire feature.

Effective Task Framing

Weak prompt:

Refactor the authentication module.

Strong prompt:

Refactor src/auth/jwt_handler.py to use the jose library instead of PyJWT.
- The function signatures in auth/jwt_handler.py must not change (other modules depend on them)
- Update requirements.txt
- Run existing tests and show me the output
- Don't touch src/auth/oauth.py

The more specific you are about scope and constraints, the less context gets consumed by clarifying back-and-forth, and the less likely the model is to make changes you didn’t intend.

Session Discipline

Start a fresh Claude Code session for each distinct task. Don’t carry a session through “fix the bug → write the tests → update the docs → refactor the related module” in one sitting. Each task boundary is an opportunity to reset context and start clean.

For multi-step workflows that genuinely need continuity, use Claude Code’s memory features — storing important intermediate results in files and having the model read them back at the start of the next step.

---

Step 5: Configure Hooks

Hooks run shell commands before or after specific Claude Code actions. They’re the mechanism for integrating Claude Code into your existing toolchain — running linters before the model commits code, triggering test suites after file writes, or logging agent activity.

Hook Configuration

Hooks are configured in ~/.claude/settings.json (global) or .claude/settings.json (project-local):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run bash command'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_ROOT && npm run lint --silent"
          }
        ]
      }
    ]
  }
}

Common Hook Patterns

Run tests after file writes:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_ROOT && pytest tests/ -q --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

Format code before the model sees it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_ROOT && black --check . --quiet || true"
          }
        ]
      }
    ]
  }
}

Hook Debugging Tips

Hook failures are logged but don’t always surface clearly in the UI. If a hook seems to be silently failing:

1. Test the command manually in your terminal first
2. Use absolute paths or $PROJECT_ROOT — relative paths in hooks can fail depending on the working directory
3. Add 2>&1 to capture stderr
4. Keep hook commands fast — slow hooks block the agent and burn context on waiting

See the hooks documentation for the complete event list and configuration reference.

---

Step 6: Work With Subagents

Claude Code can spawn subagents — separate agent instances that handle subtasks and return results to the main session. This enables parallelism and specialization, but adds complexity.

When Subagents Help

Subagents are useful when a task has genuinely independent components:

• Running a test suite while the main agent continues writing code
• Analyzing multiple files in parallel before synthesizing conclusions
• Delegating a well-defined subtask (e.g., “write unit tests for this module”) while the main session handles the implementation

When Subagents Hurt

Subagents consume context. Each subagent spawns its own session, does work, and returns output — that output then gets pulled back into the main session’s context window. A subagent that reads large files and produces verbose output can significantly accelerate context exhaustion.

Don’t use subagents for:
– Tasks where the subtask output will be large and mostly irrelevant
– Simple sequential tasks that don’t benefit from parallelism
– Cases where you need tight control over what the model does step by step

Monitoring Subagent Behavior

Claude Code surfaces subagent activity in its output. When a subagent completes, review what it actually did — the model’s summary of subagent work can omit important details. If a subagent touched files you didn’t expect, check git diff.

The Claude Code subagents documentation covers the full API for configuring custom subagent behaviors.

---

Common Mistakes to Avoid

• Writing CLAUDE.md as documentation, not instructions. The model doesn’t need project history or aspirational goals. It needs constraints, conventions, and facts it can’t infer from the code itself.

• Running long sessions without checking context usage. Performance degrades before the context limit is hit. Monitor the indicator; restart sessions proactively.

• Using vague task descriptions. “Fix the authentication bug” forces the model to explore broadly, burning context on investigation. Narrow the scope: “The JWT expiry check in src/auth/jwt_handler.py line 47 is comparing timestamps incorrectly — fix it and update the test in tests/test_jwt.py.”

• Ignoring hook stderr. Hooks that fail silently are worse than no hooks — they create a false impression that the step ran. Always capture stderr in hook commands.

• Treating subagent output as authoritative. Subagents can hallucinate or make mistakes just like the main agent. Review their output, especially when they make file changes.

---

Quick Reference

Task	Command / Action
Install Claude Code	npm install -g @anthropic-ai/claude-code
Set API key	export ANTHROPIC_API_KEY="sk-ant-..." in shell profile
Start a session	cd your-project && claude
Global CLAUDE.md location	~/.claude/CLAUDE.md
Project CLAUDE.md location	{project-root}/CLAUDE.md
Project settings/hooks	.claude/settings.json
Global settings/hooks	~/.claude/settings.json
Check context usage	UI indicator during session
Recommended CLAUDE.md size	500-800 tokens (~400-600 words)
Node.js minimum version	Node 18+ (Node 20 LTS recommended)
Official docs	docs.anthropic.com/en/docs/claude-code
Claude Code homepage	claude.ai/code

CLAUDE.md Minimal Template

## Stack
- [Language/runtime version]
- [Framework and version]
- [Database]
- [Test runner]

## Project Structure
- [Key directory conventions, e.g., "business logic in src/services/"]

## Code Conventions
- [Style rules not enforced by linter]
- [Naming conventions]
- [Error handling patterns]

## Environment
- [How to run locally]
- [Key environment variables]
- [Migration or seed commands]

## Constraints
- [What the model must NOT do]
- [Files/directories to leave alone]

---

FAQ

Q: What Node.js version does Claude Code require?

Claude Code requires Node.js 18 or higher. Node 20 LTS is the recommended version for stability. Check your current version with node --version. If you need to manage multiple Node versions, nvm is the most reliable tool on both macOS and Linux — it avoids the permission issues that come with system-level Node installs and makes version switching simple.

Q: How big should my CLAUDE.md file be?

Aim for 500-800 tokens, roughly 400-600 words. CLAUDE.md content is loaded at the start of every session and counts against the context window for the entire session. A 2,000-token CLAUDE.md isn’t catastrophic on a 200k-context model, but it’s a fixed overhead that compounds with long sessions and large files. Prioritize constraints and conventions the model can’t infer from reading your code. Move general documentation to README or inline comments.

Q: Why does Claude Code perform worse later in a long session?

Context pressure. The context window is fixed — as the session accumulates conversation history, tool call results, and file contents, older information gets truncated. The model loses access to earlier instructions and context. This isn’t a bug; it’s a fundamental property of how transformer models work. The mitigation is session discipline: start a fresh session for each distinct task, and use files to pass state between sessions rather than relying on the model to remember earlier conversation.

Q: Can I use Claude Code on Linux?

Yes. The install process is identical — Node 18+, npm install -g @anthropic-ai/claude-code, set ANTHROPIC_API_KEY. The main gotcha on Linux is Node permission issues when using a system package manager. Use nvm to install Node in user space to avoid EACCES errors on global npm installs. Claude Code’s file access and bash tool work the same on Linux as on macOS.

Q: What’s the difference between global and project-level CLAUDE.md?

Global CLAUDE.md (~/.claude/CLAUDE.md) applies to every Claude Code session regardless of which project you’re in. Use it for personal preferences — your preferred coding style, how you want the model to communicate, global toolchain facts. Project CLAUDE.md ({project-root}/CLAUDE.md) applies only when Claude Code runs in that directory tree. Use it for project-specific conventions, stack details, and constraints. When both exist, Claude Code reads both — global first, then project-level — so project settings can override or extend global ones.

Q: How do I debug a hook that isn’t working?

Three steps: (1) Run the hook command manually in your terminal from the same directory Claude Code would use — if it fails there, it’ll fail in the hook. (2) Add 2>&1 to the command to capture stderr, which often contains the actual error. (3) Use absolute paths or the $PROJECT_ROOT environment variable rather than relative paths — the working directory in hook execution can be different from what you expect. Hook output appears in Claude Code’s session log; check there for command exit codes.

---

Where to Go From Here

The Claude Code documentation covers the full feature set, including the settings schema, all available hook events, and the subagent API. The GitHub repository has open issues that reflect real-world friction points — useful reading for understanding edge cases and current limitations.

The most productive Claude Code users tend to share one trait: they treat context as a finite resource and make deliberate decisions about how to spend it, rather than assuming the model will figure things out from a firehose of information. That discipline, more than any specific config, is what separates frustrating sessions from productive ones.

Start with a clean install, a tight CLAUDE.md, and a single well-scoped task. Build from there.