Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / agents-md-mod

agents-md mod

Overview

The agents-md built-in plugin makes AGENTS.md participate in Claude Code's project-instruction machinery. Its manifest is mods/…/plugin.json, which exposes the instructionFiles user option with four values: claude-md, claude-md-or-agents-md (default), claude-md-and-agents-md, and managed-only. Hook discovery is through mods/…/hooks.json, which loads mods/…/register.ts; mods/…/index.ts re-exports the hook submodules for tests and consumers.

mods/…/register.ts is the orchestrator. On registration it normalizes the configured mode with mods/…/mode-of.ts, falling back to mods/…/default-mode.ts for unset or unknown instructionFiles values. It also supports the legacy projectInstructions key via mods/…/legacy-mode-of.ts: old values are mapped to the new mode names when instructionFiles still reads as the default, and the first session.start logs a transcript notice telling the user how the legacy key was interpreted or ignored.

Every mode registers a session.start hook in mods/…/register.ts. It immediately forwards the start event with next(e) and floats a usage row through telemetry using mods/…/mode-row-of.ts; telemetry failures or the absence of the telemetry noun are swallowed by mods/…/quietly.ts. If the effective mode is claude-md, registration stops there and the engine's built-in CLAUDE.md behavior stands alone.

In managed-only, mods/…/register.ts registers only a prompt.context hook with a matcher for instruction-file kinds declared in mods/…/dropped-kinds.ts. That hook filters e.instructionFiles through mods/…/is-kept-without-instructions.ts, removing project, local, and user files while keeping managed organization files and memory.

The two modes that load AGENTS.md are claude-md-or-agents-md and claude-md-and-agents-md. Their prompt.context hook in mods/…/register.ts reads the instruction files already handed by the engine, walks ancestors through $.fs.ancestors({ names: Names.AGENTS_NAMES }), converts walk results into project instruction files with mods/…/files-of.ts, drops duplicates with mods/…/unseen-files.ts, and merges the remaining files back into the engine's list with mods/…/with-project-files.ts. mods/…/agents-names.ts defines the files read in each directory (AGENTS.md, .claude/AGENTS.md); mods/…/claude-names.ts defines the CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md names used to decide whether the engine already owns a directory's project instructions.

Fallback mode (claude-md-or-agents-md) yields to the engine when the project has its own Claude instruction file. mods/…/register.ts first checks the handed instruction files with mods/…/is-claude-file-on-walk.ts; if needed, it asks $.fs.ancestors({ names: Names.CLAUDE_NAMES }) because the engine may have loaded and then withheld a project CLAUDE.md. A walk failure is treated as a reason to add nothing and continue with the handed context. When files are added, mods/…/register.ts writes one debug-only $.ui.log line naming the top-level loaded AGENTS.md files for the project root; it does not write to the visible transcript for normal loads.

Placement is deliberately aligned with the engine's project-file order. mods/…/files-of.ts emits one InstructionFile per found AGENTS file and per @ import, preserving parent for imported parts. mods/…/chain-root-of.ts follows that parent chain so mods/…/project-dir-of.ts can place an import with the file that brought it in. mods/…/insertion-index.ts inserts AGENTS files before the first deeper project instruction file, otherwise after the last project/local file, otherwise before memory, otherwise at the end. mods/…/unseen-files.ts skips candidates already present by normalized path, and skips non-empty candidates whose trimmed content matches an existing project/local file, covering imported or symlink-equivalent content.

Nested AGENTS.md on file reads is implemented by the tool.call hook for Read in mods/…/register.ts. After the Read succeeds, the hook checks CLAUDE_CODE_SIMPLE and CLAUDE_CODE_DISABLE_ATTACHMENTS through mods/…/is-switched-on.ts; when either switch is on, it attaches nothing to match runs where the engine attaches no turn context. It resolves the Read path the way the Read tool does using mods/…/absolute-of.ts and a cached home directory from HOME/USERPROFILE, then requires the resolved path to be below the current $.session.root() using mods/…/is-below.ts. Root changes reset the delivered-file map and fallback decision.

For an eligible Read, mods/…/register.ts walks only the directories strictly between the project root and the read file: one walk for Names.AGENTS_NAMES and one for Names.CLAUDE_NAMES. In fallback mode, mods/…/outside-claude-dirs.ts removes any AGENTS entry from a directory that also has a Claude instruction file. Candidates are then run through Files.filesOf and Files.unseenFiles against the prompt-context files and same-walk Claude files, filtered against the per-agent delivered set, and attached as result.context strings from mods/…/nested-frame.ts (`Contents of :

`). A file is not attached when the Read is of that same file, but a whole-file Read still marks it as delivered so later Reads do not reattach it; truncated Reads do not mark same-file instructions as delivered.

The delivered nested-file state lives in a Map in mods/…/register.ts, keyed by mods/…/main-loop.ts for the main loop or by agentId for subagents. The agent.spawn hook for { fork: true } copies the parent's delivered set to a fork created by an Agent-tool call, but not to resumed forks or forks with an empty tool_use_id, because those may have older transcripts. When prompt.context finishes, the delivered map is cleared and the current context files are saved so nested Read handling knows what was already in the prompt.

Telemetry is count-only and path-free. mods/…/mode-row-of.ts emits agents_md_mode at session start with the effective mode and is_interactive. On the first prompt.context in AGENTS-loading modes, mods/…/load-counts-of.ts counts added AGENTS files, @ imports, total content length, whether fallback yielded, and whether the walk failed; mods/…/load-row-of.ts logs agents_md_load, while mods/…/load-mark-of.ts marks feature agents_md as ok or sad with reason walk_failed from mods/…/walk-failed-reason.ts. When a Read attaches nested files, mods/…/nested-row-of.ts emits agents_md_nested with mode and attached file count.

mods/…/README.md is the user-facing behavior contract for the mod and is more detailed than the manifest description. Tests live under mods/agents-md/tests/. mods/…/register.test.ts exercises the default mode's core cases: AGENTS-only projects add an instruction file and debug log line, projects with their own Claude file are left to the engine without extra walks, failed walks preserve the handed context, session.start sends only the mode telemetry row when a telemetry provider is seated, and sessions continue unchanged when no telemetry noun is present. Test fixtures under mods/agents-md/tests/fixtures/ provide fake ancestor walks, session/root/ui hooks, and a recording telemetry plugin.

Coverage / routing

This doc owns mods/agents-md/**, including:

  • mods/…/plugin.json for plugin metadata and option surface.
  • mods/agents-md/hooks/** for hook registration, file ordering/deduplication, path/frame handling, mode parsing, environment switches, name constants, and telemetry rows/marks.
  • mods/agents-md/tests/** for plugin behavior tests and fixtures.
  • mods/…/README.md for the user-facing behavior contract that should stay aligned with the implementation.

Coupling

Risks

  • mods/…/register.ts and mods/…/unseen-files.ts are fragile around truncated Reads and duplicate suppression. Git history includes fix(agents-md): retain instructions after truncated reads followed by later revert activity touching agents-md behavior, so changes to the fresh/attached/sent logic can make nested instructions disappear after partial file reads or reappear repeatedly.
  • mods/…/register.ts tracks root changes with rootSeen, isClaudeProject, inContext, and the per-agent given map. If a /cd, host directory change, or worktree move is not reflected in all of those, fallback decisions or delivered nested files can leak from one project root into another.
  • mods/…/normal-spelling-of.ts and mods/…/is-below.ts compare paths by spelling and do not resolve symlinks. A symlinked project alias can therefore differ from the engine's own resolved-path behavior, causing AGENTS.md files to be skipped or attached outside the intended tree.