[FEATURE] Claude Code memory traversal should respect git worktree boundaries

[dedsm]

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 using git worktrees, Claude Code's CLAUDE.md traversal loads memory files from both the current worktree AND the parent repository directory, causing a security warning:

This project's CLAUDE.md imports files outside the current working directory. Never allow this for third-party repositories.

The problem:

• Git worktrees are a common development pattern for working on multiple branches simultaneously
• Each worktree represents a different branch state with potentially different CLAUDE.md instructions
• Claude Code traverses up from CWD to filesystem root /, loading ALL CLAUDE.md files it encounters
• This causes the parent repo's CLAUDE.md to be loaded alongside the worktree's CLAUDE.md
• When the parent CLAUDE.md imports files (e.g., @./AGENTS.md), those paths resolve outside the worktree CWD
• This triggers a misleading security warning for the developer's own repository

Why this matters:

• Teams version-control CLAUDE.md files with branch-specific instructions
• Different feature branches may need different memory/coding guidelines
• The warning is technically correct but contextually wrong (it's not a third-party repo security issue)
• No current way to prevent Claude Code from traversing above the worktree/git boundary

Proposed Solution

Claude Code should stop memory file traversal at git boundaries, specifically:

Option 1: Auto-detect git worktree roots (Preferred)

When Claude Code encounters a .git file (not directory) during traversal, recognize it as a worktree and stop there:

# In a worktree, .git is a file pointing to the actual git directory
$ cat /path/to/worktree/.git
gitdir: /path/to/main-repo/.git/worktrees/feature-branch

Option 2: Stop at git repository root

When Claude Code encounters a .git/ directory, recognize it as a repository root and stop there.

Option 3: Configurable setting

Add user configuration to control traversal behavior:

{
  "memory.stopAtGitRoot": true,
  "memory.stopAtWorktreeRoot": true,
  "memory.maxTraversalDepth": 3
}

Alternative Solutions

Current workarounds (all have drawbacks):

1. Ignore the warning - Works but creates confusion and noise
2. Use CLAUDE.local.md in parent - Prevents version control of memory files
3. Don't use git worktrees - Severely limits developer workflow
4. Inline AGENTS.md into CLAUDE.md - Defeats modularity, makes diffs messy

None of these are acceptable for teams that use both worktrees and version-controlled memory files.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Scenario: Multi-branch development with branch-specific coding guidelines

1. Developer maintains a FastAPI project with CLAUDE.md containing team coding standards
2. They create a worktree for a new feature branch:

   git worktree add worktrees/api-v2-migration api-v2-migration
   cd worktrees/api-v2-migration

3. This branch modifies CLAUDE.md to add migration-specific instructions:

   @./AGENTS.md
   
   # API v2 Migration Guidelines
   - Use Pydantic v2 syntax only
   - Maintain backwards compatibility with v1 endpoints

4. Developer starts Claude Code in the worktree
5. Claude Code loads BOTH:
   • worktrees/api-v2-migration/CLAUDE.md (v2 migration instructions)
   • ../../CLAUDE.md (main branch instructions)
6. Warning appears: "imports files outside the current working directory"
7. Developer is confused - both files are from their own repo
8. Memory instructions conflict between branches, causing inconsistent AI behavior

Expected behavior: Claude Code should only load the worktree's CLAUDE.md, respecting the git worktree boundary.

Additional Context

Git worktree structure example:

/Users/dev/my-repo/                    # Main repo
├── .git/                              # Git directory
├── CLAUDE.md                          # Main branch instructions
├── AGENTS.md
└── worktrees/
    ├── feature-branch/                # Worktree (CWD)
    │   ├── .git                       # FILE pointing to main .git
    │   ├── CLAUDE.md                  # Feature branch instructions
    │   └── AGENTS.md
    └── bugfix-branch/                 # Another worktree
        ├── .git                       # FILE pointing to main .git
        ├── CLAUDE.md                  # Bugfix branch instructions
        └── AGENTS.md

Technical detection:

# Check if current directory is a worktree
if [ -f .git ]; then
  echo "This is a git worktree - stop traversal here"
else
  echo "Continue traversing up"
fi

Similar tools:

• Many language servers stop at git root for configuration
• Build tools (npm, cargo) stop at package/crate root

Impact: Affects any workflow combining:

• Git worktrees (parallel branch development)
• Version-controlled CLAUDE.md files (team standards)
• Branch-specific AI coding instructions (different features/refactors)

[paul-mothapo]

Indeed this is what I saw, Scripts and utilities need to either use paths relative to their current location or properly determine the full path to guarantee they function within the appropriate working directory.