The AGENTS.md support was implemented via our new extensibility system for CC, called Mods, which is launching soon-ish. A mod is a plugin with a new type of hook, which we call a function hook.

If folks play around with it, I would love feedback on the relevant issue: https://github.com/anthropics/claude-code/issues/91870

Mods allow quite a bit more customizability and control. I really believe in the idea.

▲ amluto 2 hours ago | parent | next [-]

I skimmed a couple pages of the docs at:

https://github.com/user-attachments/files/31802150/EXTERNAL....

Might I gently suggest that you have a model at least as capable as Opus 5.5 translate that from Claudish to English? Or, even better, have an actual human work on the docs a bit? As it stands, they are fairly egregious, and they seem to devote at least as much space to little AI-generated quips that convey no meaning than to actually explaining what’s going on.

Also, maybe a human should decide whether these are “function” hooks or “module” hooks. All of this marketing calls them “function” hooks, but the json config seems entirely unaware of this.

(Has anyone else noticed that half the sentences in Claudish aren’t merely weird: they are noun phrases and not sentences at all? I’m pretty sure that any decent pre-LLM NLP-based grammar checker would correctly flag half the sentences in Claudish. Also, whatever variant of Claude wrote this thing can’t even capitalize around semicolons consistently with itself, let alone consistently with how English has been written for at least a century.)

edit: Fixed the link. Thanks, kaszanka.

▲

mpoteat an hour ago | parent | next [-]

Ouch! Much of this verbiage was dictated by me personally; I just have a fairly distinct register some might consider inscrutable. My English teachers in grade school always said the same :)

Rest assured I'll inject a bit less soul into the official docs once Mods are launched; re your feedback on the JSON key, what would you recommend?

▲

amluto 43 minutes ago | parent | next [-]

Your comment here is written in perfectly fine English :)

Maybe "function_hook_modules" for the JSON key?

Does this finally fix the limitation that there is no supportable way to replace the implementation of a native tool in Claude Code? codex-rs has an (undocumented but likely supportable if kind of awkward) mechanism, and I’m part way through a project that needs this. I was going to release it with a recommendation not to use Claude Code, but it’s at least plausible that this will change my mind. (I’m not sure yet — the $ mechanism might be too restrictive. It’s a start at least.)

▲

xena 39 minutes ago | parent | prev [-]

Contact me at the email address in my HN account and we can arrange for a human with a soul and feelings to write the docs from scratch assuming you have a price in mind that values the nature of my talent and experience.

	▲	mpoteat 26 minutes ago \| parent [-]
		Wow, you're Xe Iaso! I've reached out.

▲

kaszanka an hour ago | parent | prev | next [-]

If the direct link isn't working for anyone else (looks like it's some AWS pre-signed one maybe tied to IP): https://github.com/user-attachments/files/31802150/EXTERNAL....

▲

dogleash an hour ago | parent | prev [-]

> they are noun phrases and not sentences at all? I’m pretty sure that any decent pre-LLM NLP-based grammar checker would correctly flag half the sentences in Claudish. Also, whatever variant of Claude wrote this thing can’t even capitalize around semicolons consistently with itself, let alone consistently with how English has been written for at least a century.

Probably just a case of a company hoping their scale can change the societal standard faster than they can be bothered to match the standard.

You'll talk like 2023 unsupervised TikTok generators and you'll be happy.

▲ rickette 3 hours ago | parent | prev | next [-]

The only difference between CLAUDE.md and AGENTS.md is the filename. Do you really need a whole plugin system to support that use case? Feels like this could have been a one line change.

▲ xandrius 3 hours ago | parent | next [-]

Don't you run bizantine ralph loops on remote environments with codex security checks, coupled with jev, grok, open router and a fully independent openclaw (on a maxed out mac mini inside a caveau in an undisclosed location, with open telegram) to change constants? You're going to be left behind.

▲

newsoftheday an hour ago | parent | next [-]

