# agents-md

`AGENTS.md` read the way Claude Code reads `CLAUDE.md`, as a plugin, under
one option, `instructionFiles`:

- `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.)

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? }`, kinds `managed`, `user`, `project`,
`local`, `memory`, in load order) and a hook answers 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: same place in the context,
same framing, same omission rules, same announcement. An organization's
prepended plugin on `prompt.context` sits above this one and has the last
word on the files.

`hooks/register.ts` is the module; everything under `hooks/` is its parts,
importing `claude-code` and one another alone. `tests/` runs under
`claude plugin test <this folder>`.

## Setting the option

As a built-in its option is the `/config` row "Project instructions", a
picker over the four values, each described there. By hand it is

```json
{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

in user settings (`~/.claude/settings.json`), `--settings`, or managed
settings; a project's `.claude/settings.json` is not read for plugin
options. Changing it 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.

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`, any other
value as `claude-md` (which adds nothing, never as the default, which loads
`AGENTS.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.

Run from this folder instead (`claude --plugin-dir mods/agents-md`), the
same entry is keyed `"agents-md"`.

## What it hooks

| event | what the hook does |
| --- | --- |
| `session.start` | in every mode: 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 its own entry after its file, each 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` it answers nothing when the project has a `CLAUDE.md` of its own (among the handed files, else found by a `$.fs.ancestors` walk, so a `CLAUDE.md` the engine loaded and then withheld still counts), and 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 (counts) and the feature mark; under `managed-only` (matcher: a `project`, `local` or `user` file present): answers the list without those kinds |
| `agent.spawn` on `fork: true` | under `claude-md-or-agents-md` and `claude-md-and-agents-md`: 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; a fork started in the same tool batch as a `Read` inherits that Read's file although its prefix holds a placeholder for it) |
| `tool.call` on `Read` | under `claude-md-or-agents-md` and `claude-md-and-agents-md`, 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 and a moved root starts the delivered sets and the fallback decision over; a file elsewhere gets nothing, as the engine attaches no nested `CLAUDE.md` there): walks only the directories strictly between the root and the read file (`$.fs.ancestors` with `below: root`, as the engine walks only those for a nested `CLAUDE.md`, never up to the filesystem root again) and attaches their `AGENTS.md` files not yet given to that agent loop, not already among the context's instruction files (by path or, for a project file, by text) and not claimed by a `CLAUDE.md` of the same directory (or imported by one), as `context` after the tool result, framed `Contents of <path>:` byte for byte as the engine frames a nested `CLAUDE.md`, whatever its size; each file once per loop and conversation (the context's recomputation after a compaction or `/clear` starts the count over), the context's files never; a Read that attached files sends the nested row. A `~` or `~/` path is read under the home directory as the Read tool reads it |

## What it calls on `$`

`fs.ancestors` (with each found file's `parts`: the file and its imports
apart; with `below` on a Read; it finds nothing on a thin client, whose
workspace files are remote, as the engine's own walk does), `session.root`,
`session.cwd`, `env.get` (`HOME` and `USERPROFILE`, once per load, the
profile first on a Windows spelling of the working directory, so a `~/` path
the model hands a Read resolves where the Read tool reads it), `ui.log`,
`telemetry.log` and `telemetry.mark`.

`$.telemetry` is the [telemetry](../telemetry) plugin's noun; where that
plugin is not seated the calls find no noun and are dropped without a trace,
and nothing else changes.

## What it logs

Counts and closed choices only; no path and no file text. Each row goes
through `$.telemetry.log`, so it exists only where the telemetry plugin
does:

| event | when | properties |
| --- | --- | --- |
| `agents_md_mode` | once per fresh load, at `session.start` | `mode` (`claude-md` \| `claude-md-or-agents-md` \| `claude-md-and-agents-md` \| `managed-only`), `is_interactive` |
| `agents_md_load` | the first context of a load, under `claude-md-or-agents-md` and `claude-md-and-agents-md` | `mode`, `file_count` (`AGENTS.md` files handed to the engine), `import_count` (their `@` imports), `total_content_length`, `yielded` (`claude-md-or-agents-md` stood down for a `CLAUDE.md` of the project's own), `walk_failed`; with it one `$.telemetry.mark` for feature `agents_md`: `ok`, or `sad` with reason `walk_failed` |
| `agents_md_nested` | a Read that attached nested files | `mode`, `file_count` |

## Where it still differs from CLAUDE.md

All of these apply only to the modes that load `AGENTS.md`,
`claude-md-or-agents-md` (the default) and `claude-md-and-agents-md`. Each
names a loader fact a plugin cannot reach through the events it has today.

1. 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.
2. A nested file the plugin attaches is not registered in the loop's
   read-file state, so 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.
3. `/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.
4. Paths compare by spelling; the engine resolves a symlinked alias of the
   working directory before deciding a file is inside it.
5. `--add-dir` directories contribute no `AGENTS.md`, where the engine can
   load their `CLAUDE.md`.
6. `/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).
7. 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.
8. 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.

## Testing

    claude plugin test mods/agents-md

`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.