Claude Code for Monorepos: Scale to Big Codebases

The monorepo challenge for AI coding tools

Most AI coding tools choke on large codebases. They either try to load everything into context and run out of tokens, or they miss critical cross-package dependencies because they only see the file you're editing. Monorepos amplify both problems: more files, more packages, more connections between them.

Claude Code handles monorepos differently. It doesn't try to understand your entire codebase at once. Instead, it uses targeted search (Grep, Glob), selective file reading, and project-scoped configuration to work effectively in codebases of any size. But it needs the right setup to do this well.

This guide covers everything you need to use Claude Code with monorepos and large codebases, from configuration to advanced patterns like ai coding large projects with parallel agents.

Project-scoped CLAUDE.md

The most important file for any Claude Code monorepo setup is CLAUDE.md. In a monorepo, you need multiple levels:

monorepo/
├── CLAUDE.md                    # Root: shared conventions
├── packages/
│   ├── api/
│   │   └── CLAUDE.md            # API-specific context
│   ├── web/
│   │   └── CLAUDE.md            # Frontend-specific context
│   └── shared/
│       └── CLAUDE.md            # Shared library context

Claude Code reads CLAUDE.md files hierarchically. When working in packages/api/, it reads both the root CLAUDE.md and packages/api/CLAUDE.md. This gives you layered context: global rules at the root, package-specific details in each subdirectory.

Your root CLAUDE.md should contain:

# Monorepo Architecture

Package manager: pnpm (workspace protocol)
Node version: 20.x (enforced via .nvmrc)

## Packages
- `packages/api`: Express API server (port 3001)
- `packages/web`: Next.js frontend (port 3000)
- `packages/shared`: Shared types, utils, validation schemas

## Cross-package rules
- Shared types live in `packages/shared/src/types/`
- Never import from another package's internal files
- All inter-package imports use workspace protocol
- Run `pnpm build:shared` after changing shared types

## Testing
- `pnpm test` runs all tests
- `pnpm test --filter=api` runs only API tests

Each package CLAUDE.md adds specifics: the API one describes routes and middleware, the web one describes components and state management, shared describes the type system. This way Claude always has relevant context without loading your entire codebase description.

.claudeignore: keeping context clean

Large codebases have large amounts of irrelevant content. Build artifacts, generated files, vendored dependencies, test fixtures, all noise that wastes context tokens.

.claudeignore works like .gitignore but specifically controls what Claude Code can see:

# Build outputs
dist/
build/
.next/
out/

# Generated files
*.generated.ts
*.d.ts.map
coverage/

# Large vendored content
vendor/
third_party/

# Package locks (too large, low value)
pnpm-lock.yaml
yarn.lock
package-lock.json

# Test fixtures
**/__fixtures__/large-*.json
**/test-data/snapshots/

For a claude code large codebase setup, .claudeignore is not optional. Without it, Claude's search tools return results from node_modules, build directories, and generated code, drowning the useful results in noise. Every monorepo should have this file configured before the first Claude Code session.

The impact is measurable. In a 50-package monorepo, a Grep search without .claudeignore might return 2,000 results. With it, you get 40 relevant results. Claude makes better decisions when it's not filtering through garbage.

Worktrees for isolated parallel work

Git worktrees give you multiple working directories from a single repository. For monorepos, this means you can run Claude Code in isolated contexts: one session works on the API, another on the frontend, without them interfering with each other.

# Create worktrees for parallel work
git worktree add ../myapp-api-feature feature/api-auth
git worktree add ../myapp-web-feature feature/web-dashboard

Now you can run Claude Code in each worktree independently:

# Terminal 1
cd ../myapp-api-feature
claude

# Terminal 2
cd ../myapp-web-feature
claude

Each session has its own branch, its own file state, and its own context. Changes in one worktree don't affect the other until you merge. This is the cleanest way to parallelize work on a monorepo: no conflicts, no confusion, no shared state.

For a deeper dive on this pattern, see our guide on Claude Code worktrees.

Subagent delegation for parallel tasks

Within a single Claude Code session, you can delegate work to subagents, independent Claude instances that handle specific tasks and report back.

This is powerful for monorepo operations that span multiple packages:

# .claude/commands/cross-package-refactor.md
---
description: Refactor a type across all packages
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash(pnpm:*)
  - Bash(npx tsc:*)
---

Refactor the specified type across all packages:

1. Find all usages with Grep
2. Delegate to subagents:
   - Agent 1: Update shared type definition
   - Agent 2: Update API consumers
   - Agent 3: Update web consumers
3. Run type checking across all packages
4. Run tests across all packages

