Skip to content

feat: Add agents-md plugin for AGENTS.md fallback support#29833

Closed
baktybekb wants to merge 1 commit intoanthropics:mainfrom
baktybekb:feat/agents-md-plugin
Closed

feat: Add agents-md plugin for AGENTS.md fallback support#29833
baktybekb wants to merge 1 commit intoanthropics:mainfrom
baktybekb:feat/agents-md-plugin

Conversation

@baktybekb
Copy link
Copy Markdown

@baktybekb baktybekb commented Mar 1, 2026

Summary

Adds a new plugin (plugins/agents-md) that provides AGENTS.md support for Claude Code, addressing the most upvoted issue in this repository.

  • SessionStart hook detects and loads AGENTS.md files when no CLAUDE.md is present at the same directory level
  • Mirrors native CLAUDE.md loading order (root-first ancestor walk)
  • Supports both <dir>/AGENTS.md and <dir>/.claude/AGENTS.md locations
  • Respects priority hierarchy: if CLAUDE.md exists, AGENTS.md is skipped
  • Handles edge cases: special characters, unicode, large files (40k char cap)

This enables cross-tool compatibility with 20,000+ repositories using the AGENTS.md standard (Codex, Cursor, Amp, and other AI coding tools).

Resolves #6235

Behavior matrix

CLAUDE.md exists AGENTS.md exists Result
Yes Yes Only CLAUDE.md is used (native behavior)
Yes No Only CLAUDE.md is used (native behavior)
No Yes AGENTS.md is loaded by this plugin
No No Nothing loaded

Plugin structure

plugins/agents-md/
├── .claude-plugin/plugin.json      # Plugin manifest
├── hooks/hooks.json                # SessionStart hook config
├── hooks-handlers/session-start.sh # Detection & loading logic
└── README.md                       # Documentation

Test plan

  • AGENTS.md only present — loads content correctly
  • Both CLAUDE.md and AGENTS.md present — skips AGENTS.md
  • Neither file present — silent, no output
  • .claude/AGENTS.md nested location — loads correctly
  • Mixed hierarchy (parent AGENTS.md + child CLAUDE.md) — correct per-level behavior
  • Special characters, unicode, quotes, JSON-like content — safe JSON encoding

Adds a plugin that reads AGENTS.md files when no CLAUDE.md is present,
enabling cross-tool compatibility with Codex, Cursor, Amp, and 20,000+
repositories that use the AGENTS.md standard.

Resolves anthropics#6235
@kcrwfrd
Copy link
Copy Markdown

kcrwfrd commented Mar 1, 2026

@baktybekb can it also support lazy loading <project_dir>/some/sub/path/AGENTS.md when reading files from that directory?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Support AGENTS.md.

2 participants