agents-md

agents-md reads AGENTS.md the way Claude Code reads CLAUDE.md, as a plugin, under one option, instructionFiles. It has four modes, described in full under Choose a mode: only CLAUDE.md, AGENTS.md where the project has no CLAUDE.md of its own (the default), both together, or the project's and the person's instruction files dropped with the organization's kept.

How the files reach the model is the engine's doing, not the plugin's. prompt.context hands a hook the instruction files behind claudeMd ({ path, kind, content, parent? }, with kinds managed, user, project, local and memory, in load order), and a hook answers with the list changed. The engine then renders claudeMd from the answered files with its own preamble and framing, announces them by name, and keeps only the managed ones for an agent that omits project instructions (Explore, Plan, a custom agent with omitClaudeMd).

So an AGENTS.md this plugin adds as a project file is, to everything downstream, a project instruction file: the same place in the context, the same framing, the same omission rules and the same announcement. An organization's prepended plugin on prompt.context sits above this one and has the last word on the files.

The README lists where it still differs from CLAUDE.md. All of these apply only to the modes that load AGENTS.md, claude-md-or-agents-md and claude-md-and-agents-md, and each names a loader fact a plugin cannot reach through the events it has today.

Nested files attach on a text Read only. The engine also attaches a directory's CLAUDE.md for a file @-mentioned in the prompt, for the IDE's opened file or selection, and for the Read tool's notebook, image and PDF results.

A nested file the plugin attaches is not registered in the loop's read-file state. After a compaction the engine does not restore it among the recently read files (the plugin attaches it again at the next Read under that directory instead), and a change to it mid-session is not re-announced.

/cd carries the new tree's CLAUDE.md in its own notice. The plugin's files for the new tree arrive in the same next request through the engine's instructions announcement instead.

Paths compare by spelling. The engine resolves a symlinked alias of the working directory before deciding a file is inside it.

--add-dir directories contribute no AGENTS.md, where the engine can load their CLAUDE.md.

/memory and the # shortcut do not know AGENTS.md files, and the engine's own initial-load row does not count them (this plugin's agents_md_load row does).

An @ import outside the working directory inside an AGENTS.md is honoured only once the approval the engine asks for a CLAUDE.md's external imports has been given. Without it the import is left out, as a CLAUDE.md's is. The approval dialog itself is raised for CLAUDE.md imports alone.

A subagent that is not a fork gets a nested AGENTS.md at its own first Read under that directory even when its parent's loop was already given it. The engine does not hand such a subagent the nested CLAUDE.md again. A fork matches the engine on both sides.

The module is hooks/register.ts, and everything under hooks/ is its parts, importing claude-code and one another alone.

session.start: in every mode it passes the start straight through and floats the usage row for the configured mode, never awaited. The first start of a load logs how a stored projectInstructions value is read. The session's start never waits on this plugin.

prompt.context, under claude-md-or-agents-md and claude-md-and-agents-md: walks $.fs.ancestors for the AGENTS.md files above the working directory and answers them as project instruction files. Each @ import gets its own entry after its file, and each is placed where a project file of its directory stands (root first, before the first deeper project file, else after the last project file, before memory). Files the engine already holds by path or by content are left out.

Under claude-md-or-agents-md the same hook answers nothing when the project has a CLAUDE.md of its own. That is decided among the handed files, else by a $.fs.ancestors walk, so a CLAUDE.md the engine loaded and then withheld still counts. It logs which files it loaded once, and again after a move to another project root. Handed unknown files (a hook above rewrote the claudeMd text), it adds nothing. The first context of a load sends the load row and the feature mark.

prompt.context, under managed-only (matcher: a project, local or user file present): answers the list without those kinds.

agent.spawn on fork: true, under the two AGENTS.md modes: a fork the Agent tool starts shares its parent's prompt prefix, so the parent loop's delivered nested files are copied to the fork's loop and not attached to it again. A /fork or /subtask fork does not raise agent.spawn yet and starts from an empty set, as every fork did before.

tool.call on Read, under the two AGENTS.md modes: for a file under the session's project root ($.session.root(), read live, so /cd, a host's directory change and worktree moves are followed), it walks only the directories strictly between the root and the read file and attaches their AGENTS.md files that were not yet given to that agent loop, are not already among the context's instruction files and are not claimed by a CLAUDE.md of the same directory. They arrive as context after the tool result, framed "Contents of <path>:" byte for byte as the engine frames a nested CLAUDE.md, whatever their size, each file once per loop and conversation. A file elsewhere gets nothing, as the engine attaches no nested CLAUDE.md there.

Nothing is attached in a run where the engine attaches nothing to a turn: --bare (which sets CLAUDE_CODE_SIMPLE) or CLAUDE_CODE_DISABLE_ATTACHMENTS, both read on every Read through $.env.get. A ~ or ~/ path is read under the home directory as the Read tool reads it. A Read that attached files sends the nested row.

What it logs: counts and closed choices only, with no path and no file text. Each row goes through $.telemetry.log, so it exists only where the telemetry plugin does. agents_md_mode is sent once per fresh load at session.start, with mode and is_interactive. agents_md_load is sent for the first context of a load under the two AGENTS.md modes, with mode, file_count, import_count, total_content_length, yielded and walk_failed, plus one $.telemetry.mark for the feature agents_md. agents_md_nested is sent for a Read that attached nested files, with mode and file_count.

