README.md

Claude Code only reads CLAUDE.md. The AGENTS.md specification is supported by 23+ tools (Codex, Cursor, Copilot, Gemini CLI, and more), but Claude Code is not one of them. This has been the most requested feature (3,600+ upvotes) with no official response.

cc-agents-md fixes this. One command, and every Claude Code session automatically loads your AGENTS.md files. No CLAUDE.md wrapper files. No symlinks.

How It Works

Three hooks are registered in ~/.claude/settings.json:

1. SessionStart — On every new Claude Code session, walks upward from your working directory to the git root, collects every AGENTS.md on the path, and injects the content
2. UserPromptSubmit — On each user message, checks if AGENTS.md files changed since last injection. If changed, re-injects updated content. If unchanged, exits silently (zero overhead)
3. PreCompact — Before context compression, re-injects AGENTS.md content so instructions survive in long sessions

Small files are inlined directly into Claude's context. Large files get a read instruction — Claude reads the full file on demand.

monorepo/
├── AGENTS.md                  ← always loaded (project root)
├── packages/
│   ├── frontend/
│   │   ├── AGENTS.md          ← loaded if you're working here
│   │   └── src/
│   └── backend/
│       ├── AGENTS.md          ← NOT loaded (not on your path)
│       └── src/

The depth adapts to where you are. Open Claude at the root? One file. Open it in packages/frontend? Two files. No scanning downward, no wasted context.

Installation

npx cc-agents-md setup

That's it. Restart Claude Code.

Verify

npx cc-agents-md doctor

Uninstall

npx cc-agents-md remove

Commands

Command	Description
setup	Install the SessionStart hook globally
remove	Uninstall completely (hook + script)
status	Show installation state and detected AGENTS.md
doctor	Full health check (hook, patch, watcher, config)
preview	Print exactly what Claude would see
migrate	Convert CLAUDE.md files to AGENTS.md format
patch	Experimental — patch Claude Code internals
unpatch	Restore Claude Code to original state
watch	Auto-repatch after Claude Code upgrades (macOS/Linux)
unwatch	Remove the auto-repatch watcher
logs	Show auto-repatch watcher log (--lines N)
diff	Show what the patch changed (unified diff or metadata)

Output flags

Flag	Description
--json	Machine-readable JSON (status, doctor, preview, logs, diff)
--verbose	Extra detail during patch (regex tier, byte offsets, config)

Experimental: Internal Patching

Warning: This is experimental. It modifies Claude Code's JavaScript internals and may break after updates. Use cc-agents-md unpatch to restore at any time.

The default setup command uses a stable SessionStart hook. For deeper integration, patch modifies Claude Code itself so it loads AGENTS.md natively — the same way it loads CLAUDE.md:

# Dry run — see what would change
cc-agents-md patch --dry-run

# Patch npm installation
cc-agents-md patch

# Patch native binary (Homebrew) — requires --force
cc-agents-md patch --force

# Restore original
cc-agents-md unpatch

What it does

Patches the async reader function inside Claude Code to try AGENTS.md as a fallback when CLAUDE.md is not found. This means:

• AGENTS.md is loaded at each directory level (same walk-up discovery as CLAUDE.md)
• AGENTS.local.md works as a local counterpart (like CLAUDE.local.md)
• .claude/AGENTS.md is checked alongside .claude/CLAUDE.md

After Claude Code updates

The patch needs to be reapplied after every Claude Code update:

cc-agents-md patch        # or: cc-agents-md patch --force

The backup of the previous version is stored alongside the patched file and used by unpatch to restore.

Auto-repatch watcher

Tired of repatching after every update? The watch command installs a platform-native file watcher that automatically reapplies the patch:

# Install the watcher
cc-agents-md watch

# Remove it
cc-agents-md unwatch

• macOS: LaunchAgent monitoring /opt/homebrew/Caskroom/claude-code — fires after brew upgrade claude-code
• Linux: systemd user path unit monitoring the npm global install directory

Logs are written to ~/.claude/cc-agents-md-autopatch.log.

Configuration

Config file

Create .agents-md.json at your project root (or any ancestor directory) to customize behavior:

{
  "threshold": 150,
  "patterns": ["AGENTS.md", "RULES.md"],
  "exclude": ["vendor", "node_modules"],
  "cache": true
}

Key	Default	Description
threshold	200	Lines — inline below, read instruction above
patterns	["AGENTS.md"]	File names to look for at each directory level
exclude	[]	Directory names to skip during walk-up discovery
cache	true	Cache assembled output based on file modification times

Environment variables

Environment variables override the config file (useful for CI):

export AGENTS_MD_INLINE_THRESHOLD=200   # lines — inline below, read instruction above
export AGENTS_MD_PATTERNS=AGENTS.md,RULES.md   # comma-separated file patterns
export AGENTS_MD_EXCLUDE=vendor,dist            # comma-separated directories to skip
export AGENTS_MD_CACHE=0                        # disable caching

How is this different from...

@AGENTS.md in CLAUDE.md

That still requires a CLAUDE.md file in every repo. Also, imported content is followed less reliably than inline instructions.

Symlink CLAUDE.md → AGENTS.md

Still creates a CLAUDE.md file (even if it's a symlink). Doesn't handle nested AGENTS.md in monorepos.

tweakcc

A general-purpose Claude Code patcher with 40+ patches (themes, prompts, tools, etc.). cc-agents-md is focused solely on AGENTS.md loading — the setup command uses the stable hook API (no patching), while patch is an opt-in experimental alternative for deeper integration.

Platform support

Platform	Hook loader	Patching	Auto-repatch watcher
macOS	bash	npm + Homebrew (Bun binary)	LaunchAgent
Linux	bash	npm	systemd user path unit
Windows	PowerShell	npm	not yet supported

Requirements

• Claude Code (any version with SessionStart hooks)
• Node.js >= 18 (for the CLI only — the runtime hook is pure bash / PowerShell)
• bash (macOS/Linux) or PowerShell (Windows)

Troubleshooting

macOS: Gatekeeper blocks Claude Code after patching or upgrade

After brew upgrade claude-code, macOS may quarantine the new binary, preventing it from opening. The patch command removes the quarantine flag automatically (xattr -dr com.apple.quarantine), but if the binary is blocked before the watcher can repatch:

xattr -d com.apple.quarantine /opt/homebrew/Caskroom/claude-code/*/claude

To prevent this permanently, tell Homebrew to skip quarantine on all cask installs:

echo 'export HOMEBREW_CASK_OPTS="--no-quarantine"' >> ~/.zshrc
source ~/.zshrc

License

GPL-3.0 — see LICENSE.