⭐️ YOUR INPUT NEEDED: syntax for including CLAUDE.md files
Status Fixed / completed
Maintainer reply ✓ Yes — bcherny
Activity 8 comments · opened May 7, 2025 · closed May 8, 2025
💡 Likely answer: A maintainer (bcherny, collaborator)
responded on this thread — see the highlighted reply below.
Hey everyone!
We're working on an update that lets you interlink CLAUDE.md files. A CLAUDE.md can link other Markdown and text files (and in the future, URLs), which will be automatically pulled into context when you start Claude Code.
This will also work for local commands:
# .claude/commands/foo.md
Read @foo.py and @bar.py, then fetch issues from @https://github.com/foo/bar issues, then...
> /project:fooWe are considering two syntaxes for including files, and need your input:
- @-mention:
@path/to/file-- react with a ❤ if you prefer this - Markdown link with @:
[@Description](path/to/file)-- react with a 🚀
Which do you prefer? Please vote!
8 Comments
You could also consider supporting snippet/include syntax that's compatible with mkdocs, as there is prior art in this area.
https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
That would be nice for people who already have user guides or devdocs that use Markdown in this way.
BTW, I trust you that this is useful but why can't Claude just ask to read a file if it finds a reference and believes it's interesting? Is "forcing" the context this way sometimes going to be counterproductive?
What I have been trying to get working is a common directory of instructions for the various AI tools that I use (eg,
$HOME/Documents/AI) that I can refer to from within the user-level, per-tool configuration. In other words, being able to use something like the following in my user-level claude.md file would be awesome:A few of us have been fighting with the sudden proliferation of tool configuration files in our project environments especially since many of them are duplicative. Even more so when I use the same code guidelines and CI workflows across _many_ projects. I would love to describe them once and be done with it.
I love using whatever Markdown does here by default, and your
@syntax to essentially declare that the link is "included" feels elegant to me.I was originally thinking of this as an "embed" or "include", which made me think of Obsidian and Quarto embeds syntax, but I see why you'd want to go the "This is just a hyperlink with a special character in the description" route. I think that's the most descriptive and least "new-syntax" approach.
Thanks for the feedback! @ it is. Coming soon.
Is there any update or timeline regarding this feature?
One thing I find really helpful is checking claude.md into my repo so everyone has the same general instructions.
I’d also like to be able to create a claude.personal.md file that I could add to .gitignore and link to from claude.md. That way, if someone doesn’t have their own claude.personal.md, it just skips it without breaking anything.
I can see different setups for different projects. For example, I like to have commits come from me but have a GitHub bot open the pull requests. That way, I can review them as myself without approving my own pull requests. It also lets me send feedback back to Claude through the pull request itself.
Right now, I often have to remember to manually @ mention the file when I start up Claude, or it won’t pick it up. Having this built-in would make things much smoother.
Really appreciate the work on this. Looking forward to using it!
FYI - Here is doc on how to use the
@file import syntax, which is now implemented: https://docs.anthropic.com/en/docs/claude-code/memory#claude-md-importsThis issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.