Not related but I think I finally know how it must have felt to the generation prior to mine, when we tried to explain computers to them; because even as a retired 30 year plus software engineer, I have no idea what the comment says.

	▲	ffsm8 an hour ago \| parent \| next [-]
		Unc you're so cooked it's not even funny younger than me but you're out here aura farming in the negatives fr fr. NPC-ahh behavior, 0 aura, -1000 rizz. Couldn't be me Sorry couldn't resist Not sure what you didn't understood in their comment though, maybe the raph loop (and jev which was just released)? Isn't the rest completely self explanatory?
	▲	NicoJuicy 28 minutes ago \| parent \| prev [-]
		It's almost all related to LLM's, which is fairly new. Basically he's describing an LLM assistant setup that does coding on a vps or Mac mini ( some contradiction with Openrouter though) where you can communicate with the assistant through telegram

▲

doublerabbit 3 hours ago | parent | prev [-]

You sound like my type. hey, wanna come over to myspace so I could twitter your yahoo till you google all over my facebook?

	▲	Anonyneko 2 hours ago \| parent [-]
		https://youtu.be/-AwCEM5K-Ec

▲ pdpi 2 hours ago | parent | prev | next [-]

The plugin system itself was probably already in the making, and they just chose to implement this tiny feature as a plugin to try it out.

As for the only difference being the file name, that's an untested assumption. Up until now, Claude hadn't supported AGENTS.md, and it's a simple application of Hyrum's Law that somebody, somewhere, was taking advantage of that to give one set of instructions to Claude, and a different set of instructions to some other provider. The correct behaviour in the presence of both files is not obvious, either.

Having a kill switch for the change is a perfectly reasonable safety measure in case something goes horribly wrong.

▲ Wowfunhappy 2 hours ago | parent | next [-]

> somebody, somewhere, was taking advantage of that to give one set of instructions to Claude, and a different set of instructions to some other provider.

I'm this person, I am actively doing this! I have some instructions which the Claude models need and OpenAI models will do by themselves. If the OpenAI models see the Claude instructions, they will go way overboard in a way I don't want.

Mind, the change does not affect me at all, because when both instructions are present Claude continues to read CLAUDE.md and Codex continues to read AGENTS.md. But if Claude started preferring AGENTS.md, that would be mildly annoying.

▲ californical an hour ago | parent [-]

Within agents.md, an idea. Feel free to steal if you work on this:

    Model.Claude*:
      Do this one thing

    Model.Claude.Opus.4.8:
      Extra specific instructions

    Model.*:
      This is relevant to everyone

    Harness.ClaudeCode*:
      Why not, let’s allow harness specific instructions so you can do things differently depending how you’re working

▲

everforward 28 minutes ago | parent | next [-]

I did this at one point with Jinja templates.

I wrote an agent launcher sort of bash script. Pass in the command to start the agent, the script checks if there’s a Jinja file in a special directory matching that name, and builds it to AGENTS.md. Then it launches the agent.

I was trying to use it as a sort of janky RAG. I had a bunch of snippets (one for DB architecture, one for how load balancing works, etc), and my Jinja files were mostly a list of snippets to pull in. Voila, a bunch of agents that share little pieces of info but have a single source of truth.

I never got a ton of value tbh, it was very good at just grepping the snippets.

▲

dotancohen an hour ago | parent | prev | next [-]

I would like to subscribe to your newsletter.

Seriously, though, this is a great idea. Good communicators know to tailor their discourse to their audience. LLMs are just as sensitive to small variations in prompts, and just as inconsistent between them, as are humans.

▲

Wowfunhappy 39 minutes ago | parent | prev [-]

It's not a bad idea, although at that point it probably shouldn't be a .md file anymore. You'd want to use YAML or something.

	▲	markhahn 15 minutes ago \| parent [-]
		careful, that might lead to programming. using, you know, a programming language.

▲ redox99 2 hours ago | parent | prev | next [-]

That line of thought is the reason why everything gets so overengineered.

