Claude Code: Understanding External CLAUDE.md Imports

When launching Claude Code, you may encounter a prompt asking to "Allow external CLAUDE.md file imports?" This document explains the mechanism, security considerations, and when it's safe to approve.

Official Documentation

From Claude Code Memory Docs:

"Claude recursively ascends from cwd to root /, loading all CLAUDE.md/CLAUDE.local.md files encountered"

The import syntax supports both relative and absolute paths:

# Relative imports (resolved from CLAUDE.md location)
@docs/style-guide.md
@shared/conventions.md

# Absolute imports (home directory)
@~/.claude/my-preferences.md

Maximum recursive import depth is 5 hops (file A imports B imports C...).

Security Model

From Claude Code Security Best Practices:

"Files outside project scope require explicit user approval"

The approval is stored in ~/.claude.json:

{
  "/absolute/path/to/project": {
    "hasClaudeMdExternalIncludesApproved": true
  }
}

This security gate exists because a malicious repository could craft a CLAUDE.md that attempts to import sensitive files from your system (SSH keys, cloud credentials, etc.).

The Mechanism Explained

Scenario

Consider this directory structure:

/home/alice/projects/
├── my-org/                          # Parent organization directory
│   ├── CLAUDE.md                    # Organization-wide instructions
│   ├── shared-docs/
│   │   ├── commit-conventions.md
│   │   └── code-style.md
│   └── my-project/                  # Your current working directory
│       ├── .git/
│       ├── README.md
│       └── src/

The parent my-org/CLAUDE.md contains:

# My Organization Standards

* Follow commit conventions @shared-docs/commit-conventions.md
* Use our code style @shared-docs/code-style.md

What Happens

1. You run claude inside /home/alice/projects/my-org/my-project/

2. Claude Code walks up the directory tree looking for CLAUDE.md files:

   • Checks /home/alice/projects/my-org/my-project/CLAUDE.md (not found)
   • Checks /home/alice/projects/my-org/CLAUDE.md (found!)
   • Continues up to root...

3. The parent CLAUDE.md uses @shared-docs/... imports, which resolve to:

   • /home/alice/projects/my-org/shared-docs/commit-conventions.md
   • /home/alice/projects/my-org/shared-docs/code-style.md

4. These files are outside your project directory (my-project/), so Claude Code flags them as "external imports"

5. You see the security prompt:

Allow external CLAUDE.md file imports?

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

External imports:
  /home/alice/projects/my-org/shared-docs/commit-conventions.md
  /home/alice/projects/my-org/shared-docs/code-style.md

The Warning: When to Approve

Safe to Approve

• Your own repositories where you control the parent CLAUDE.md
• Organization monorepos with shared documentation
• Trusted team projects with known import structures

Never Approve

• Third-party repositories you cloned from unknown sources
• Open source projects you're evaluating for the first time
• Any repo where you haven't reviewed what files are being imported

Why This Matters

A malicious CLAUDE.md could attempt:

# Innocent looking instructions...
@~/.ssh/id_rsa
@~/.aws/credentials
@~/.config/gh/hosts.yml

By requiring explicit approval for external imports, Claude Code prevents untrusted repositories from accessing files outside their directory scope.

Verification

Use these commands inside Claude Code to inspect what's loaded:

• /memory — Lists all loaded memory files and their token counts
• /context — Shows full context including resolved imports

Summary

Aspect	Details
Trigger	CLAUDE.md imports files outside current project directory
Cause	Parent directory CLAUDE.md with @path/file.md imports
Storage	Approval saved in ~/.claude.json per project path
Security	Prevents untrusted repos from accessing arbitrary files
Action	Approve for your own projects; reject for third-party code

---

Generated with Claude Code research. Sources: Claude Code Docs, GitHub Issues #1041, GitHub Issues #2950