How to Work with Large Codebases in Claude Code

Working with large codebases in Claude Code requires deliberate context management strategies. Unlike small projects where Claude can read everything at once, large repositories and monorepos need careful orchestration to maintain performance and accuracy.

This guide covers proven techniques for managing context, excluding unnecessary files, chunking large refactoring tasks, and optimizing memory usage across macOS, Windows, and Linux.

Understanding Context Limits

Claude Code operates within a fixed context window that functions as working memory:

• Standard context: 200,000 tokens
• Enterprise (Claude Sonnet 4.5): 500,000 tokens

A fresh session in a monorepo typically consumes a baseline of 15-25K tokens (roughly 10-15% of available context) before you start working. This includes:

• System prompts and configuration
• CLAUDE.md contents (loaded automatically)
• Initial file indexing

Check your current context usage with:

/context

This shows how much of your 200K token window is in use.

CLAUDE.md: Your Primary Configuration Tool

The CLAUDE.md file at your repository root is Claude Code's primary source of truth. For large codebases, a well-structured CLAUDE.md dramatically improves performance by helping Claude navigate efficiently.

Recommended Structure for Large Projects

# Project Name

## Quick Reference
- Tech stack: Next.js 15, TypeScript, PostgreSQL
- Build: `npm run build`
- Test: `npm run test`
- Lint: `npm run lint`

## Repository Map

/apps /web # Next.js frontend /api # Express backend /mobile # React Native app /packages /shared # Shared utilities /ui # Component library /types # TypeScript types

## Key Patterns
- All API routes use Edge runtime
- Components follow [Component]/index.tsx pattern
- Tests colocated with source files

## Do Not Touch
- /legacy       # Deprecated, being phased out
- /vendor       # Third-party code

Keep CLAUDE.md Under 10K Words

Research indicates that CLAUDE.md files should stay under 10K words for optimal performance. If your file exceeds this, consider:

1. Split by subdirectory: Place focused CLAUDE.md files in subdirectories
2. Reference instead of embed: Link to separate documentation files
3. Use lazy loading: Put context in subdirectories so it loads only when Claude accesses those paths

Hierarchical CLAUDE.md Files

Claude Code reads CLAUDE.md files hierarchically:

/myproject/CLAUDE.md           # Loads first (root context)
/myproject/apps/CLAUDE.md      # Loads when working in /apps
/myproject/apps/web/CLAUDE.md  # Loads when working in /apps/web

This pattern lets you provide specific context only when relevant, preserving tokens for actual work.

Excluding Files with Permission Rules

Preventing Claude from reading unnecessary files saves tokens and improves focus.

Using settings.json

Create permission rules in your settings file:

User-level settings (~/.claude/settings.json):

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.envrc)",
      "Read(~/.aws/**)",
      "Read(**/*.log)",
      "Read(**/node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/.git/**)"
    ]
  }
}

Project-level settings (.claude/settings.json):

{
  "permissions": {
    "deny": [
      "Read(legacy/**)",
      "Read(vendor/**)",
      "Read(**/*.min.js)",
      "Read(**/*.bundle.js)"
    ]
  }
}

Third-Party .claudeignore Solution

For .gitignore-style exclusions, use the claudeignore npm package:

1. Install the package globally or in your project
2. Configure it in .claude/settings.json as a hook
3. Create a .claudeignore file in your project root:

# Build artifacts
dist/
build/
.next/

# Dependencies
node_modules/
vendor/

# Large data files
*.sql
*.dump
data/fixtures/

# Generated code
generated/
__generated__/

# Secrets
.env*
secrets/

This approach provides hierarchical support, discovering .claudeignore files throughout your directory structure.

Context Management Commands

The /compact Command

When your context reaches 70% usage, it is time to compact:

/compact

This summarizes your conversation history while preserving key information. You can provide custom instructions:

/compact keep all file paths and decisions, summarize implementation details

Context thresholds:

Auto-Compact Behavior

Claude Code auto-compacts at approximately 95% context usage. However, waiting for auto-compact often leads to lost context. Better practice:

