Omniscio

OmniscioGuidesClaude Code in a monorepo

Claude Code in a monorepo

A monorepo does not break Claude Code, but the defaults tuned for small projects start to cost. Every instruction that loads and every file it reads competes for the same context window, whether or not the task touches it.

This page covers the settings Anthropic documents for large trees: where to start a session, nested CLAUDE.md files, exclusions, deny rules, sparse worktrees, access across packages, and per-package skills.

Last checked against Anthropic's monorepo documentation on November 17, 2026. By the Omniscio team. Updated .

On this page

These settings layer rather than replace each other, so apply whichever fit your repository. The CLAUDE.md guide covers how those files load in a single-project repo.

Start from the right directory

Where you launch claude decides three things at once: which files Claude can read and edit without another permission grant, which CLAUDE.md files load at startup, and which project settings apply.

From the repository root, Claude can reach every file, and only the root CLAUDE.md loads at launch, with subdirectory files loading on demand. That suits a task spanning several packages.

From a subdirectory, Claude reaches that subtree until you grant more, and that directory's CLAUDE.md plus every ancestor's loads at launch. That suits work scoped to one package.

One asymmetry catches people out. Project settings in .claude/settings.json are not inherited from parent directories the way CLAUDE.md files are, so a package's settings file has to be self-contained.

Source: the choose-where-to-start-Claude section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Layer CLAUDE.md by directory

A single root CLAUDE.md drifts one of two ways in a large tree: it grows to cover every subsystem's conventions and costs context on every task, or it stays so generic it helps nobody.

Splitting it by directory fixes both. Claude Code loads every CLAUDE.md from the working directory and its parents at launch, then loads each subdirectory's file on demand, so a task sees the repository-wide rules plus that area's conventions.

Anthropic's split is two levels. The root file holds what applies everywhere, such as commit conventions and which commands to run for scripts. Each package's file holds the conventions specific to its stack, and each directory's owner maintains its own.

Commit both, so teammates inherit them. To confirm what actually loaded, run /context all and read the list under Memory files.

There is an alternative worth knowing: path-scoped rules under .claude/rules/ load when Claude touches a matching file, keeping all conventions in one place instead of one file per package.

Sources: the layer-CLAUDE-md-files-by-directory and choose-between-per-directory-claude-md-and-path-scoped-rules sections of Anthropic's monorepo and large codebase page, read November 17, 2026.

Exclude what you never touch

Started from the root, every subdirectory's CLAUDE.md can load on demand during a session. claudeMdExcludes skips specific files by path or glob, so another team's package, legacy code or a vendored subtree never loads. This is the repository's .claude/settings.local.json:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Patterns are glob syntax matched against absolute paths, so a relative-style pattern needs to start with **/ to match anywhere in the tree. **/packages/*/CLAUDE.md excludes every package's file while keeping the root one.

The list is static, not a per-task switch. To work in one package today and another tomorrow, start Claude from that package's directory rather than editing exclusions each time.

Put it in .claude/settings.local.json when the exclusion is only yours, and remember to add that file to your gitignore, because a hand-created settings file is not added for you. To check which files still load, run /context all and read Memory files.

Source: the exclude-irrelevant-claude-md-files section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Block reads of generated code

Content searches respect .gitignore by default, so node_modules/, dist/ and build/ stay out of results with no setup. Checked-in generated code and vendored SDKs are the gap, and Read deny rules in .claude/settings.json close it.

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

