claude-code-agents-md

Claude Code plugin for reading AGENTS.md files.

Loads project instructions from AGENTS.md files automatically, enabling Claude Code to work with projects using this open standard.

Why

If you work in a small number of repositories, symlinking AGENTS.md to CLAUDE.md is probably fine:

ln -s AGENTS.md CLAUDE.md

This plugin is intended for users who work across many repositories and want consistent AGENTS.md support without per-project setup. It's also useful for large monorepos where linking AGENTS.md to CLAUDE.md in every subdirectory is harder to reliably maintain.

With the plugin installed, AGENTS.md files load automatically as you navigate your codebase. Subdirectory files take precedence over parent files, giving you hierarchical context without manual symlink management.

This plug-in tries to adhere as closely as possible to the AGENTS.md spec, which has subtle differences from CLAUDE.md.

Requirements

• Node.js 22.18.0 or later (for native TypeScript support)

Install

Direct Install

claude plugin install github:bendrucker/claude-code-agents-md

Via Marketplace

Add the bendrucker marketplace, then install the plugin:

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

How It Works

The plugin uses two hooks to inject AGENTS.md content into Claude Code sessions:

SessionStart: At session start (or after /clear, /compact), injects the root AGENTS.md from the project directory.

PostToolUse (Read): After any file read, walks up the directory tree from the read file to find the closest AGENTS.md and injects it. This allows subdirectories to have their own context.

Each AGENTS.md is injected only once per session to avoid context duplication.

Usage

Create AGENTS.md files in your project to provide context to Claude Code:

project/
├── AGENTS.md           # Root instructions (injected at session start)
├── src/
│   ├── api/
│   │   └── AGENTS.md   # API-specific instructions
│   └── utils/
└── tests/
    └── AGENTS.md       # Testing instructions

When Claude reads a file in src/api/, it receives the src/api/AGENTS.md content. The closest AGENTS.md to the file being read wins.

See the AGENTS.md standard for guidance on file contents.

AGENTS.md vs CLAUDE.md

Claude Code natively supports CLAUDE.md files for project instructions. This plugin adds support for AGENTS.md, an open standard.

Behavior	CLAUDE.md	AGENTS.md
Loads nearest file in directory tree	✓	✓
Loads all ancestor files to project root	✓	✗
@ file imports	✓	✗

Use AGENTS.md for portable project instructions across AI coding tools. Use CLAUDE.md for richer Claude Code-specific features.

License

MIT © Ben Drucker