Subagents inherit the parent's permissions but run in their own context. Each one focuses on a specific package or task, then returns results to the parent session for verification. This is how you handle cross-cutting changes in a large codebase without overwhelming a single context window.

Context management strategies

The biggest challenge with ai coding large projects is context. Claude Code has a finite context window, and a monorepo can easily exhaust it if you're not intentional about what you load.

Strategy 1: Package-focused sessions

Work on one package at a time. Start your session by telling Claude which package you're focused on:

I'm working in packages/api today. Focus on this package
unless I specifically mention cross-package work.

This keeps Claude from proactively exploring other packages and consuming context on irrelevant code.

Strategy 2: Retrieval map in CLAUDE.md

Tell Claude where to find things instead of making it search:

## Retrieval Map
| You need... | Look in... |
|---|---|
| API route definitions | `packages/api/src/routes/` |
| Database schemas | `packages/api/src/db/schema.ts` |
| Shared types | `packages/shared/src/types/` |
| Component library | `packages/web/src/components/ui/` |
| E2E tests | `tests/e2e/` |
| CI configuration | `.github/workflows/` |

This eliminates exploratory searches that waste context. Claude goes directly to the right file instead of Grepping across 50 packages to find it.

Strategy 3: Aggressive /compact usage

In a monorepo session, you'll hit context limits faster because more files get loaded. Use /compact proactively, don't wait for the warning. After completing a task in one package, compact before moving to another.

For extended sessions, use a /safe-clear command that preserves your progress before resetting context. The context window guide covers this in depth.

Strategy 4: Task-scoped file reading

Never ask Claude to "look at the whole API package." Instead, point it at specific files:

Read packages/api/src/routes/auth.ts and
packages/api/src/middleware/validate.ts.
I need to add rate limiting to the auth routes.

The more specific your requests, the less context gets consumed on irrelevant code. This discipline matters more in monorepos than anywhere else.

Monorepo-specific commands

Build commands that understand your monorepo's structure:

/scope: Set package focus

---
description: Set working scope to a specific package
argument-hint: "[package-name]"
---

Set the working scope to: $ARGUMENTS

1. Read that package's CLAUDE.md
2. Read the package.json for dependencies
3. Summarize the package's purpose and key files
4. All subsequent work should focus on this package unless told otherwise

/cross-check: Verify cross-package consistency

---
description: Check cross-package type and dependency consistency
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(pnpm:*)
  - Bash(npx tsc:*)
---

Verify cross-package consistency:
1. Run `pnpm tsc --noEmit` across all packages
2. Check that shared type exports match consumer imports
3. Verify no circular dependencies between packages
4. Report any inconsistencies with file:line references

/test-affected: Only test what changed

---
description: Run tests only for affected packages
allowed-tools:
  - Bash(git:*)
  - Bash(pnpm:*)
---

1. Run `git diff --name-only HEAD~1` to find changed files
2. Map changed files to affected packages
3. Include packages that depend on changed packages
4. Run `pnpm test --filter={affected}` for each

What doesn't work

Asking Claude to understand your entire monorepo at once. No AI tool can hold 500 packages in context simultaneously. Work package-by-package with cross-references.

Skipping .claudeignore. Generated files and build artifacts will pollute every search result and waste context tokens on noise.

Running long builds inside Claude sessions. A 10-minute pnpm build blocks your session. Run long commands in a separate terminal and tell Claude the result.

Assuming Claude remembers cross-session work. Each session starts fresh. Use memory systems to persist important context between sessions, especially for ongoing monorepo refactors.

FAQ

How large of a codebase can Claude Code handle?

There's no hard limit on repository size. Claude Code doesn't load your entire codebase into memory: it searches and reads files on demand. Teams use it successfully on repos with millions of lines of code. The constraint is context window per session, which is managed through .claudeignore, focused sessions, and regular compaction.

Should I use one CLAUDE.md or many in a monorepo?

Both. Use a root CLAUDE.md for shared conventions (package manager, testing strategy, code style) and per-package CLAUDE.md files for package-specific context (API routes, component patterns, database schemas). Claude reads them hierarchically, so there's no duplication needed.

Can Claude Code handle cross-package refactors?

Yes, but break them into steps. Use Grep to find all usages across packages, plan the changes, then execute package by package. For large refactors, subagent delegation lets you parallelize across packages. Always run type checking and tests across the full monorepo after cross-package changes.

---

Building a monorepo setup from scratch takes hours of trial and error. Claudify ships with monorepo-ready configuration: hierarchical CLAUDE.md templates, .claudeignore presets, cross-package commands, and context management patterns tested on real production monorepos. One command: npx create-claudify.