The directory patterns end in /**/* rather than /** on purpose, so each rule covers what is inside the directory but not the directory itself. Claude can still list it or change into it.

Deny rules also cover file commands in Bash that Claude Code recognises, such as cat, head and grep, when a denied path is an argument. They do not cover a subprocess that opens the file itself.

Where the rule lives decides who it applies to: a committed .claude/settings.json covers everyone in the repository, .claude/settings.local.json covers you, and managed settings cover every session and cannot be overridden.

Source: the block-reads-of-generated-and-vendored-code section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Smaller worktrees

The --worktree flag starts a session in a new git worktree, checked out in full by default. In a large repository that is slow and eats disk, and worktree.sparsePaths in .claude/settings.json narrows it.

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Paths are relative to the repository root whichever directory you start from. Root-level files such as package.json and lock files always come along; root-level directories do not, which is why .claude is listed here.

Pair it with symlinkDirectories to stop duplicating large folders. Listing node_modules there creates a symlink from each worktree back to the main checkout's copy instead of a second one.

Sparse checkout needs git to enable extensions.worktreeConfig in the shared config while such a worktree exists. Anthropic states Claude Code removes that entry after the last worktree if it added it.

The worktrees guide covers the flag itself and what a worktree shares with the main checkout.

Source: the check-out-only-the-directories-you-need section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Reach a sibling package

Started from packages/api/, Claude cannot edit packages/shared/ without a grant. Two settings give it: permissions.additionalDirectories in a settings file, or the --add-dir flag at launch.

claude --add-dir ../shared

How you added the directory decides what else comes with it. additionalDirectories grants file access only and loads neither CLAUDE.md nor skills. --add-dir and the /add-dir command load the directory's skills, and load its CLAUDE.md and rules only when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set.

Relative paths resolve against the directory you start Claude from, so ../shared means the sibling. Commit the setting for paths everyone in that area needs, and use your local settings file or the flag for a one-off.

Source: the grant-access-across-packages-or-repositories section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Skills per directory

Any subdirectory can hold skills for its own stack, in .claude/skills/ inside it, committed with that area's code. Started from the root, a skill loads when Claude touches files in that directory.

That is lighter than CLAUDE.md for procedures, because Claude reads every discovered skill's name and description and loads the full file only when the task calls for it.

The catch is volume. Started from the root, skills accumulate from every subdirectory Claude touches, and Anthropic notes that when there are many, some descriptions are cut short, which can strip the keywords Claude uses to decide whether a skill applies.

Keep descriptions short and lead with the words a request would contain. Package skills many directories share as a plugin instead, which keeps them in one place with their own version history.

The skills guide covers writing a SKILL.md itself.

Sources: the add-per-directory-skills and keep-skills-discoverable sections of Anthropic's monorepo and large codebase page, read November 17, 2026.

A change that spans packages

Configuration controls what Claude sees. When one change touches several packages, such as a shared type and every call site, how you sequence it decides the result.

Anthropic gives two techniques. Hand the whole change over in one session, so the decisions behind each edit stay consistent instead of being re-derived per package.

And plan before editing. In plan mode Claude writes the plan to a file, and Claude Code re-injects that file after each compaction, so the plan survives where conversation history may not.

The plan mode guide covers the approval flow, and the context window guide covers what compaction keeps.

Source: the scope-and-plan-changes-that-span-packages section of Anthropic's monorepo and large codebase page, read November 17, 2026.

Running several sessions at once

A monorepo is where one session per package stops being enough. Omniscio, the desktop app we make for running many Claude Code sessions at once, puts those sessions in one window with a sidebar, and each one starts in the directory you choose.

It is free to use with up to 8 projects. Pro is $20/month or $192/year, and neither plan includes an AI allowance.

The multi-session guide compares the ways to run more than one, and running many coding agents at once covers what changes at five and above.

Where these answers come from

  • Anthropic, Set up Claude Code in a monorepo or large codebase: where to start, the settings table, per-directory CLAUDE.md, claudeMdExcludes, Read deny rules, code intelligence, worktree sparsePaths and symlinkDirectories, additionalDirectories and --add-dir, per-directory skills, and planning across packages. Read November 17, 2026.
  • Anthropic, Settings: which settings file each scope reads, and project settings not being inherited. Read November 17, 2026.

Anthropic's page changes often. Read it again before trusting an older copy.

Common questions

How do I set up Claude Code in a monorepo?

Start Claude from the package you are working on instead of the repository root. Then split instructions into a root CLAUDE.md for rules that apply everywhere and one CLAUDE.md per package for its own conventions, and add Read deny rules for generated or vendored code.

Where should I start Claude Code in a monorepo?

From the repository root, every file is readable and only the root CLAUDE.md loads at launch, with subdirectory files loading on demand. From a subdirectory, file access is that subtree until you grant more, and that directory's CLAUDE.md plus every ancestor's loads at launch.

How do I stop Claude Code loading another team's CLAUDE.md?

Use the claudeMdExcludes setting with a path or glob, such as "**/packages/web/**". It skips every CLAUDE.md and rules file under that path. The list is static, so to focus on a different package tomorrow, start Claude from that package's directory instead.

How do I give Claude Code access to a sibling package?

Add the directory to permissions.additionalDirectories in the settings file, or pass --add-dir when you start Claude. A directory added with --add-dir or /add-dir also loads its skills; its CLAUDE.md and rules load only when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set.

How do I make Claude Code worktrees smaller in a large repo?

Set worktree.sparsePaths to the directories the work needs, so git checks out only those plus root-level files. Pair it with worktree.symlinkDirectories to symlink node_modules back to the main checkout instead of duplicating it.

How do I stop Claude Code reading build output?

Paths already in .gitignore stay out of searches by default. For checked-in generated or vendored code, add Read deny rules such as Read(./**/dist/**/*) to permissions.deny in .claude/settings.json so Claude cannot open those files.

One session per package, one window to watch them

Omniscio runs many Claude Code sessions side by side, each starting in its own directory. The features page lists what it does today.