Scope Claude Code to one package in a monorepo

In a 400k-line workspace, an unscoped agent burns half its context discovering packages it will never touch — then edits one it shouldn't. Run the agent from the package directory, deny writes outside it, and hand it the workspace-level commands it still needs.

Expected result

Claude works inside one package with read access to the rest of the workspace but write access only to its own package, and it runs affected-only builds and tests instead of workspace-wide ones.

Difficulty

Intermediate

Estimated time

~30 min

Version notes

The !(billing) glob needs Claude Code 2.4+; on 2.3.x enumerate sibling packages explicitly. Turborepo: swap nx commands for turbo run build test --filter=billing...[main].

Framework

Node.js

1. 01An Nx, Turborepo, or pnpm workspace with per-package directories
2. 02Claude Code 2.4+ (additionalDirectories + deny rules)
3. 03Package-level test/build targets that actually run in isolation

01

Start the session in the package, not the root

The working directory is the strongest scoping signal Claude gets — file search, git status, and its mental model all anchor there. Add the workspace root read-only so cross-package types still resolve.

cd packages/billing
claude --add-dir ../..

Copy

02

Deny writes outside the package

Read everything, write one place. Check this into packages/billing/.claude/settings.json so every session gets it. Deny beats allow here: new file paths appear constantly and you want the default to be no.

{
  "permissions": {
    "deny": [
      "Edit(../../packages/!(billing)/**)",
      "Edit(../../libs/**)",
      "Edit(../../tools/**)",
      "Edit(../../*.json)",
      "Write(../../packages/!(billing)/**)"
    ]
  }
}

Copy

03

Write a package-level CLAUDE.md with the boundary spelled out

The root CLAUDE.md describes the workspace; the package one describes the contract. Most important line: what to do when a change SEEMS to require touching another package (answer: stop and say so).

! Common failures

Claude edits a shared lib anyway via a Bash sed command

Edit/Write denies don't cover shell writes. Add Bash deny patterns for the obvious ones or, better, run the session in a worktree and let the diff check in step 5 be the hard gate — review catches what permissions miss.

TypeScript can't resolve imports from other packages in the session

You skipped --add-dir, so Claude can't read the workspace root. Re-launch with it; deny rules still prevent writes there.

nx affected reports everything affected

Your base is wrong (detached HEAD or shallow CI clone) or someone touched a root config. Check with npx nx affected:graph --base=main; if a root file is the trigger, that change should be its own human-owned PR.