[Feature Request] Add global AGENTS.md configuration support alongside project-level

Status Open
Reported on v2.1.278
Maintainer reply None cached
Activity 3 comments · opened Sep 21, 2026

Bug Description
You guys recently added support for AGENTS.md, but for some reason you added only project level, but god damn, I want to have AGENTS.md global configurations. Like why should I still have these freaking links inside the CLAUDE.md? Please just do that in a good way.

Doing that partially doesn't work. I'm so upset, but at the same time, I was so excited that you guys listened to the audience and added support of AGENTS.md. But oh my gosh, not this way. Please. Make that happen.

Environment Info

  • Platform: darwin
  • Terminal: ghostty
  • Version: 2.1.278
  • Feedback ID: 6a7cecaa-7de6-4e6a-8295-2b0869cffcb3

Errors

[]

View original on GitHub ↗

3 Comments

tredondo · 23 days ago

LOL join the feature-beggars club :)

garysassano · 22 days ago

The agents-md plugin only works at project scope. User-level instructions still have to be ~/.claude/CLAUDE.md, so anyone keeping one shared AGENTS.md for several harnesses still needs a CLAUDE.md symlink just for Claude Code. Codex (~/.codex/AGENTS.md) and opencode (~/.config/opencode/AGENTS.md) both accept AGENTS.md as the global filename.

There's also a side effect that looks like a workaround but isn't one. The plugin loads AGENTS.md and .claude/AGENTS.md from every directory above the working directory. Home is one of those, so ~/AGENTS.md and ~/.claude/AGENTS.md do get loaded, but only in sessions started somewhere under $HOME (not in /tmp or /mnt/c), and only as project files. That means they disappear under managed-only, when the plugin is off, and on Bedrock, Vertex and Foundry.

Proposal: load ~/.claude/AGENTS.md as a user-kind instruction file, the same way ~/.claude/CLAUDE.md is loaded. Dedupe by path and content when CLAUDE.md is a symlink to it, which the plugin already does for project files. Put it behind the same instructionFiles modes: claude-md-or-agents-md uses it when there is no ~/.claude/CLAUDE.md, and claude-md-and-agents-md always loads it.

YunosukeYoshino · 15 days ago

+1. Still reproducible on 2.1.284 (macOS).

I'd like to keep a single ~/.claude/AGENTS.md as my user-level instructions and share it with other harnesses, but Claude Code only picks up ~/.claude/CLAUDE.md at user scope. Right now the only reliable option is to keep a CLAUDE.md copy or symlink just for Claude Code.

Supporting the proposal above: loading ~/.claude/AGENTS.md as a user-level instruction file (same as ~/.claude/CLAUDE.md, deduped when one is a symlink to the other) would solve this cleanly.