[FEATURE] Provide way to exclude parent CLAUDE.md files from auto-loading in subdirectories

[alex-klyuev]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When working in a subdirectory of a large monorepo, Claude Code recursively loads all parent CLAUDE.md files into context with no way to opt out. This causes large irrelevant documentation to consume context tokens unnecessarily, thereby degrading performance and usefulness of Claude Code.

Per the memory documentation:

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds.

This behavior is problematic for monorepos with multiple teams/tech stacks where parent-level documentation is irrelevant to subdirectory work.

Example Scenario

monorepo/
├── CLAUDE.md (40k+ chars - Go microservices docs)
├── services/
│   ├── ui-app/          # Frontend app
│   │   ├── CLAUDE.md    # Frontend-specific docs
│   │   └── packages/
│   │       └── app/     # <- Working directory
│   │           └── CLAUDE.md

Currently loaded: All 3 CLAUDE.md files, including backend Go service documentation that's irrelevant to the working directory.

Desired: Only load the 2 UI-related CLAUDE.md files, excluding the one in root directory.

Proposed Solution

The ideal solution is some sort of setting or configuration knob to customize CLAUDE.md loading, that can be checked in to main repo (something akin to a .gitignore).

Alternative Solutions

Tried denying permission to read from CLAUDE.md in .claude/settings.json - this doesn't work as this controls tool uses by Claude Code but not auto-loading CLAUDE.md into the context window.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

No response

Additional Context

Related issues:

• Context Duplication in Worktrees Causing Excessive Context Consumption #3232 - Context duplication in worktrees (closed as not planned)
• [Feature Request] Add option to conditionally skip loading ~/.claude/CLAUDE.md based on working directory #15332 - Conditionally skip ~/.claude/CLAUDE.md based on working directory (closed as duplicate of Context Duplication in Worktrees Causing Excessive Context Consumption #3232)

[github-actions]

Found 3 possible duplicate issues:

1. [MODEL] Agents/scales recursively search parent directories - no option to disable #19458
2. [FEATURE] Claude Code memory traversal should respect git worktree boundaries #16600
3. [Feature Request] Add option to conditionally skip loading ~/.claude/CLAUDE.md based on working directory #15332

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[overallmedia]

+1 on this — this is causing real issues in our workflow.
We have a project structure like dev-env/src/shop/ where shop/ is a fully independent git repository with its own CLAUDE.md, AGENT.md, .claude/settings.local.json, etc.
When launching Claude Code from shop/, it traverses up to dev-env/ and loads directives from there that are completely unrelated to the current project. This causes confusion, conflicting instructions, and potential errors — Claude ends up mixing context from different projects.
The presence of a .git directory in shop/ should be a natural boundary, but it's completely ignored.
Suggested solutions (any of these would help):

A flag in .claude/settings.local.json like "disableParentTraversal": true
Respect .git boundaries by default — if the cwd has its own .git, stop traversing upward
A CLAUDE.md directive like # ROOT that tells Claude Code "this is the top level, don't go higher"

This is critical for anyone working in multi-project structures (monorepos, dev environments with multiple independent repos nested under a common folder). Without a way to control this, the memory system actively works against project isolation.

[robertfw]

Needing this for similar reasons, we've got a repo for setting up multiple workspaces that can share infrastructure (e.g, share one postgres instance across multiple worktrees, each with their own DB). there's a CLAUDE.md in that repo root for working on the setup itself. the workspaces live in a gitignored folder within that repo - so when you're working within the workspace, we're ending up loading up irrelevant context from the infra sharing repo.

[PabloLION]

+1 to the problem statement, but I think the best fix is configurable resolution policy rather than only exclusions.

claudeMdExcludes helps, but in monorepos/worktrees it can become ongoing maintenance. A frontmatter policy would be cleaner and deterministic:

---
memory:
  discovery_mode: repo      # repo | filesystem | manual
  ancestor_traversal: false
  local_file: CLAUDE.local.md
  precedence: [org, local, nested, repo, user]
---

Key point: some users need parent inheritance, others need strict project isolation. A mode switch in the resolver supports both without breaking either.

[tarikyalcinkaya]

+1 on this. Same problem in a nested project structure:

my-org/CLAUDE.md              (3K)
my-org/my-project/CLAUDE.md   (59K)
my-org/my-project/apps/web/   (cwd)

Three issues caused by this:

1. The 59K parent CLAUDE.md consumes significant context window space, triggers the performance warning (>40K chars), and accelerates context compaction — reducing effective working memory for actual tasks.
2. /memory list becomes cluttered with unrelated parent CLAUDE.md files, making it harder to identify which memory is relevant.
3. Irrelevant parent memories can mislead Claude, causing it to follow instructions meant for a different project scope.

Current workaround is renaming the parent CLAUDE.md to a different name and using @import when needed — works but is fragile.