What is the syntax for importing a file into CLAUDE.md?

Write @ followed by the path, anywhere in the file: @docs/git-instructions.md or See @README for an overview. Relative paths resolve from the file containing the import, not your working directory.

How deep can CLAUDE.md imports go?

Four hops. An imported file can import another file, up to a maximum depth of four.

Do imports reduce how much context CLAUDE.md uses?

No. Imported files load together with the CLAUDE.md that imports them, so the context cost is the same as one long file. To save context, use .claude/rules/ with a paths field, or a skill, which load only when needed.

How do I mention a path in CLAUDE.md without importing it?

Wrap it in backticks. Import parsing skips Markdown code spans and fenced code blocks, so `@README` stays literal text while @README outside backticks imports the file.

Why isn't my CLAUDE.md import loading?

Common causes: you declined the external import dialog for that project, the path has a space with no backslash before it, the path is wrapped in quotes, or the line sits inside backticks or a code block. A path resolves from the importing file too.

How to import other files into CLAUDE.md

To import a file into CLAUDE.md, write @ followed by its path anywhere in the file, such as @docs/git-instructions.md. Relative paths resolve from the file containing the import, absolute and ~/ paths also work, and imports can nest up to four hops. The imported file loads into context alongside the CLAUDE.md, so it costs the same context.

The syntax

The @path can stand on its own line or sit inside a sentence or a list item:

See @README for project overview and @package.json for available npm commands.

# Additional instructions
- git workflow @docs/git-instructions.md
- @~/.claude/my-project-instructions.md

The path rules

You write	What happens
`@docs/api.md`	Resolves from the folder of the file containing the import, not your working directory
`@/Users/you/shared/api.md`	An absolute path, which works
`@~/.claude/my-rules.md`	A file in your home folder, which works
`@Design\ Docs/api.md`	A space escaped with a backslash, which works
`@Design Docs/api.md`	The path ends at the first space, even on a line of its own
`@"Design Docs/api.md"`	Not imported. A quoted path never is, with or without backslashes
`@README`	Literal text. Code spans and fenced code blocks are skipped

Imported files can import other files, up to a maximum depth of four hops. The relative rule applies at each hop, so a path in an imported file resolves from that file's folder.

Imports from outside your project need approval

In a project-level file, an import is external when its path resolves outside your working directory. The first time Claude Code meets external imports in a project, a dialog lists the files. If you decline, the imports stay disabled and the dialog doesn't appear again.

The dialog protects you from files other people commit to a shared project. Imports in your own ~/.claude/CLAUDE.md and ~/.claude/rules/ load without it, except in Cowork sessions, which skip imports that resolve outside the session's working directory.

What imports don't do

They don't save context. Imported files load with the CLAUDE.md that references them. Splitting a 600-line file into six imports makes it easier to read and costs the same. See how long CLAUDE.md should be.
They don't escape the length warning. Each CLAUDE.md, rules file and import counts as a separate file, and Claude Code warns when files add up past a combined limit at session start.
They don't override anything. Imported text joins the same context as every other file. If it contradicts another file, Claude may pick either one.

Import, rule, or skill?

Use	Loads	Good for
`@path` import	With the file that imports it	Reusing a file that already exists, such as a README or AGENTS.md
`.claude/rules/`	At launch, or on matching files with `paths`	Instructions for one part of the codebase
Skill	When invoked or relevant	Multi-step procedures and long reference material

Three common uses

Reuse AGENTS.md

Put @AGENTS.md at the top of a CLAUDE.md beside it. Claude reads the imported file first, then the rest. See whether Claude Code reads AGENTS.md.

Personal notes across worktrees

A gitignored CLAUDE.local.md exists only in the worktree where you created it. An import from your home folder reaches all of them.

One standards file for several repos

Add the same import line to each repo. See how to share CLAUDE.md across projects for the other options.

Check that an import loaded

Run /context all and read the Memory files list.
If you never saw the approval dialog for an external path, or declined it, that import is off for the project.
For a full record, add an InstructionsLoaded hook. It fires for each imported file with load_reason set to include.

On-demand files have one more limit. An import from a subfolder CLAUDE.md counts toward a per-file size limit, 40,000 characters in a 200K context window, and Claude gets only the start of a file over it.

Rulebook, the Mac app we are building, shows each CLAUDE.md as you wrote it. It doesn't expand imports, so an @path line appears as text.

Questions

What is the syntax for importing a file into CLAUDE.md?: Write @ followed by the path, anywhere in the file: @docs/git-instructions.md or See @README for an overview. Relative paths resolve from the file containing the import, not your working directory.
How deep can CLAUDE.md imports go?: Four hops. An imported file can import another file, up to a maximum depth of four.
Do imports reduce how much context CLAUDE.md uses?: No. Imported files load together with the CLAUDE.md that imports them, so the context cost is the same as one long file. To save context, use .claude/rules/ with a paths field, or a skill, which load only when needed.
How do I mention a path in CLAUDE.md without importing it?: Wrap it in backticks. Import parsing skips Markdown code spans and fenced code blocks, so `@README` stays literal text while @README outside backticks imports the file.
Why isn't my CLAUDE.md import loading?: Common causes: you declined the external import dialog for that project, the path has a space with no backslash before it, the path is wrapped in quotes, or the line sits inside backticks or a code block. A path resolves from the importing file too.

Rulebook for Mac

Rulebook is a native Mac app we are building for these files. It shows every CLAUDE.md and settings.json level side by side, lets you drag a rule from one file to another, and edits permissions without hand-written JSON. See the features.

Rulebook is in development and not available yet.

Email us about the launch