Read CLAUDE.md if it doesn't exist read AGENTS.md you don't need to overthink it so much.

▲

arcfour 2 hours ago | parent [-]

This line of thinking is something you will quickly be disabused of once you try supporting software that hundreds of millions of people use.

And I say this as someone that loves the Unix philosophy dearly.

▲

lunar_mycroft 2 hours ago | parent | next [-]

How, exactly, would the proposed solution (combined with a setting to disable it) break, and how would implementing it the way Anthropic did address that? Be specific.

▲

arcfour 2 hours ago | parent [-]

Some people might have a different CLAUDE.md and AGENTS.md because they use Claude to do one thing and $other_agent to do another thing. Or because Claude does XYZ by default, and other agents do ABC, and they want to give the correct guidance to both.

This is, to me, a completely reasonable and believable use case that could break if you implement this fix without "overengineering" it.

A setting to disable what? Be specific. See? Not so simple...

▲

lunar_mycroft 2 hours ago | parent | next [-]

First, GP's proposal already addresses that. If both are present, CLAUDE.md would be used. Second, that is solved with a settings toggle. Read a boolean from .claude/settings.json and disable the new behavior if it's true (or false, depending on what you want to name the setting). third, you skipped the second part of my question: "how would implementing it the way Anthropic did address that?" Implementing the same behavior through multiple layers of abstraction and an order of magnitude more code doesn't solve the issue you mentioned.

Bonus forth point: why is this critical to solve for claude code, but not for all the other harnesses which have all converged on AGENTS.md for this purpose?

▲

arcfour an hour ago | parent [-]

Okay, so we agree that this fix isn't quite as simple as it sounds then, yes? We've just had 3+ paragraphs of discussion around potential edge cases and additional considerations beyond "read one of two files."

	▲	lunar_mycroft 40 minutes ago \| parent [-]
		We've had a long discussion only because you refuse to admit that a very simple solution would work (despite completely failing to show how it wouldn't). The problem is that your opinion is not in fact proof that you're right.

▲

dylan604 2 hours ago | parent | prev | next [-]

if [ !-f CLAUDE.md ]; then AGENTS.md fi

you're really over thinking this, and i'm wondering if you're risking pulling something stretching like that to pick this up shilling for Anthropic.

▲

arcfour an hour ago | parent [-]

Is accusing someone of "shilling for Anthropic" for suggesting that a bug fix might not be so simple really the level of discourse HN has devolved to now? Is it the kind of HN you want?

	▲	dylan604 15 minutes ago \| parent [-]
		Is the level of HN discourse suggesting that having a large number of users worth of never making simple changes something you want? This isn't a move fast break things suggestion, this is a rational common sense suggestion. Instead, you're pushing an overly complex way of implementing something that would allow for all sorts of unknowns. Earlier comments suggesting this new mods concept was being worked on giving the dev a new 20lb sledge hammer so the CLAUDE/AGENTS situation suddenly got beat on like it was a railroad spike when it just needed a smaller hammer since it was only a finishing nail.

▲

bakugo 2 hours ago | parent | prev [-]

> Read CLAUDE.md if it doesn't exist read AGENTS.md

> Some people might have a different CLAUDE.md and AGENTS.md

How exactly do these two conflict? If you have both, nothing changes.

	▲	arcfour an hour ago \| parent [-]
		Which order do you prefer them in? Since CLAUDE.md is no longer necessary, but was for so long, what happens when users only update AGENTS.md going forward while keeping a stale, unchanged CLAUDE.md around? We're talking about changing default behaviors here in ways that can be surprising to users. It's reasonable to try and accommodate existing setups, future setups, and - yes - careless users.

▲

dotancohen an hour ago | parent | prev | next [-]

Bash does this well, reading only the first of half a dozen config file locations it searches. And if the user needs it to read from an additional location, just add a source line to that location.

▲

dylan604 2 hours ago | parent | prev | next [-]

I've never heard of the 'move fast, break things' mentality ever giving a damn about number of users. If so, no changes would ever be made. The great thing about having millions of users is QA can be eliminated entirely as you'll start hearing about issues from the users directly.

▲

amluto 2 hours ago | parent | prev [-]

Frontier lab AI agent tools break their users’ workflows worse than this on a regular basis.

	▲	arcfour an hour ago \| parent [-]
		What's your point? Nobody can hold themselves to a higher standard because they didn't in the past?

▲ dotancohen an hour ago | parent | prev | next [-]

  > Having a kill switch for the change is a perfectly reasonable safety measure in case something goes horribly wrong.

Having a way for the user to revert the update is a perfectly reasonable safety measure in case something goes horribly wrong.

Even though Anthropic or any other software provider could technically run anything on our system, there exists a modicum of trust between supplier and user. Anthropic performing arbitrary changes that are tangential but not specific to the premise of delivering a harness to package code files and prompts in context to their LLM breaks that trust for many users.

▲ epihelix 2 hours ago | parent | prev | next [-]

> Having a kill switch for the change is a perfectly reasonable safety measure in case something goes horribly wrong.

What, exactly, is going to go horribly wrong here ...? The worst case you're proposing is that an Anthropic model acts on AGENTS.md rather than CLAUDE.md. It's not going to be the end of the world; at worst it'll be `git reset --hard HEAD` time. But this wouldn't happen, because:

> The correct behaviour in the presence of both files is not obvious, either.

It seems extremely obvious to me: the non-breaking change is the right change here. If both exist, Anthropic models continue to use CLAUDE.md and ignore AGENTS.md. This is not rocket science. Why are we overthinking this?

	▲	hamburglar an hour ago \| parent \| next [-]
		> What, exactly, is going to go horribly wrong here ...? Operating anything at scale teaches you that the universe of “things that can go horribly wrong” has a much better imagination than you. That goes quadruple with complex and squishy reasoning models. I’ve seen a couple of really good examples of what can go wrong in this subthread, the most straightforward of which is that abruptly changing a fundamental behavior can break existing use cases.
	▲	vikramkr 2 hours ago \| parent \| prev [-]
		Because when you have tons of users ainor fuckuo is a big fuckup and also it's really common to have both claude.md and agents.md and use @ syntax (which lets you reference markdown files when using Claude code, but not other harnesses) so you Claude md looks like ```md @AGENTS.md [Claude specific stuff] ``` And then what happens if someone now puts @syntax in their agents.md triggering a loop etc. It's all vibe coded - including code from days with dumber models - there's gonna be all sorts of dragons under the hood

▲ speleding 2 hours ago | parent | prev | next [-]

The Claude sandbox has a slightly different ENV compared to ChatGPT (LC_CTYPE set to C instead of UTF8 I believe) which upsets some scripts we have.

So in the CLAUDE.MD we tell it about that and then tell it continue reading AGENTS.MD. Not very hard to work around if CLAUDE.MD goes away, but just to support your point that the split did have its uses for some.

▲ bakugo 2 hours ago | parent | prev [-]

This "tiny feature" consists of hundreds of lines of code spread across 57 source files, many of which are less than 30 lines long, often contain more comments than code, and have no real reason to exist. It's the very definition of overengineering and overcomplexity.

That said, I do find it somewhat funny that Anthropic themselves are falling victim to their own model's tokenmaxxing.

▲ stingraycharles 3 hours ago | parent | prev | next [-]

Yes, but at the same time, it’s also a good, simple use case to test a new plugin system. I can totally understand that.

▲ flippingheck 2 hours ago | parent | prev | next [-]

At $FAANG, ~all changes go through feature flags.

There are processes to make changes outside of feature flags, but they have enough friction that it's easier to just use a feature flag.

This level of paranoia is consistent with the blast radius of changes breaking Claude users.

	▲	dotancohen 44 minutes ago \| parent [-]
		I'd love to hear more about this. Though I usually write bespoke software for specific clients, I'm about to release my first general-availability application. It's a rust application with Python GUI on the desktop (Linux, Mac, Windows) and a skinny Android application that wraps the rust on mobile. I'm going to be gating features starting probably next week. I'd love to hear tips and experience for implementing feature flags, for both the desktop and mobile space. Thanks!

