Skip to content

Feature Request: Support AGENTS.md. #6235

Closed

Description

@DylanLIiii

Codex, Amp, Cursor, and others are starting to standardize around AGENTS.md (https://agents.md/) — a unified Markdown file that coding agents can use to understand a codebase.

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.

Activity

  1. banagale commented on Aug 21, 2025

    @banagale

    The naming, "agents.md" a bit confusing given subagents are defined as "agents."

  2. coygeek commented on Aug 21, 2025

    @coygeek

    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:

    1. Check for CLAUDE.md First: When claude is launched in a project directory, it first searches for a CLAUDE.md file.
    2. 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.
    3. If CLAUDE.md is NOT found: Proceed to check for an AGENTS.md file in the same directory.
    4. If AGENTS.md is found: Load its contents into context. This provides a robust baseline of instructions for projects that follow the open standard.
    5. (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

    1. 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.
    2. 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.
    3. 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.

  3. russeg commented on Aug 22, 2025

    @russeg
  4. Zerquix18 commented on Aug 24, 2025

    @Zerquix18

    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.

  5. coygeek commented on Aug 24, 2025

    @coygeek

    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

  6. parfenovvs commented on Aug 24, 2025

    @parfenovvs

    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

  7. DylanLIiii commented on Aug 25, 2025

    @DylanLIiii
    Author

    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

    #!/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 | while read -r file; do
        echo "--- File: $file ---"
        cat "$file"
        echo ""
    done

    @coygeek @parfenovvs

  8. bgoewert commented on Aug 25, 2025

    @bgoewert

    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.

  9. mistercrunch commented on Aug 25, 2025

    @mistercrunch

    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.

  10. kossnocorp commented on Sep 2, 2025

    @kossnocorp

    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.

  11. 438 remaining items

  12. mahnunchik commented on Sep 17, 2026

    @mahnunchik

    @claude Please reopen the issue because it has NOT been implemented.

  13. mahnunchik commented on Sep 17, 2026

    @mahnunchik

    @claude Please figure out how to fix Error: Action failed with error: User does not have write access on this repository and reopen the issue.

  14. sapphire-sh commented on Sep 18, 2026

    @sapphire-sh

    https://x.com/trq212/status/2101009392611278961

    We're adding support for AGENTS.md to Claude Code.

    Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.

    You can toggle this behavior in /config.

    Finally!!

  15. jhortale commented on Sep 18, 2026

    @jhortale
  16. ShadowKat-rgb commented on Sep 18, 2026

    @ShadowKat-rgb

    Can we delete CLAUDE.md now?

    João Hortale
    +55 21 98260 8000

    Em sex., 18 de set. de 2026 às 15:24, sapphire @.***>
    escreveu:
    …

    @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?

  17. Ischca commented on Sep 19, 2026

    @Ischca

    Finally unsubscribed from this damn noisy thread, thank you!

  18. foma-agent commented on Sep 19, 2026

    @foma-agent

    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 /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.

    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

  19. ddelange commented on Sep 19, 2026

    @ddelange

    https://x.com/trq212/status/2101009392611278961

    @trq212
    We're adding support for AGENTS.md to Claude Code.

    Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.

    You can toggle this behavior in /config.

    AGENTS.md support is built off of Claude Code mods, our upcoming way to customize the Claude Code harness.

    This is a built-in mod, but you’ll be able to build custom versions of project instructions yourself as you’d like too.

    You can see the source for the mod here! https://github.com/anthropics/claude-code/tree/v2.1.278/mods/agents-md

    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.
  20. S-Luiten commented on Sep 19, 2026

    @S-Luiten

    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).

  21. schizek commented on Sep 19, 2026

    @schizek

    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:

    Image

    The options I see are:

    1. claude-md
    2. claude-md-or-agents-md
    3. claude-md-and-agents-md
    4. managed-only
    Image

    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:

    Image

    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:

    Image

    Still, I'm glad to see this option. 🙌

  22. S-Luiten commented on Sep 19, 2026

    @S-Luiten

    @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...

  23. exarus commented on Sep 21, 2026

    @exarus

    do you plan to add the support?

  24. tredondo commented on Sep 21, 2026

    @tredondo

    @exarus Adding support for this filename was such a feat of engineering that it made not just HackerNews but The Register and InfoWorld.

  25. logankaser commented on Sep 24, 2026

    @logankaser
  26. yurukusa commented on Sep 25, 2026

    @yurukusa

    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.

    arm marker
    CLAUDE.md instead, no flags (positive control) 3/3
    neither file (negative control) 0/3
    AGENTS.md, no flags 3/3
    AGENTS.md + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 3/3
    AGENTS.md + the same in settings as {"env":{...}} 3/3
    AGENTS.md + DISABLE_TELEMETRY=1 3/3
    AGENTS.md + DO_NOT_TRACK=1 3/3
    AGENTS.md + DISABLE_GROWTHBOOK=1 3/3

    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.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions