agents-md

agents-md

Claude Code plugin that loads AGENTS.md files — no per-project config needed.

Many AI coding tools use AGENTS.md for project-level instructions (Cursor, Codex, Windsurf, Continue.dev, etc.), but Claude Code only reads CLAUDE.md. This plugin bridges the gap so your cross-tool instructions just work.

Install

/plugin marketplace add hexsprite/claude-agents-md
/plugin install agents-md@hexsprite

Then start a Claude Code session in any project with an AGENTS.md file. Done.

Or test locally from a clone:

claude --plugin-dir /path/to/claude-agents-md

[!TIP] Use /reload-plugins inside a running session to pick up plugin changes without restarting.

How it works

For each AGENTS.md found in your project tree, the plugin:

1. Creates a CLAUDE.md symlink pointing at AGENTS.md in the same directory (falling back to a @AGENTS.md text file on platforms that can't symlink), or prepends @AGENTS.md to an existing CLAUDE.md that doesn't already have it
2. Injects the content via stdout for the current session (since Claude Code reads CLAUDE.md files before hooks fire on the first run)

This means:

• First session: Content is injected directly. The generated CLAUDE.md files take effect from the next session onward.
• Subsequent sessions: Claude Code natively reads the CLAUDE.md → @AGENTS.md imports. The plugin only injects truly new files.
• Mid-session: New AGENTS.md files (e.g., after a git pull) are detected and injected on your next prompt.

What gets created

If your project has an AGENTS.md but no CLAUDE.md:

CLAUDE.md -> AGENTS.md   (relative symlink created by plugin)
AGENTS.md                (your file, untouched)

The plugin prefers a symlink because it keeps a single source of truth — edits to AGENTS.md show up through CLAUDE.md with zero duplication, and build watchers that key off **/*.md won't see an extra real file.

If your platform can't create symlinks (Windows without Developer Mode, certain network mounts) or you opt out with CLAUDE_AGENTS_MD_NO_SYMLINK=1, the plugin falls back to a @AGENTS.md text file:

CLAUDE.md  (contains: @AGENTS.md)
AGENTS.md  (your file, untouched)

If a CLAUDE.md already exists, the import is prepended — the plugin never converts an existing file into a symlink:

@AGENTS.md
---

# Your existing CLAUDE.md content
...

[!NOTE] When the fallback text file is used, CLAUDE.md is a normal file you can edit, commit, or gitignore — you can add Claude-specific instructions below the @AGENTS.md import. When a symlink is used and you later want to add Claude-only content, replace the symlink with a text file and the plugin will leave it alone.

Should you commit CLAUDE.md?

With this plugin enabled, most projects should gitignore CLAUDE.md and commit only AGENTS.md. Reasons:

• The plugin regenerates CLAUDE.md on session start for anyone who has it installed — committing it is redundant.
• In symlink mode, CLAUDE.md is just a pointer to AGENTS.md. Committed symlinks behave inconsistently across platforms (Windows checkouts, some CI runners materialize them as text files containing the target path).
• Treating AGENTS.md as the single source of truth keeps cross-tool instructions (Cursor, Codex, Windsurf, Continue.dev, Claude) in one file.

Recommended .gitignore entry:

CLAUDE.md
**/CLAUDE.md

Exception: if you have Claude-specific instructions that shouldn't apply to other agents, use text-file mode (CLAUDE_AGENTS_MD_NO_SYMLINK=1 or let the plugin fall back) and commit the CLAUDE.md with your Claude-only content below the @AGENTS.md import. The plugin won't touch an existing CLAUDE.md beyond ensuring the import line is at the top.

Hook events

Event	When	Purpose
SessionStart	Session begins	Initial scan — link and inject all AGENTS.md files
UserPromptSubmit	Every prompt	Re-scan for new AGENTS.md files added mid-session

A temp file tracks which AGENTS.md files have been injected this session to avoid duplicates.

Scan strategy

The plugin picks the cheapest correct walker for the current tree, in order:

1. git ls-files when CLAUDE_PROJECT_DIR is inside a git working tree. Honors all .gitignore rules — including nested .gitignore files and negation patterns — and surfaces both tracked and untracked-but-not-ignored AGENTS.md files. Fast even on large monorepos because it reads the index instead of walking the tree.
2. fd when not in a git repo. Honors .gitignore by default and respects the canned exclude list below.
3. find as a final fallback when neither is available.

For the fd and find paths, the canned exclude list is node_modules .git vendor dist build .next .cache __pycache__ .venv.

Safety guards