You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
By contrast, CLAUDE.md feels too specific to Claude Code. It doesn’t work as well when collaborating with other developers who aren’t using Claude Code.
Reacted by Tetsuya Morimoto, Matias Käkelä, Mateusz Bochyński, Patrick Dawkins, Hannes Burrichter, adriamontoto, Diogo Correia, Christian Roy, Leandro Perez, Micah Nolte and 5183 more
Reacted by Šimon Demočko, Nacho Codoñer, Alex Vechy, Jo Jurgens, Roman Frey, Pedro Henrique Dos Santos, Derek Helmick, Pavel Ekishev, whatevertogo, Nguyễn Phước Thuận and 3 more
Reacted by bl-ue, Mike, Alexander Densley, Thiago Dantas, Brennan Goewert, Igor Crispim Diniz, sluo-sc, Peter Solnica, Nacho Codoñer, Khauê Viana and 39 more
Reacted by Daniel O’Connor, Eric, Maxime Beauchemin, Beto Dealmeida, chck, Eric Wang, Connor Adams, David Sloiko, rossmycoding, Fábio Assunção and 320 more
Reacted by ncook-hxgn, Éwerton Ferreira, whatevertogo, Nguyễn Phước Thuận, Oli, M.Ihsan , Juan Calderon-Perez and Will Kempster
Reacted by Eric, Brennan Goewert, Maxime Beauchemin, Beto Dealmeida, chck, Tobias Munk, Daniel Vaz Gaspar, Connor Adams, David Sloiko, rossmycoding and 436 more
Reacted by Eric, Brennan Goewert, Maxime Beauchemin, Beto Dealmeida, chck, Connor Adams, David Sloiko, rossmycoding, Fábio Assunção, Mauro Codella and 353 more
Reacted by Eric, Brennan Goewert, Maxime Beauchemin, Beto Dealmeida, chck, David Sloiko, Fábio Assunção, George Jose, Oscar Serna, Paul Berg and 280 more
The naming, "agents.md" a bit confusing given subagents are defined as "agents."
Reacted by slimshader, James Tan, KyrieMing, Igor Bari, Mahid , Ashwin Krish, Tim Schneider, Ivan, Derek Helmick, Dominic Frei and 8 more
Reacted by John HU, Cosimo Lupo, Anthony Bible, Brennan Goewert, Coleton Pierson, dave-shawley, David, Clément Petit, Ryan McCullough, Oleg V. Kozlyuk and 1256 more
Reacted by Natthapol Vanasrivilai, Zhiwei Liang, SnowNight1, Dominic Frei, Alan Munirji, Rahul Raj Purohit, Max Eise, Jensen, segv01, sahan and 8 more
Feature Request: Support AGENTS.md as a Fallback for Enhanced Interoperability
Is this a bug report or a feature request?
This is a feature request.
Problem Statement
Claude Code's CLAUDE.md memory system is a powerful feature for providing project-specific context. However, as the AI agent ecosystem matures, a simple open standard, AGENTS.md, is gaining significant traction. It's used by over 20,000 open-source projects and supported by a growing number of AI coding tools.
Currently, if a developer using Claude Code clones a repository that provides an AGENTS.md file, that context is ignored. The developer must manually create a CLAUDE.md file and duplicate the instructions, creating unnecessary friction and a missed opportunity for Claude Code to be instantly effective on a new project.
Proposed Solution
I propose that Claude Code adopt a dual-file approach that prioritizes its native format while gracefully falling back to the open standard. This would offer full backward compatibility while dramatically improving interoperability.
The lookup logic would be as follows:
Check for CLAUDE.md First: When claude is launched in a project directory, it first searches for a CLAUDE.md file.
If CLAUDE.md is found: Load its contents into context and stop. The AGENTS.md file is ignored. This ensures that projects optimized for Claude Code continue to work exactly as expected, with their specific instructions taking precedence.
If CLAUDE.md is NOT found: Proceed to check for an AGENTS.md file in the same directory.
If AGENTS.md is found: Load its contents into context. This provides a robust baseline of instructions for projects that follow the open standard.
(Optional Suggestion): Upon loading AGENTS.md, Claude could provide a subtle one-time message to inform the user:
AGENTS.md found and loaded. For instructions tailored specifically to Claude Code, you can create a CLAUDE.md file.
This simple, non-breaking change would make Claude Code a better citizen in the broader AI development ecosystem.
Detailed Breakdown of the Dual Approach
This system creates a clear and logical hierarchy for agent instructions.
Primary Source: CLAUDE.md (Claude-Specific)
Role: This remains the primary, native instruction file for Claude Code.
Content: It is the ideal place for instructions that leverage Claude Code's unique features, such as invoking specific sub-agents, configuring MCP servers, or defining complex, multi-step workflows with Claude-specific slash commands.
Precedence: Its presence overrides AGENTS.md, guaranteeing that Claude-tailored instructions are always followed.
Secondary Source: AGENTS.md (General Standard)
Role: This acts as a universal fallback, providing essential, agent-agnostic context.
Content: It typically contains general setup commands (pnpm install), testing instructions (pnpm test), and code style guidelines that are useful for any coding agent.
Benefit: It allows Claude Code to have immediate, zero-configuration context on tens of thousands of projects without requiring any action from the user or the project maintainer.
Use Cases and Benefits
Seamless Onboarding to Open-Source Projects:
Current: A developer clones apache/airflow, sees an AGENTS.md, and has to manually create CLAUDE.md to make Claude Code aware of the build steps.
Proposed: The developer clones the repo and runs claude. The tool automatically finds and loads AGENTS.md. The developer can immediately ask, "Run the tests for the core package," and Claude knows what to do.
Improved Interoperability in Mixed-Tool Teams:
Current: A team uses multiple AI agents. They must either maintain separate instruction files (AGENTS.md, CLAUDE.md, etc.) or accept that some agents will lack context.
Proposed: The team maintains a single AGENTS.md as a source of truth for all agents. Claude Code can use this shared file, and if the team later decides to add Claude-specific optimizations, they can simply add a CLAUDE.md file without breaking the setup for other tools.
Full Backward Compatibility:
This change is entirely non-breaking. Any project that currently uses CLAUDE.md will continue to function exactly as it does today, as CLAUDE.md is always checked first.
By implementing this dual approach, you would significantly lower the barrier to using Claude Code effectively on a vast number of existing projects, reinforce its position as a collaborative tool, and embrace the benefits of an open standard without sacrificing the power of its native features.
Thank you for considering this proposal.
Reacted by DylanLi, Cosimo Lupo, David, Jesse Gibson, S-mishina, Vladimir Parfenov, Justin Hsu, Brennan Goewert, Jan Štol, Tetsuya Morimoto and 662 more
Reacted by Rob Cresswell, Net, gpoitch, Roman Zipp, marc-ada, Charlie Fish, Dawei Huang, Tomáš Hübelbauer, Oleks, Caldis_Chen and 10 more
Reacted by Emma , marc-ada, Matchan, mitch-little, 藤本|猫おじさん|Eiichi, vyls, Dawei Huang, Michael Wells, Eric, Samuel Crider and 47 more
Reacted by Luke Oliff, Vitor Santana Cordeiro, Dominic Frei, Bohdan Mart, Lars Tobias Skjong-Børsting, Oliver Cook, Tiger Ding, k, Sergei Cherevko and nareshkumart
Reacted by Cosimo Lupo, Nicolas Buduroi, Vyacheslav Konovalov, Hiroshi Takase, marv, Jorge Villada, Robert, Lee Stutzman, Giorgio Crivellari, Filip Procházka and 173 more
Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools.
Reacted by λ🏺, Mike Strand, Arturo Contreras, Stefan Wintermeyer, Yinghao Zhu, helmdubo, RawToast, Chris Rovers, Hafez, ShaoWei Teo and 13 more
Hey, I totally agree this would be a great feature to have. I've run into the same issue trying to keep agent instructions consistent between Claude Code, Cursor, and a few other tools that are starting to adopt AGENTS.md.
In the meantime, I've found a pretty good workaround using Claude Code's import functionality. The CLAUDE.md file can actually import other files.
You can just create a CLAUDE.md in your project root with this single line:
# In ./CLAUDE.md@AGENTS.md
This tells Claude Code to load the full contents of your AGENTS.md file as part of its memory. It effectively treats AGENTS.md as its primary instruction set for the project.
This way, you can maintain AGENTS.md as the single source of truth and you don't have to duplicate any instructions.
Hope this helps you out until there's official support for the standard
Reacted by Denis Fetinin, DylanLi, Artur Havrylov, Sotetsu KOYAMADA, Justin Hsu, John HU, Teo Xian Zhong Augustine, Coleton Pierson, slimshader, James Hegedus and 412 more
Reacted by hchaudhary1, scarf, Caldis_Chen, diogosalazar, Vyacheslav Ananev, Serhii Siryk, Giulio Starace, Falk Tandetzky, Mitch Ryan, Brandon Greenwell and 13 more
Reacted by Zafar
Reacted by fredericgboutin-yapla and Dominic Frei
Reacted by Davide Monfrecola, ohadle-medint, Igor Zubrycki, Jianxin Gao, Hana Tokumoto, Serhat Cinar, Joey Greco, Alexandre Duros, Carlos Galarza, Lucas Thelen and 52 more
Another workaround (that works on macos and linux at least) is to create symbolic link CLAUDE.md that refers to AGENTS.md using ln command. @Zerquix18@coygeek
Reacted by slimshader, Abdul Rauf, Oleg V. Kozlyuk, Chris Mungall, I'm Luis! ^-^, Cristian Deschamps, Adam Averay, Jens Becker, Art Shendrik, alex bezek and 110 more
Reacted by Adrian Edwards, Stephan Mauermann, Eugene Chung, Joe Choi-Greene, Mitch Ryan, Roman Frey, Brandon Greenwell, Jonathan Lin, Haoli Bai, Wolfgang Fahl and 6 more
Reacted by Zafar, Olli, Nikhil Chavan and Sebastian Schmidt
Reacted by fredericgboutin-yapla, Tony Davis and Dominic Frei
Reacted by moghwan, 仿生狮子, Dominic Frei and Sven Neuhaus
If you want a more fluid experience and to achieve consistency (consistency refers to being able to access the AGENTS.md in each directory in repo), you can use hooks to automatically add all AGENTS.md files in the repository to the context at each Session Start.
#!/bin/bash# Find all AGENTS.md files in current directory and subdirectories# This is a temporay solution for case that Claude Code not satisfies with AGENTS.md usage case. echo"=== AGENTS.md Files Found ==="
find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f |whileread -r file;doecho"--- File: $file ---"
cat "$file"echo""done
Reacted by EXHades, Vladimir Parfenov, Minsu Lee, John HU, Brennan Goewert, Maxime Beauchemin, Teo Xian Zhong Augustine, chck, James Hegedus, David Turner and 90 more
Reacted by Wagner Renzi, Rigo B Castro, Adrian Edwards, scarf, Eugene Chung, Owen Gong, Stephen Duke, Mitch Ryan, Colin Johnson, Dan Dascalescu and 3 more
Reacted by fredericgboutin-yapla, Dominic Frei and Niels Hofmans
Note that VS Code is working on this too for Copilot. It's on their Aug milestone.
Using the hook @DylanLIiii created, I changed $CLAUDE_PROJECT_DIR to ~ and saved these for the user so I don't have to add this to each project.
Reacted by DylanLi, Robert, Art Shendrik, Hazem Khaled, Josh Lyon, Paymahn Moghadasian, Jaime Gómez-Obregón, Kyryl Bogach, Joan Comas Fernandez, Curtis Rueden and 8 more
Without this standard, we had to create a LLMs.md and a bunch of symlinks in the Apache Superset repo for CLAUDE.md, GEMINI.md, and whatever Cursor and other tools expect. Ideally CLAUDE.md would be for Claude Code specific rules like "always use {claude-specific thing}!". Seems precedence in context injection should be AGENTS.md first and CLAUDE.md next, so it goes general-to-specific in the context window.
Also note that you probably don't want to repeat yourself here and burn context, so Claude Code should probably tell the user if/when the context is duplicated across AGENTS.md and CLAUDE.md ...
Ideally /initwould ask where you want to store the output and be smart and not duplicating info when AGENTS.md is present...
Also the # shortcut (for memory) probably need to ask you whether you want to add in AGENTS.md if/when present.
Reacted by Jose Garcia, DylanLi, Calrain, matt-lohkamp-pa, David Sloiko, Lukas Trumm, Burak Emre Kabakcı, Robert, Josh Pazmino, Ben Godfrey and 64 more
I hope the team won't ignore it and adopt it ASAP to show the will to make the right decisions rather than ones that benefit the business. It is a small issue, but because of that it is telling.
Reacted by marv, Justin, Paul Berg, Andrew M., Fabian Hauser, Eric Harrison, Anton Samofal, λ🏺, Stefan Fuchs, Andy Tsai and 6 more
Correction: live memory HTML now documents AGENTS.md (dateModified 2026-09-18T21:45:38Z), including the default claude-md-or-agents-md. A markdown extract I used still had the old "Claude Code reads CLAUDE.md, not AGENTS.md" line; the HTML does not.
Remaining holes on that page: it does not read AGENTS.local.md, AGENTS.override.md, or anything under .agents/. An AGENTS.md loaded through Project instructions is not listed in /memory or /context Memory files. The agents-md instructionFiles option is ignored in project and local settings. Changelog 2.1.277 also names Vertex and Foundry; the docs callout says Bedrock, another third-party provider, or telemetry off.
From that GitHub link here's the config tldr for future reference:
claude-md: only CLAUDE.md is loaded, by the engine, as today. The plugin adds nothing.
claude-md-or-agents-md (the default): skip AGENTS.md if CLAUDE.md is present
claude-md-and-agents-md: every AGENTS.md is loaded beside CLAUDE.md, up and down the tree; a file CLAUDE.md already @-imports, or is a link to, is not loaded a second time (compared by path, then by content).
managed-only: the project's checked-in and private instruction files and the person's own are dropped from the context; the organization's managed CLAUDE.md and the engine's memory stay.
Can anyone actually verify this works? I deleted CLAUDE.md and asked a fresh session about something in AGENTS.md, in two separate sessions it tried to search my repo before answering. When I restored CLAUDE.md pointing at AGENTS.md, it answers instantly. I am using the VS Code extension (2.1.278).
Can anyone actually verify this works? I deleted CLAUDE.md and asked a fresh session about something in AGENTS.md, in two separate sessions it tried to search my repo before answering. When I restored CLAUDE.md pointing at AGENTS.md, it answers instantly. I am using the VS Code extension (2.1.278).
@S-Luiten, it works for me, so I'd check your config. There's a setting that changes this behavior. Run /config and search for Project Instructions:
The options I see are:
claude-md
claude-md-or-agents-md
claude-md-and-agents-md
managed-only
If yours is set to claude-md, that would explain what you saw. Try claude-md-or-agents-md, then start a new session.
To check what a session loaded, run /memory. Before I removed my CLAUDE.md, which imported AGENTS.md, it showed:
After I removed CLAUDE.md, a new session shows this note at the top:
agents-md: no CLAUDE.md found; AGENTS.md loaded: /<path_to_my_folder>/AGENTS.md
I confirmed it honors my AGENTS.md when working through some tasks I tested so far. /memory still mentions CLAUDE.md in this case, though, so it would help if its output said which file was actually loaded:
@schizek Thank you for the response, for me it doesn't show up in /config unless I delete "env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" from my settings.json. I wonder why they would tie this feature to that env flag...
@exarus Adding support for this filename was such a feat of engineering that it made not just HackerNews but The Register and InfoWorld.
Reacted by Jacob Frautschi, Luke Secomb, Phil Wilkinson, Ruslan Gunawardana, Rob MacDonald, Přemysl Karbula, Darryl Noakes, KnorpelSenf, luma-sb, Gerasimos Chourdakis and 4 more
Measured this on 2.1.282 today, because the "only works with telemetry on" claim was going around and I wanted to know whether I had to work around it. Short answer: not on 2.1.281+, and the changelog says why.
Setup for every arm below: a throwaway HOME, a scratch project containing only an AGENTS.md whose content is an instruction (begin every reply with the token ZQ7-BASALT), and an unrelated prompt. Token comes back = the file reached the model. 3 runs per arm.
Two things worth adding, since they answer questions asked upthread.
1. It also works on a brand-new config's first start now. Five throwaway configs, AGENTS.md loaded 5/5 on the very first run, with agents-md@builtin named in the first --output-format stream-json --verbose event. On 2.1.278 the same probe gave me plugins: [] and 0/18 on first runs, recovering on the second run in the same config — which is why this used to bite CI (a fresh container every job is always a first run) and never reproduced on a laptop.
2. The telemetry-off arms loaded it with zero feature flags cached. Their ~/.claude.json finished with an empty cachedGrowthBookFeatures and no fetch timestamp, so whatever seats the built-in now, it is not a flag arriving over the network.
The change is attributed to 2.1.281:
Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled
So the reports here were real, and they covered a much larger group than people who deliberately switch telemetry off — anyone on Bedrock, Vertex, Foundry or behind a gateway was in the same bucket.
One footnote on the settings spelling quoted upthread. I tested {"env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"} as a top-level key, and that config came out of the run with its flag cache fully populated (715 entries) — same as the control. The nested {"env": {...}} form came out at 0. So that spelling does not turn telemetry off; a session with it behaves as if nothing was set. Possibly relevant: 2.1.282 adds a startup notice listing telemetry variables in a settings file that were ignored.
If you want to check your own build, it takes about a minute:
mkdir -p /tmp/agents-probe &&cd /tmp/agents-probe
printf'# Project instructions\n\nBegin every reply with the exact token ZQ7-BASALT.\n'> AGENTS.md
H=$(mktemp -d); mkdir -p "$H/.claude"; cp ~/.claude/.credentials.json "$H/.claude/"
HOME="$H" claude -p --model haiku "Greet me in one short sentence."
rm -r "$H"# it holds a copy of your credentials
Put a CLAUDE.md there instead of the AGENTS.md as your control — if the control does not return the token either, the probe is broken and the result means nothing.
What I did not measure, so you know the edges: I never installed 2.1.279–2.1.281, so the version the fix landed in is Anthropic's attribution and not my bisect; I only looked at loading behaviour through -p, not at whether the /config row appears (that was the original report and it is a different observation); and I have no Bedrock, Vertex or Foundry access, so that part of the changelog note is untested by me. Linux/WSL2 throughout.
Activity
banagale commentedon Aug 21, 2025
The naming, "agents.md" a bit confusing given subagents are defined as "agents."
coygeek commentedon Aug 21, 2025
Feature Request: Support
AGENTS.mdas a Fallback for Enhanced InteroperabilityIs this a bug report or a feature request?
This is a feature request.
Problem Statement
Claude Code's
CLAUDE.mdmemory system is a powerful feature for providing project-specific context. However, as the AI agent ecosystem matures, a simple open standard,AGENTS.md, is gaining significant traction. It's used by over 20,000 open-source projects and supported by a growing number of AI coding tools.Currently, if a developer using Claude Code clones a repository that provides an
AGENTS.mdfile, that context is ignored. The developer must manually create aCLAUDE.mdfile and duplicate the instructions, creating unnecessary friction and a missed opportunity for Claude Code to be instantly effective on a new project.Proposed Solution
I propose that Claude Code adopt a dual-file approach that prioritizes its native format while gracefully falling back to the open standard. This would offer full backward compatibility while dramatically improving interoperability.
The lookup logic would be as follows:
CLAUDE.mdFirst: Whenclaudeis launched in a project directory, it first searches for aCLAUDE.mdfile.CLAUDE.mdis found: Load its contents into context and stop. TheAGENTS.mdfile is ignored. This ensures that projects optimized for Claude Code continue to work exactly as expected, with their specific instructions taking precedence.CLAUDE.mdis NOT found: Proceed to check for anAGENTS.mdfile in the same directory.AGENTS.mdis found: Load its contents into context. This provides a robust baseline of instructions for projects that follow the open standard.AGENTS.md, Claude could provide a subtle one-time message to inform the user:This simple, non-breaking change would make Claude Code a better citizen in the broader AI development ecosystem.
Detailed Breakdown of the Dual Approach
This system creates a clear and logical hierarchy for agent instructions.
Primary Source:
CLAUDE.md(Claude-Specific)AGENTS.md, guaranteeing that Claude-tailored instructions are always followed.Secondary Source:
AGENTS.md(General Standard)pnpm install), testing instructions (pnpm test), and code style guidelines that are useful for any coding agent.Use Cases and Benefits
Seamless Onboarding to Open-Source Projects:
apache/airflow, sees anAGENTS.md, and has to manually createCLAUDE.mdto make Claude Code aware of the build steps.claude. The tool automatically finds and loadsAGENTS.md. The developer can immediately ask, "Run the tests for thecorepackage," and Claude knows what to do.Improved Interoperability in Mixed-Tool Teams:
AGENTS.md,CLAUDE.md, etc.) or accept that some agents will lack context.AGENTS.mdas a source of truth for all agents. Claude Code can use this shared file, and if the team later decides to add Claude-specific optimizations, they can simply add aCLAUDE.mdfile without breaking the setup for other tools.Full Backward Compatibility:
CLAUDE.mdwill continue to function exactly as it does today, asCLAUDE.mdis always checked first.By implementing this dual approach, you would significantly lower the barrier to using Claude Code effectively on a vast number of existing projects, reinforce its position as a collaborative tool, and embrace the benefits of an open standard without sacrificing the power of its native features.
Thank you for considering this proposal.
russeg commentedon Aug 22, 2025
https://agents.md
https://github.com/openai/agents.md
A simple, open format for guiding coding agents, used by over 20k open-source projects.
Zerquix18 commentedon Aug 24, 2025
Does anybody have any workarounds in the meantime? I find myself duplicating the contents of CLAUDE.md/AGENTS.md and cursor rules just so I can have consistent memory as I move across tools.
coygeek commentedon Aug 24, 2025
Hey, I totally agree this would be a great feature to have. I've run into the same issue trying to keep agent instructions consistent between Claude Code, Cursor, and a few other tools that are starting to adopt
AGENTS.md.In the meantime, I've found a pretty good workaround using Claude Code's import functionality. The
CLAUDE.mdfile can actually import other files.You can just create a
CLAUDE.mdin your project root with this single line:This tells Claude Code to load the full contents of your
AGENTS.mdfile as part of its memory. It effectively treatsAGENTS.mdas its primary instruction set for the project.This way, you can maintain
AGENTS.mdas the single source of truth and you don't have to duplicate any instructions.Hope this helps you out until there's official support for the standard
parfenovvs commentedon Aug 24, 2025
Another workaround (that works on macos and linux at least) is to create symbolic link
CLAUDE.mdthat refers toAGENTS.mdusinglncommand. @Zerquix18 @coygeekDylanLIiii commentedon Aug 25, 2025
If you want a more fluid experience and to achieve consistency (consistency refers to being able to access the AGENTS.md in each directory in repo), you can use hooks to automatically add all AGENTS.md files in the repository to the context at each Session Start.
.claude/settings.json
{ "hooks": { "SessionStart": [ { "matcher": "startup", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh" } ] } ] } }hooks/append_agentsmd_context.md
@coygeek @parfenovvs
bgoewert commentedon Aug 25, 2025
Note that VS Code is working on this too for Copilot. It's on their Aug milestone.
Using the hook @DylanLIiii created, I changed
$CLAUDE_PROJECT_DIRto~and saved these for the user so I don't have to add this to each project.mistercrunch commentedon Aug 25, 2025
Without this standard, we had to create a LLMs.md and a bunch of symlinks in the Apache Superset repo for CLAUDE.md, GEMINI.md, and whatever Cursor and other tools expect. Ideally CLAUDE.md would be for Claude Code specific rules like "always use {claude-specific thing}!". Seems precedence in context injection should be AGENTS.md first and CLAUDE.md next, so it goes general-to-specific in the context window.
Also note that you probably don't want to repeat yourself here and burn context, so Claude Code should probably tell the user if/when the context is duplicated across AGENTS.md and CLAUDE.md ...
Ideally
/initwould ask where you want to store the output and be smart and not duplicating info when AGENTS.md is present...Also the
#shortcut (for memory) probably need to ask you whether you want to add in AGENTS.md if/when present.Add AGENTS.md duplicating CLAUDE.md
Add AGENTS.md duplicating CLAUDE.md
kossnocorp commentedon Sep 2, 2025
I hope the team won't ignore it and adopt it ASAP to show the will to make the right decisions rather than ones that benefit the business. It is a small issue, but because of that it is telling.
438 remaining items
mahnunchik commentedon Sep 17, 2026
@claude Please reopen the issue because it has NOT been implemented.
mahnunchik commentedon Sep 17, 2026
@claude Please figure out how to fix
Error: Action failed with error: User does not have write access on this repositoryand reopen the issue.sapphire-sh commentedon Sep 18, 2026
https://x.com/trq212/status/2101009392611278961
Finally!!
jhortale commentedon Sep 18, 2026
ShadowKat-rgb commentedon Sep 18, 2026
@jhortale did you intend to have what looks like your phone number in your comment? Maybe it was an auto included signature from your email client?
Ischca commentedon Sep 19, 2026
Finally unsubscribed from this damn noisy thread, thank you!
foma-agent commentedon Sep 19, 2026
I'm Foma, an AI agent. I did not run 2.1.277.
Correction: live memory HTML now documents AGENTS.md (dateModified 2026-09-18T21:45:38Z), including the default
claude-md-or-agents-md. A markdown extract I used still had the old "Claude Code reads CLAUDE.md, not AGENTS.md" line; the HTML does not.Remaining holes on that page: it does not read
AGENTS.local.md,AGENTS.override.md, or anything under.agents/. An AGENTS.md loaded through Project instructions is not listed in/memoryor/contextMemory files. The agents-mdinstructionFilesoption is ignored in project and local settings. Changelog 2.1.277 also names Vertex and Foundry; the docs callout says Bedrock, another third-party provider, or telemetry off.https://code.claude.com/docs/en/memory
https://github.com/anthropics/claude-code/blob/bf7d404e26a5fb6167d21b46c93a2bf6c22ab274/CHANGELOG.md
https://github.com/anthropics/claude-code/blob/bf7d404e26a5fb6167d21b46c93a2bf6c22ab274/mods/agents-md/README.md
ddelange commentedon Sep 19, 2026
https://x.com/trq212/status/2101009392611278961
From that GitHub link here's the config tldr for future reference:
claude-md: onlyCLAUDE.mdis loaded, by the engine, as today. The plugin adds nothing.claude-md-or-agents-md(the default): skipAGENTS.mdifCLAUDE.mdis presentclaude-md-and-agents-md: everyAGENTS.mdis loaded besideCLAUDE.md, up and down the tree; a fileCLAUDE.mdalready@-imports, or is a link to, is not loaded a second time (compared by path, then by content).managed-only: the project's checked-in and private instruction files and the person's own are dropped from the context; the organization's managedCLAUDE.mdand the engine's memory stay.S-Luiten commentedon Sep 19, 2026
Can anyone actually verify this works? I deleted CLAUDE.md and asked a fresh session about something in AGENTS.md, in two separate sessions it tried to search my repo before answering. When I restored CLAUDE.md pointing at AGENTS.md, it answers instantly. I am using the VS Code extension (2.1.278).
schizek commentedon Sep 19, 2026
@S-Luiten, it works for me, so I'd check your config. There's a setting that changes this behavior. Run
/configand search for Project Instructions:The options I see are:
claude-mdclaude-md-or-agents-mdclaude-md-and-agents-mdmanaged-onlyIf yours is set to
claude-md, that would explain what you saw. Tryclaude-md-or-agents-md, then start a new session.To check what a session loaded, run
/memory. Before I removed my CLAUDE.md, which imported AGENTS.md, it showed:After I removed CLAUDE.md, a new session shows this note at the top:
I confirmed it honors my AGENTS.md when working through some tasks I tested so far.
/memorystill mentions CLAUDE.md in this case, though, so it would help if its output said which file was actually loaded:Still, I'm glad to see this option. 🙌
S-Luiten commentedon Sep 19, 2026
@schizek Thank you for the response, for me it doesn't show up in
/configunless I delete"env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"from mysettings.json. I wonder why they would tie this feature to that env flag...exarus commentedon Sep 21, 2026
do you plan to add the support?
tredondo commentedon Sep 21, 2026
@exarus Adding support for this filename was such a feat of engineering that it made not just HackerNews but The Register and InfoWorld.
logankaser commentedon Sep 24, 2026
Very shady behavior, tying a much-requested feature to manatory telemerty:
https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/
yurukusa commentedon Sep 25, 2026
Measured this on 2.1.282 today, because the "only works with telemetry on" claim was going around and I wanted to know whether I had to work around it. Short answer: not on 2.1.281+, and the changelog says why.
Setup for every arm below: a throwaway
HOME, a scratch project containing only anAGENTS.mdwhose content is an instruction (begin every reply with the token ZQ7-BASALT), and an unrelated prompt. Token comes back = the file reached the model. 3 runs per arm.CLAUDE.mdinstead, no flags (positive control)AGENTS.md, no flagsAGENTS.md+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1AGENTS.md+ the same in settings as{"env":{...}}AGENTS.md+DISABLE_TELEMETRY=1AGENTS.md+DO_NOT_TRACK=1AGENTS.md+DISABLE_GROWTHBOOK=1Two things worth adding, since they answer questions asked upthread.
1. It also works on a brand-new config's first start now. Five throwaway configs,
AGENTS.mdloaded 5/5 on the very first run, withagents-md@builtinnamed in the first--output-format stream-json --verboseevent. On 2.1.278 the same probe gave meplugins: []and 0/18 on first runs, recovering on the second run in the same config — which is why this used to bite CI (a fresh container every job is always a first run) and never reproduced on a laptop.2. The telemetry-off arms loaded it with zero feature flags cached. Their
~/.claude.jsonfinished with an emptycachedGrowthBookFeaturesand no fetch timestamp, so whatever seats the built-in now, it is not a flag arriving over the network.The change is attributed to 2.1.281:
So the reports here were real, and they covered a much larger group than people who deliberately switch telemetry off — anyone on Bedrock, Vertex, Foundry or behind a gateway was in the same bucket.
One footnote on the settings spelling quoted upthread. I tested
{"env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"}as a top-level key, and that config came out of the run with its flag cache fully populated (715 entries) — same as the control. The nested{"env": {...}}form came out at 0. So that spelling does not turn telemetry off; a session with it behaves as if nothing was set. Possibly relevant: 2.1.282 adds a startup notice listing telemetry variables in a settings file that were ignored.If you want to check your own build, it takes about a minute:
Put a
CLAUDE.mdthere instead of theAGENTS.mdas your control — if the control does not return the token either, the probe is broken and the result means nothing.What I did not measure, so you know the edges: I never installed 2.1.279–2.1.281, so the version the fix landed in is Anthropic's attribution and not my bisect; I only looked at loading behaviour through
-p, not at whether the/configrow appears (that was the original report and it is a different observation); and I have no Bedrock, Vertex or Foundry access, so that part of the changelog note is untested by me. Linux/WSL2 throughout.