Comment by mpoteat
4 days ago
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.
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.
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?
What if we have it all backwards? What if Claude-speak, as some like to call it, is actually caused by this one dude dictating the documentation?
2 replies →
Out of curiosity, I ran the PDF through pangram and it seemed to flag nearly the entire thing as AI. I recognize these aren't perfect detectors, but they can give signals if nothing else. Perhaps it needs more soul injected!
https://www.pangram.com/history/93f9ec71-f7b3-4680-86b1-ff12...
8 replies →
> Ouch! Much of this verbiage was dictated by me personally; I just have a fairly distinct register some might consider inscrutable.
I do notice that the more Claude-generated stuff I read, the more it creeps into my daily usage, and I suspect I don't read nearly as much of it as an Anthropic Employee would, so I could believe that. Though "much of" isn't the same as "written with zero AI generation/rephrasing/etc."
Anyway, that aside, something I would like to see is an example of something that's possible with this system that isn't, or isn't easily, possible with existing Claude hooks. Right now it reads like "Here's a cool thing! Here's how it works! And here's this other similar system we have! Here's how that works!" But there's no summary of the differences, why I'd use this over regular hooks, and so on. Or at least not that I saw on quick skim, and I'd be looking for that to be mentioned as early as possible, so I know if the rest is worth reading.
Not beating the allegations on "Claude doesn't speak human because Anthropic employees don't speak human."
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.)
2 replies →
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.
1 reply →
It's a register that would be great for some tabletop games or pop science writing, but in this context it could really use a technical editor to aggressively remove phrasing like "keeping the fold neatly uniform" and "affordance surface", as well as change things like "hooks live in a hooks.json file, today of four extant types" into plain technical language ("there are four types of hook that can be defined in hooks.json").
I think the various recent articles about agent output using ASD-STE100 Simplified Technical English are quite pertinent here. For example:
"Agent Skill to Force Docs in ASD-STE100 Simplified Technical English"
https://news.ycombinator.com/item?id=49114639
Your writing is fine, documentation is hard and nobody is perfect at launch. I can all but guarantee I have more editing experience than the commenter and trust me, you’re fine.
I am going to be called on that one, but I have to call on your bullshit here. You didn't write this.
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....
Here's a palatable, clear version:
https://pdfhost.io/v/2CVhPGy9Kw_CLEAR_Function_Hooks_Core_Ar...
I’m curious… would you talk to them like this in person? The only ‘egregious’ thing I read here was your reaction. Maybe you could consider acting more human?
Writing documentation is one of the most often mentioned uses of LLMs. I suppose if Anthropic wouldn't be doing it it would put into question why anyone else would.
> 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.
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.
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.
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.
8 replies →
You sound like my type. hey, wanna come over to myspace so I could twitter your yahoo till you google all over my facebook?
1 reply →
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.
> 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.
6 replies →
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.
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.
22 replies →
> 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?
2 replies →
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.
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.
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.
I always point people back to https://grugbrain.dev.
The worst thing about AI is endless complexity slopification.
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.
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!
2 replies →
> Do you really need a whole plugin system
Vibe-coding gotta vibe-code.
need to, no, but if you put the Ai to task, expect over engineering
I'm not sure why they didn't just extend plugins, but having mod support is definitely a plus for everyone.
AGENTS.md seems to simply showcase what mods are capable of.
We've just had a file called `.rules` that is symlink as `AGENTS.md`, `CLAUDE.md`, etc to support the 3 or so common ones used around our projects.
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`?
Go download the leaked source code from earlier this year, search for all occurrences of the string `CLAUDE.md`, and be horrified.
One line change? Pffft. That means you're still looking at the code, you're behind the times.
Welcome to SWE in 2026
> 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.
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.
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.
> The document format in CLAUDE.md is whatever Anthropic specifies
Q: Do Anthropic actually specify a document format?
2 replies →
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.
>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?
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.
Sounds like you've read the deepseek harness paper.
> The AGENTS.md support was implemented via our new extensibility system for CC, called Mods,
AKA "we need 100~ish files wrtitten in the most horrible Clean Code style replete with no two files agreeing on the same naming of the same feature... to read one of two files, one of which has been a de-facto industry standard for over two years"
Will you extend your plugin to read skills and rules from `.agents`? Or should we write our own plugin/mod for that?
This may or may not be related, but if you're working on CC, who do we have to annoy to make Anthropic stop trying to force use of arbitrary Bash commands instead of the actual tool calls built into the harness? (https://github.com/anthropics/claude-code/issues/90450, https://github.com/anthropics/claude-code/issues/89251, etc) It's deeply infuriating at times that there's this full system of hooks, permissions, etc that's unusable at times because CC keeps trying to make the model not use any of it.
mods seem like a grasp at all the pi and dsh users