This mod ships inside Claude Code as a built-in. Its one option is the /config row "Project instructions", a picker over the four values, each described there. The default is claude-md-or-agents-md.

By hand, the option is set in user settings (~/.claude/settings.json), with --settings, or in managed settings, as {"pluginConfigs": {"agents-md@builtin": {"options": {"instructionFiles": "claude-md-and-agents-md"}}}}. A project's .claude/settings.json is not read for plugin options.

Changing the option reloads the module, and the next context the engine builds (the next turn after the reload, a new conversation, /clear, a compaction) carries the new mode's files. A hand-typed value outside the four is told once in the transcript and reads as the default.

/plugin lists the plugin among the built-ins, where a person can turn it off. With it off, the engine reads CLAUDE.md alone. No hooks setting or CLI mode turns it off: disableAllHooks, allowManagedHooksOnly and --bare govern settings hooks and installed plugins, not built-ins. Where the engine loads no instruction files (--bare without --add-dir, --safe-mode, CLAUDE_CODE_DISABLE_CLAUDE_MDS), its walk finds none and the plugin adds none, CLAUDE.md and AGENTS.md alike.

To read it running from source, run the command below from the root of a clone of the repository. Run from that folder, the same entry is keyed "agents-md" instead of "agents-md@builtin".

The option was first keyed projectInstructions, with the values claude, agents-fallback, both and none. A value still stored under that key is honoured for now while instructionFiles reads as its default: none as managed-only, claude as claude-md, agents-fallback as claude-md-or-agents-md, both as claude-md-and-agents-md, and any other value as claude-md. The first session.start of a load says in the transcript how it was read. Once instructionFiles is set to anything but its default, the old key is not read and the transcript says to remove it.

In plugin.json the option is declared as userConfig instructionFiles: type string, title "Project instructions", not required, default claude-md-or-agents-md, with the four values as its options.

The source does not document how to enable function hooks. The author of the announcement issue (anthropics/claude-code #91870) wrote in its Sep 9, 2026 update that anyone who wants to test can start Claude Code with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1. That is a note in an issue, not documentation, and it may change without notice.

The source lives in the mods/agents-md folder of the anthropics/claude-code repository. To fetch only that folder and the mods/types declarations it is typed against, clone the repository sparsely, enter it, and check out those two folders. The clone also brings the files at the top level of the repository.

The repository's LICENSE.md reads: "© Anthropic PBC. All rights reserved. Use is subject to Anthropic's Commercial Terms of Service." The mods README says this folder is the source of the mods, published as it is built into the binary, so that it can be read. This listing does not call it open source.

Run the command below from the root of a clone of the repository. Tests live in the mod's tests/ folder, which holds 1 test file (tests/register.test.ts) and a fixtures folder as of the source read for this listing.

Per its README, tests/register.test.ts covers the default mode: a project with AGENTS.md alone gets it as a project instruction file and one transcript line naming it, a project with a CLAUDE.md of its own is left to the engine without a walk, a failed walk leaves the context as handed, and the start hands $.telemetry the mode row alone where a test seats a provider for that noun, and goes on untouched where none is seated.

Per the mods README, a test gets the engine's own $ and a plugin's on. Each call on $ is one the engine makes, through every hook of the mod loaded as it ships. The hooks a test registers with on sit beneath the mod, where the rest of the world would be, and a call they leave unanswered throws, naming its event. A test file is named for what it covers under hooks/, and the kit's mock answers the world beneath the mod from memory (mock.env, mock.store, mock.clock).

The mods README also says that tsc -p mods/tsconfig.json typechecks every mod's hooks and tests against types/ and each mod's own types contract.

claude-md: only CLAUDE.md is loaded, by the engine, as today. The plugin adds nothing.

claude-md-or-agents-md (the default): a project with no instruction files of its own gets its AGENTS.md files instead, loaded exactly where and how CLAUDE.md would be. "Of its own" is read off what the engine loaded for the context: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in any directory from the root down to the working directory leaves the whole project to the engine, and the plugin stays out. The organization's managed file, the person's ~/.claude/CLAUDE.md, a .claude/rules file and an added directory's CLAUDE.md do not count, as the nested walk does not see them either. With none, every AGENTS.md and .claude/AGENTS.md on that path joins the instruction files the engine renders, and a Read under a subdirectory attaches that directory's AGENTS.md unless a CLAUDE.md there claims it.

claude-md-and-agents-md: every AGENTS.md is loaded beside CLAUDE.md, up and down the tree. A file CLAUDE.md already @-imports, or is a link to, is not loaded a second time (compared by path, then by content).

managed-only: the project's checked-in and private instruction files and the person's own are dropped from the context. The organization's managed CLAUDE.md and the engine's memory stay. The engine's nested CLAUDE.md attachments on Read are not an event yet and still arrive. The engine's claudeMdExcludes setting also exists, for user, project and local files, and applies to the AGENTS.md files this plugin reads too.