agents-md, a Claude Code AGENTS.md mod: load AGENTS.md as project instructions
Loads AGENTS.md files as project instructions, the way Claude Code loads CLAUDE.md, with four modes set in /config.
Permissions
- Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- tested with
- v2.1.310
- last tested
- requires
- Claude Code ≥ 2.1.287
- surfaces
- none
- source
- Anthropic (anthropics)
Install inside Claude Code:
git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-mdWhat does this mod do?
agents-md is a mod by Anthropic (anthropics/claude-code) that gives Claude Code AGENTS.md support. Many repositories keep their agent instructions in AGENTS.md, while Claude Code reads CLAUDE.md. This mod hands AGENTS.md files to Claude Code as project instruction files, so the model sees them in the same place and with the same framing as a CLAUDE.md.
One option, instructionFiles, picks what is loaded:
claude-md: onlyCLAUDE.md, as Claude Code does today. The mod adds nothing.claude-md-or-agents-md(the default): a project with noCLAUDE.mdof its own gets itsAGENTS.mdfiles instead.claude-md-and-agents-md: everyAGENTS.mdis loaded next toCLAUDE.md.managed-only: the project's and your own instruction files are dropped; the organization's managedCLAUDE.mdand memory stay.
Files are found from the filesystem root down to the working directory, and both AGENTS.md and .claude/AGENTS.md count. When Claude reads a file in a subdirectory, that directory's AGENTS.md is attached to the result, as Claude Code does for a nested CLAUDE.md. The mod draws nothing on screen; its effect is in what the model knows.
Demo
The recording starts Claude Code with the mod loaded in the small demo project. Before the clip starts, a hidden setup line writes a short AGENTS.md into that project (two rules: commit messages start with a ticket id like DEMO-123, and run npm test before every commit). The project has no CLAUDE.md. In the clip we ask: "Without reading any file: what does my AGENTS.md say about commit messages? One sentence." Claude answers that commit messages start with the ticket id, like DEMO-123, in about two seconds and with no tool call, because the file was already in its context.
Install
Use any of the methods in the install block; they install from the anthropics/claude-code repository. The repository has no marketplace.json that lists this plugin, so the block uses the repository as the source. The default mode needs no setup: start a session in a project that has an AGENTS.md and no CLAUDE.md.
$ install agents-md
Requires Claude Code ≥ 2.1.287
Installs from the author's own marketplace: anthropics/claude-code
1.Try it without installing
git clone https://github.com/anthropics/claude-code claude --plugin-dir ./claude-code/mods/agents-mdLoads the mod for one session only. Nothing is added to your settings.
How it works
hooks/register.ts is the only module in hooks/hooks.json; everything else under hooks/ is a small helper it imports. In the two loading modes, a prompt.context hook receives the instruction files Claude Code has loaded, walks up the tree with $.fs.ancestors for AGENTS.md, and answers with the list plus the new files as project files. This is the walk, from hooks/register.ts:
const found = isClaudeProject
? NONE
: await $.fs.ancestors({ names: Names.AGENTS_NAMES }).catch(() => {
isWalkFailed = true
return NONE
})
const added = Files.unseenFiles(Files.filesOf(found), handed)unseenFiles drops a file whose path Claude Code already holds, or whose text equals a handed project file's (for example a CLAUDE.md symlinked to AGENTS.md). A tool.call hook on Read lets the read finish first, then, for a file under the project root, attaches the AGENTS.md files of the directories between the root and that file as Contents of <path>:, once per agent loop. An agent.spawn hook for forks copies the parent's delivered set so a fork does not get the same files twice.
Customize it
The option is the /config row "Project instructions", a picker over the four values. By hand, set it in user settings, --settings or managed settings (a project's .claude/settings.json is not read for plugin options):
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}When run with claude --plugin-dir mods/agents-md, the same entry is keyed "agents-md". An older key, projectInstructions, is still honoured until instructionFiles is set to a non-default value. The author's README lists eight places where AGENTS.md still differs from CLAUDE.md, for example --add-dir directories contribute no AGENTS.md and /memory does not know the files.
Permissions & safety
We read every file the plugin can execute: plugin.json, hooks/hooks.json, hooks/register.ts and all the helper modules under hooks/ it imports, plus the tests. There is no package.json, install script, binary or bundled code, and the sources contain no non-ASCII characters.
- Reads files.
$.fs.ancestorsreadsAGENTS.mdand.claude/AGENTS.md(and looks forCLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md) up the tree. Their text goes to the model as project instructions, so anAGENTS.mdyou do not trust can steer Claude, as aCLAUDE.mdcan. - Reads environment variables.
HOME,USERPROFILE,CLAUDE_CODE_SIMPLEandCLAUDE_CODE_DISABLE_ATTACHMENTS, only to resolve~paths and to skip attachments where Claude Code attaches nothing. It writes no environment variables. - Intercepts tool calls. The
tool.callhook onReadand the forkagent.spawnhook wait for the call, then return its result, adding only context after a successful Read. They never deny a call.claude plugin validatenotes that both hooks lack a.catch. - Telemetry. It calls
$.telemetry.logand$.telemetry.markwith counts and closed choices (mode, file and import counts, total length, a few flags). The README says no path and no text are included and that the rows are dropped where Anthropic's telemetry plugin is not installed. We did not check that plugin. - No network, no processes, no writes, no daemons. The mod uses no
fetch, shell,$.fswrite or background clock. It does write one debug-log line,no CLAUDE.md found; AGENTS.md loaded: <paths>, through$.ui.log. - License. The repository's
LICENSE.mdreads "© Anthropic PBC. All rights reserved" with use subject to Anthropic's Commercial Terms, so the page isredistributable: false. We link to the code and do not mirror it.
claude plugin validate reported no errors. Its only findings were a non-blocking "no icon" warning for the plugin directory, the two missing-.catch notes above, and advice that the README has no install line. The author's 5 tests passed on Claude Code 2.1.310.
- Intercepts tool calls
- Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UI
- Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
Compatibility & troubleshooting
Checked with Claude Code 2.1.310 on macOS (validate, tests and the demo recording). The README describes the plugin as a built-in (agents-md@builtin), so a copy of Claude Code that ships it may already load it; /plugin lists built-ins, where it can be turned off. If your AGENTS.md is not picked up:
- Look for a
CLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdanywhere from the root down to the working directory. In the default mode any of them makes the mod stand down. - Check the option in
/configis notclaude-mdormanaged-only. - In
--bareor--safe-moderuns, or withCLAUDE_CODE_DISABLE_CLAUDE_MDSset, Claude Code loads no instruction files, and nested attachments are skipped withCLAUDE_CODE_DISABLE_ATTACHMENTS. - The mod finds nothing on a thin client, whose workspace files are remote.
- After you change the option, the new files arrive with the next context Claude Code builds: the next turn,
/clearor a compaction.
FAQ
- Does Claude Code read AGENTS.md without this mod?
- The mod's README says the engine loads CLAUDE.md only, and the plugin adds AGENTS.md on top. With the option set to claude-md the plugin adds nothing and CLAUDE.md is loaded as before.
- What happens if my project has both CLAUDE.md and AGENTS.md?
- In the default mode, claude-md-or-agents-md, the mod stays out when a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists anywhere from the root down to the working directory. In claude-md-and-agents-md it loads both, and skips an AGENTS.md that CLAUDE.md already imports or links to.
- Does it send my AGENTS.md text anywhere?
- The code makes no network calls and runs no commands. It does hand counts (file count, import count, total length, the mode) to a telemetry noun, and the README says these rows exist only where Anthropic's telemetry plugin is installed. No path and no file text are in them.
- How do I change the mode?
- Open /config and pick a value in the row "Project instructions", or set instructionFiles under pluginConfigs in your user settings. The change reloads the module, and the next context the engine builds uses the new mode.
- Can I reuse the code in my own plugin?
- Not by copying it. The repository's LICENSE.md says all rights reserved and subject to Anthropic's Commercial Terms of Service, so this page links to the code and does not mirror it.
# Related mods
FeaturedContext Inspector
Shows what fills your Claude Code context, how much is re-reads and duplicates, and what compaction kept.
- status
- pane
- toast
- Writes files
- Intercepts tool calls
- Reads your prompts
- Changes the UI
- Adds commands/tools
tested with v2.1.303
memory-fork
Haiku checks each turn for memory-worthy facts; a tool-less fork writes them to Claude Code memory in the background.
- above-prompt
- pane
- Reads files
- Writes files
- Runs commands
- Calls the model (uses your quota)
- Intercepts tool calls
- Reads your prompts
- Changes the UI
- Adds commands/tools
tested with v2.1.307
More in Timers, todos, standups.