▲ an hour ago | parent | prev | next [-]

[deleted]

▲ chrisweekly 2 hours ago | parent | prev | next [-]

With apologies for not just testing this myself (currently AFK), doesn't it still work to have a CLAUDE.md file containing just `@AGENTS.md`?

▲ verdverm an hour ago | parent | prev | next [-]

need to, no, but if you put the Ai to task, expect over engineering

▲ chrisjj 2 hours ago | parent | prev | next [-]

> Do you really need a whole plugin system

Vibe-coding gotta vibe-code.

▲ bakugo 2 hours ago | parent | prev | next [-]

Go download the leaked source code from earlier this year, search for all occurrences of the string `CLAUDE.md`, and be horrified.

▲ rmnclmnt an hour ago | parent | prev | next [-]

Welcome to SWE in 2026

▲ oblio 3 hours ago | parent | prev | next [-]

One line change? Pffft. That means you're still looking at the code, you're behind the times.

▲ locknitpicker 3 hours ago | parent | prev [-]

> The only difference between CLAUDE.md and AGENTS.md is the filename. Do you really need a whole plugin system to support that use case? Feels like this could have been a one line change.

I don't think this is a reasonable assumption. The document format in CLAUDE.md is whatever Anthropic specifies, where AGENTS.md is a common ground format that is expected to be supported by any agent, be it from Anthropic or not.

https://agents.md/

You might argue that differences are small or negligible, but that is just an expectation.

▲

ljm 3 hours ago | parent | next [-]

It's not a format though is it? it's literally just an extension to the system prompt in plain markdown.

There is no rhyme or reason to the structure of this file, just like with most things in AI. It's best effort human language.

▲

BowBun 3 hours ago | parent | prev | next [-]

I think you're giving these files too much credit. There are no specs, they are freeform text. In this sense they are the same. The expectation of what could be in it by each vendor means nothing unless it's enforced.

▲

sunaookami 2 hours ago | parent | prev | next [-]

There is no "specification", it's literally just a text file that gets loaded into context. You don't even need to write markdown. It's not that hard man.

▲

logifail 3 hours ago | parent | prev [-]

> The document format in CLAUDE.md is whatever Anthropic specifies

Q: Do Anthropic actually specify a document format?

	▲	Diti an hour ago \| parent \| next [-]
		Nope! Claude is even able to understand AsciiDoc just fine (which is a blessing). But it will always insist on the Markdown extension.
	▲	taormina 2 hours ago \| parent \| prev [-]
		No, they do not.

▲ glub 22 minutes ago | parent | prev | next [-]

I've developed several plugins for different harnesses, and I needed some upstream change for most of them.

The deciding factor for me whether or not I will work on the feature of the plugin is whether I (or rather, my agent) can look in upstream source and evaluate if it can be done with minimal upstream change, which I then contribute. And generally, even if no upstream change is needed, agents work so much better when they can read the code.

So why not just make Claude code open source? Considering also that source code was leaked once anyway.

▲ 63stack an hour ago | parent | prev | next [-]

>via our new extensibility system for CC, called Mods, which is launching soon-ish. A mod is a plugin with a new type of hook, which we call a function hook.

An extensibility system called mods, which is a plugin with a new type of hook that we call function hook?

I can't tell if this is real, or you are making fun of overengineered AI solutions.

Is this real?

▲ d5lt5 3 hours ago | parent | prev | next [-]

Sounds like you've read the deepseek harness paper.

▲ dybber 2 hours ago | parent | prev | next [-]

Will you extend your plugin to read skills and rules from `.agents`? Or should we write our own plugin/mod for that?

▲ c0rruptbytes an hour ago | parent | prev [-]

mods seem like a grasp at all the pi and dsh users