1. Compact manually at logical breakpoints
2. Compact after completing a feature or fix
3. Compact before starting a new task area

The /clear Command

Use /clear when switching to completely unrelated work:

/clear

This wipes all context and starts fresh. Use it when:

• Switching between different features
• Starting a new debugging session
• Moving to a different part of the codebase

Chunking Large Refactoring Tasks

Large refactoring operations should be broken into manageable chunks that compile and test independently.

The Batch Strategy

Aim for batches of 5-20 files that represent a logical, self-contained unit:

Good batch: "Refactor all authentication middleware files"
Bad batch: "Refactor everything related to users"

Example: Migrating to Async/Await

Instead of asking Claude to refactor the entire codebase at once:

Step 1: Identify scope

List all files using callback-based patterns in the /services directory

Step 2: Batch by module

Refactor the user service callbacks to async/await.
Files: services/user/*.ts
Run tests after each file to verify.

Step 3: Verify incrementally

Run npm test -- --testPathPattern=services/user

Step 4: Commit the batch

Commit these changes with message "refactor(user-service): migrate to async/await"

Using Subagents for Large Operations

For operations spanning many files, delegate to subagents:

Refactor all 75 files using the deprecated getUserById function.
Use parallel subagents to handle each file independently.
Each subagent should: replace the function call, update imports, run the file's tests.

Subagents run in isolated contexts, preventing the main conversation from filling with verbose output.

Git Worktrees for Parallel Development

Git worktrees enable running multiple Claude Code sessions on different tasks simultaneously.

Setting Up Worktrees

Create a worktree for each feature:

# Create feature branch
git branch feature-auth-refactor

# Create worktree in separate directory
git worktree add ../myproject-auth feature-auth-refactor

# Create another for a different feature
git branch feature-api-v2
git worktree add ../myproject-api feature-api-v2

Directory structure:

~/projects/
  myproject/              # Main working directory (main branch)
  myproject-auth/         # Worktree for auth refactor
  myproject-api/          # Worktree for API v2

Running Parallel Sessions

1. Open separate terminal windows/tabs
2. Navigate to each worktree directory
3. Run claude in each
4. Optionally run /init to orient Claude to the worktree

Each Claude instance works independently without file conflicts.

Worktree Best Practices

• Use consistent naming: project-feature-name
• Run /init in new worktrees: Helps Claude understand the context
• Remove completed worktrees: git worktree remove ../myproject-auth
• Prune stale metadata: git worktree prune

When Worktrees Are Worth It

Worktrees add setup overhead (copying untracked files, installing dependencies). They are most valuable when:

• Tasks take longer than 15-20 minutes
• Multiple features can progress independently
• You want to maximize throughput during focused coding sessions

Memory and Performance Optimization

Reduce Token Usage

Be specific with requests:

Bad:  "Improve the codebase"
Good: "Add input validation to the login function in auth.ts"

Vague requests trigger broad scanning. Specific requests let Claude work efficiently.

Use cheaper models for routine tasks:

/model

Switch to Claude 4 Sonnet or Haiku 3.5 for:

• Basic syntax validation
• Simple text transformations
• Quick status checks
• Routine linting tasks

Reserve Claude 4 Opus for complex reasoning and architectural decisions.

Adjust extended thinking:

Extended thinking improves complex reasoning but costs output tokens. For simple tasks:

/config
# Set MAX_THINKING_TOKENS=8000 or disable thinking

Delegate Verbose Operations

Operations producing large output should run in subagents:

Run the full test suite and summarize failures.
Use a subagent to run tests - only return the summary to this conversation.

This keeps verbose test output in the subagent's context, returning only the summary.

Monitor Your Usage

Check costs and usage regularly:

/cost

Configure your status line to show token usage continuously for awareness during long sessions.

Platform-Specific Considerations

macOS

macOS provides the smoothest Claude Code experience with full feature support.

Recommended setup:

• Use the native installer: curl -fsSL https://claude.ai/install.sh | bash
• Homebrew alternative: brew install --cask claude-code

Performance tips:

• Allocate sufficient RAM (8GB+ recommended for large projects)
• Use Terminal.app or iTerm2 for best compatibility
• Consider Raycast or Alfred integration for quick Claude access

Windows

Windows now supports native Claude Code without WSL (version 2.x+).

Native installation:

irm https://claude.ai/install.ps1 | iex

WSL 2 option (recommended for large projects):

• Provides sandboxing for enhanced security
• Better compatibility with Unix-based build tools
• Run the bash installer inside your WSL environment

Performance tips:

• Use Windows Terminal for better rendering
• Enable Developer Mode for symlink support
• Consider WSL 2 if working with many shell scripts

Linux

Linux support is excellent with the native installer.

Installation:

curl -fsSL https://claude.ai/install.sh | bash

Performance tips:

• Ensure sufficient swap space for large projects
• Use tmux or screen for session persistence
• Configure your shell profile to add Claude to PATH

Advanced Strategies for Monorepos

Scoped Sessions

Use one objective per session and name it explicitly:

Goal: Migrate auth middleware to v2 across web-frontend package only

Reset the session when switching objectives to prevent context pollution.

Feature-Based Exploration

When exploring, organize by feature rather than directory:

Use 4 parallel tasks to explore:
1. Authentication system
2. Data models and ORM
3. API endpoints and routes
4. Test coverage patterns

This catches cross-directory dependencies that directory-based exploration misses.

Custom Slash Commands

Create reusable prompts for common monorepo operations:

.claude/commands/explore-package.md:

Analyze the $ARGUMENTS package:
1. List all exports
2. Document dependencies
3. Identify integration points with other packages
4. Note any technical debt or TODOs

Usage:

/explore-package shared-utils

MCP-Based Semantic Search

For repositories exceeding grep's practical limits, consider Model Context Protocol (MCP) servers that provide semantic code search. These index your codebase and return only relevant code slices, dramatically reducing context consumption.

Troubleshooting Common Issues

Context Fills Too Quickly

Symptoms: Hitting context limits within minutes of starting.

Solutions:

1. Check CLAUDE.md size (should be under 10K words)
2. Add permission deny rules for large directories
3. Use /context to identify what is consuming tokens
4. Disable unused MCP servers with /mcp

Claude Loses Track of Changes

Symptoms: Claude forgets earlier work or makes contradictory changes.

Solutions:

1. Compact proactively at logical breakpoints
2. Use explicit "keep" instructions when compacting
3. Consider splitting work across worktrees
4. Write key decisions to a NOTES.md file Claude can reference

Slow Response Times

Symptoms: Long delays between messages.

Solutions:

1. Reduce extended thinking budget for simple tasks
2. Use specific file references instead of broad searches
3. Delegate verbose operations to subagents
4. Consider switching to a faster model for routine tasks

Subagent Tasks Fail

Symptoms: Subagents return errors or incomplete results.

Solutions:

1. Provide more explicit instructions to subagents
2. Break complex subagent tasks into smaller steps
3. Verify subagent scope does not overlap (use different files)
4. Check that subagent tasks are truly independent

Summary: Best Practices Checklist

Before starting work on a large codebase:

• Create or update CLAUDE.md with repository map and patterns
• Configure permission deny rules for large/irrelevant directories
• Set up git worktrees if planning parallel work
• Check context usage baseline with /context

During work:

• Monitor context usage (compact at 70%)
• Use specific requests rather than broad ones
• Batch related changes into logical units
• Delegate verbose operations to subagents

After completing tasks:

• Compact or clear before switching focus
• Remove completed worktrees
• Update CLAUDE.md with new patterns or learnings

Additional Resources

• Official Claude Code Documentation
• Anthropic's Best Practices for Agentic Coding
• Managing Context on the Claude Developer Platform
• Git Worktrees Documentation

Need help optimizing your development workflow? Inventive HQ provides consulting on AI-assisted development tools and workflows. Contact us for guidance on integrating Claude Code into your team's processes.