Skip to content
Book a callSkip the hiring grind

Day 46 of 52 · about 20 min · Context · Bonus

Set up Claude Code in a monorepo

In a big repository, Claude needs to know where to look. Otherwise it spends your context on other teams’ code and on instructions that have nothing to do with the package you are changing.

You’ll finish with

  • A root CLAUDE.md plus one per package, each loading only where you work
  • Deny rules that keep build output and vendored code out of Claude’s reads
  • A sibling package added with --add-dir when a change spans two

You’ll need

  • A monorepo or large repository where you can add files
  • Day 9 (deny rules) and Day 21 (path-scoped rules)
Start from the practice project as of Day 35 (.zip, 46 KB)

Before you start

Tell us about your setup and the steps change to fit it. Your answers stay in this browser, and you can change them at any time.

Which system are you on?

Commands differ between systems. Pick the one you’ll run Claude Code on.

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

0 of 4 steps done0%

  1. Step 1 of 4: Choose where to start Claude

    Where you run claude decides what Claude can read and which instructions load.

    Start at the root

    • Every file is in reach
    • Root CLAUDE.md at launch; package files load on demand
    • For tasks that span packages

    Start in a package

    • That package only, until you add more
    • Its CLAUDE.md plus every parent folder’s
    • For work inside one package
    Pick per task. To focus on one package, start in it.

    Check it worked

    You know which folder you will start from for your next task.

  2. Step 2 of 4: Give each package its own CLAUDE.md

    Keep repository-wide rules at the root and package rules beside their code.

    For example, commit conventions go in the root file and each package’s stack in its own. Prefer one central place? Use path-scoped rules in .claude/rules/ instead, as on Day 21.

    monorepo/

    • CLAUDE.mdRules for every package
    • folder packages
      • folder api
        • CLAUDE.mdNewAPI conventions only
      • folder web
        • CLAUDE.mdNewFrontend conventions only
      • folder shared
        • CLAUDE.mdNew
    The layout the docs use. Swap in your own packages or subsystems.

    Check it worked

    Start Claude in packages/api/ and run /context. Memory files lists the root and api CLAUDE.md, and nothing from web.

  3. Step 3 of 4: Keep Claude out of generated code

    Deny reads of build output and skip CLAUDE.md files you never need.

    Folders in .gitignore, like node_modules, already stay out of Claude’s searches. For checked-in build output or vendored code, add Read deny rules. A Bash grep -r over those folders still sees them.

    .claude/settings.json
    permissions.deny: ["Read(./**/dist/**/*)", "Read(./**/vendor/**/*)"]
    Blocks the files inside. Claude can still list the folders.
    claudeMdExcludes: ["**/packages/legacy-*/**"]
    Skips those packages’ CLAUDE.md and rules when you start at the root.
    Settings aren’t inherited from parent folders, so start-from folders need their own copy.

    Check it worked

    Save this at the repository root and start Claude there: /permissions lists both deny rules.

  4. Step 4 of 4: Reach a sibling package

    Add another folder when a change spans packages.
    Terminal

    Run: claude --add-dir ../shared

    What happens: Started in packages/api/, Claude can now read and edit packages/shared/ too.

    What happens: Mid-session, /add-dir ../web does the same.

    Added folders give file access. Their CLAUDE.md loads only with an extra environment variable.

    Check it worked

    Ask Claude to read a file in ../shared. It opens without a prompt about leaving the working folder.

Finish · 4 of 4 steps to go

Claude reads the part you work on

Start where the task lives and add folders only when a change crosses packages.

What you’ll have checked

  • /context shows the root and package CLAUDE.md only
  • Build output and vendored code are on the deny list
  • --add-dir gave access to a sibling package

Lesson updates by email

Get lesson updates by email

Leave your email and we’ll tell you when we add or update a lesson.

We’ll email you when we add or update a lesson. We use your email only for this. Privacy policy

Claude Code for your team

Want Claude Code set up across your team?

HorizonLux sets up and repairs Claude Code for teams: CLAUDE.md rules, hooks that enforce them and reviewed MCP servers. Book a free call to talk it through.

Book a free call Claude Code agency

Related

Free tool

Token Counter

How we build

AI software factory

Questions

Questions about Day 46

Can a package settings file build on the root one?

No. Claude Code reads `.claude/settings.json` only from the folder you start in, so each one must be complete.

Sources

Checked against the official Claude Code docs on .

Independent resource, not affiliated with Anthropic. HorizonLux wrote this lesson; Claude Code is made by Anthropic.