Why isn't my CLAUDE.md @import loading?

/context

Memory files shows what loaded. If the importing file is not there, the import never had a chance.

Answer

An @path in CLAUDE.md inlines that file at launch, and it fails quietly for five documented reasons: the path sits inside backticks or a code block and is treated as text; it is relative to the wrong place, because relative paths resolve from the importing file, not the working directory; it is more than four hops deep; it points outside the working directory and you declined the approval dialog, which then never returns; or the importing file itself never loaded. Start with /context.

What it does

@path/to/file anywhere in a CLAUDE.md inlines that file at launch, alongside the file that references it. When the content is missing, one of five things happened, and each leaves a different trace.

The path is inside backticks or a code block

Import parsing skips code spans and fenced code blocks. That is the documented way to *mention* a path without importing it, so ` @README stays literal while @README` outside backticks imports the file. A path you quoted for tidiness is a path you switched off.

The path is relative to the wrong place

Relative paths resolve from the file containing the import, not from the working directory. A @docs/git-instructions.md written in packages/api/CLAUDE.md looks for packages/api/docs/git-instructions.md. The same line in the root CLAUDE.md looks at the root.

It is more than four hops deep

Imported files can import other files, to a maximum depth of four. A chain that grew as the team added layers stops expanding at the fifth file, with nothing said.

It points outside the working directory and you declined once

An import in a project-level file is external when its path resolves outside the working directory, the home-directory import being the usual case. The first time Claude Code meets external imports in a project it shows an approval dialog listing the files. Decline, and the imports stay disabled and the dialog does not appear again. The documentation does not describe a way to reverse that answer.

The dialog exists to protect you from files other people commit to a shared project. Imports written in your own user-scope files, ~/.claude/CLAUDE.md and ~/.claude/rules/, load without it.

The importing file never loaded

An import loads with the file that references it. A CLAUDE.md in a subdirectory loads only when Claude reads a file there, so its imports wait with it. A file that was excluded, oversized or declined takes its imports down too; why CLAUDE.md is ignored lists those cases.

How to check

Run /context and look under Memory files. If the importing CLAUDE.md is not listed, the problem is upstream of the import, and the fifth cause applies.

If it is listed, open it from /memory and read the import line as the parser does: is the @ inside backticks or a fenced block, does the relative path make sense from *this* file's directory, and how many files deep is the chain. An external path you cannot remember approving is the fourth cause.

How to fix it

Backticks. Take them off the path you want imported, and keep them on the paths you only mention.

Wrong base. Write the path from the importing file's directory, or use an absolute path.

Too deep. Flatten the chain: import the leaf directly from the file that needs it.

Declined dialog. Two ways around, both documented: move the file inside the working directory, where an import is not external and needs no approval, or import it from a user-scope file, ~/.claude/CLAUDE.md, which loads its imports without the dialog. For text that belongs to the project, paste it in.

File not loaded. Fix the file, not the import.

Example

Three lines, three different outcomes:

See @README for the project overview.
Do not edit `@package.json` by hand.
- git workflow @docs/git-instructions.md

The first and third import. The second mentions a file and imports nothing, which is what the backticks are for.

Personal instructions shared across worktrees, from the home directory:

# Individual Preferences
- @~/.claude/my-project-instructions.md

In a project file this one is external and asks once. In ~/.claude/CLAUDE.md it does not ask at all.

Common mistakes

Quoting the path for readability. Backticks mean "do not import" here.

Reading the relative path from the working directory. It is read from the importing file. Two identical lines in two files can point at two places.

Declining the dialog to "look at it later". There is no later; the imports stay off for that project. Approve, or move the file inside the working directory.

Assuming an import adds nothing to context. It inlines the whole file at launch. Content that should load only when relevant belongs in a path-scoped rule instead.