Claude Code for Large Codebases: Add Directories, Limit Scope, and Avoid Token Waste
Learn how to use --add-dir and .claudeignore to scope Claude Code precisely in monorepos and enterprise codebases. Practical configs that cut token waste and keep Claude focused on what matters.
Claude Code is a powerful agentic CLI for editing real codebases — but the default behavior assumes a small, focused project. Drop it into a Turborepo monorepo with 80 packages, and without proper scoping it can wander through tens of thousands of files, waste a significant chunk of your context window on generated output and lock files, and produce confused suggestions that blend concerns from unrelated packages.
This guide covers the two core tools for keeping Claude surgical in large codebases — --add-dir and .claudeignore — plus monorepo-specific patterns for per-package context and token budgeting.
The Problem: Large Codebases Without Scope Are Expensive
A typical enterprise Next.js monorepo might have:
apps/web — the main app
apps/admin — a separate admin panel
packages/ui — shared component library
packages/db — Prisma schema and database utilities
packages/shared — type definitions and constants
node_modules/ — hundreds of megabytes of dependencies
dist/, build/, .next/, .turbo/ — compiled output
If you launch claude from the repo root and ask it to "add a new field to the user settings form," Claude may start by indexing every subdirectory it can reach. Without boundaries, it might read lock files, compiled artifacts, and packages completely unrelated to the task at hand — every token spent there is a token not available for the actual code you want changed.
Two features address this directly.
By Default: Claude Works Inside Your Current Directory
When you run claude from a terminal, Claude Code can read and write files relative to the directory you launched it from — and nothing else. That is the safe default.
If you are in apps/web/, Claude can see everything under apps/web/. It cannot reach one level up, even if your component imports from it. This is intentional: it prevents accidental cross-package writes and keeps the blast radius small.
The challenge is that in a monorepo, the package you are editing almost always imports from shared packages. When Claude cannot read those packages, it either guesses at type signatures or asks you to paste code inline — both of which are friction.
Expanding Scope with --add-dir
The --add-dir flag tells Claude Code that it has permission to read and write those additional directories alongside the working directory. You can add multiple directories in a single invocation:
bash
claude --add-dir ../shared-utils --add-dir ../design-system
Practical Monorepo Example (Turborepo / pnpm workspace)
Say you are working on apps/web but your components import from packages/ui and your API routes import from packages/db:
bash
# Working on apps/web, but need access to packages/ui and packages/dbcd apps/web
claude --add-dir ../../packages/ui --add-dir ../../packages/db
Now Claude can read the component types in packages/ui and understand the Prisma schema in packages/db without you needing to paste anything manually. It can also write to those packages if a fix needs to land there — for instance, adding an exported type that both apps/web and apps/admin need.
Persistent Configuration via settings.json
If you always want certain packages available when working from a directory, codify it in .claude/settings.json at the package level:
This file lives inside apps/web/.claude/settings.json. Every time someone runs claude from apps/web/, those directories are automatically available without typing the flags. Commit this file so the whole team benefits.
Limiting Scope with .claudeignore
The second half of scoping is telling Claude what not to read. Create a .claudeignore file in your project root using the same syntax as .gitignore:
snippet
# Dependencies — never useful for Claude to read
node_modules/
.pnp/
.pnp.js
# Build output
.next/
dist/
build/
out/
# Turbo and cache
.turbo/
.cache/
# Coverage and test artifacts
coverage/
.nyc_output/
# Minified and compiled
*.min.js
*.min.css
*.map
# Lock files
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml
# Generated files
*.generated.ts
*.generated.graphql
**/__generated__/
# Static assets Claude doesn't need to index
public/static/
public/images/
Claude Code will not read or traverse ignored paths. On a typical Next.js monorepo, ignoring node_modules/, .next/, and generated files can reduce the number of indexable files from tens of thousands down to a few hundred — the actual source you care about.
What .claudeignore Actually Prevents
When Claude receives a task like "find where we handle auth errors," without .claudeignore it might look through:
node_modules/passport/lib/ — not what you want
.next/server/chunks/ — compiled output, not readable
coverage/lcov-report/ — not relevant
dist/ — stale compiled artifacts
With .claudeignore, that search hits only your actual source files. Results come back faster, use fewer tokens, and are far less likely to surface a false positive from a dependency's internals.
Monorepo-Specific Strategies
1. Launch from the Package, Not the Root
Always cd into the specific package before launching Claude:
bash
# Do thiscd apps/web && claude
# Not this (unless you specifically need repo-wide context)
claude # from repo root
Starting from the package directory means the default scope is already narrow. Add packages on demand with --add-dir rather than trying to limit a root-level launch.
2. Per-Package CLAUDE.md Files
Each package in a monorepo can have its own CLAUDE.md file. When you launch Claude from apps/web, it reads apps/web/CLAUDE.md for package-specific context:
markdown
# apps/web CLAUDE.md## Stack- Next.js 15 App Router
- Tailwind CSS + shadcn/ui components from ../../packages/ui
- Auth via NextAuth, session types in ../../packages/shared/auth.ts
## Key conventions- Components go in src/components/, pages in src/app/
- Use the Button component from @company/ui, not a local one
- All DB access must go through the repository pattern in ../../packages/db/src/
## Do not touch- src/generated/ — auto-generated by graphql-codegen, run pnpm codegen instead
The root CLAUDE.md handles repo-wide conventions (commit format, PR templates, testing requirements), while package-level files handle the specific context for that package.
3. Reference Specific Files with @ in CLAUDE.md
The --add-dir flag grants directory access. A separate but complementary feature is the @file reference syntax inside CLAUDE.md:
This loads the content of those files into Claude's context at startup — useful for small, critical files like type definitions or schemas that Claude should always have in mind. Combine both:
additionalDirectories in settings.json — so Claude can navigate and edit those packages
@file references in CLAUDE.md — so key type files are always pre-loaded in context
Working with Large Files
Some files are too large to read wholesale without burning significant token budget:
Log files — rarely need full content; let Claude use Bash(grep) or Bash(tail) to find relevant lines instead of reading the whole file
Generated data — database seeds, fixture files, large JSON — put these in .claudeignore
Large config files — if your next.config.ts or webpack.config.js is very long, split it into focused modules that Claude can read one at a time
Tell Claude explicitly when you want targeted reads:
"Only look at the files in src/auth/ — don't read anything else unless I specifically ask."
Explicit scoping in your prompt costs almost nothing but saves Claude from exploring broadly.
--add-dir vs @file Reference: When to Use Each
--add-dir / additionalDirectories
@file in CLAUDE.md
What it does
Grants read/write permission to a directory
Loads a file's content into context at startup
Use for
Shared packages Claude may need to navigate or edit
Small, always-relevant files (type defs, schema)
Scope
Entire directory tree
One specific file
Token cost
Low (only reads what it needs)
Fixed per file loaded
Persists?
Via settings.json
Via CLAUDE.md commit
Use --add-dir broadly for packages Claude might need to navigate. Use @file selectively for the small set of files Claude should always have memorized.
Checking What Claude Can See
At any point in a session, ask Claude directly:
"What directories do you have access to?"
Claude will list its working directory and any additional directories granted via --add-dir or additionalDirectories. This is useful for debugging why Claude says it "can't find" a file — often the directory simply hasn't been granted access.
Token Budgeting Tips for Large Codebases
Effective token management in large projects comes down to four habits:
1. Start sessions scoped to one module or feature at a time
Instead of "fix the auth system," try "fix the JWT refresh logic in src/auth/refresh.ts." The narrower the task, the less Claude needs to explore.
2. Use /clear between unrelated tasks
The /clear command resets context between tasks. If you just finished work on packages/ui and are now switching to packages/db, clear the session rather than carrying forward unrelated context.
3. Be explicit about file scope in your prompts
"Only look at files in src/api/routes/ — do not read anything outside that directory."
Claude Code respects this kind of explicit instruction. It avoids broad exploration and goes straight to the relevant files.
4. Use .claudeignore aggressively
Start by ignoring everything that is not source code — build output, node_modules, lock files, generated files, static assets. You can always temporarily remove a rule from .claudeignore if Claude genuinely needs to inspect a generated file. The default should be narrow, not wide.
Complete Setup: Turborepo + pnpm Example
Here is a complete working configuration for a typical Turborepo workspace:
Configuration details and flag availability reflect Claude Code as of June 2026. Check the official Claude Code docs for the latest settings reference before writing team runbooks.
