Claude Code reads AGENTS.md only when telemetry is on [fixed]
blog.szypowi.cz
blog.szypowi.cz
The mod is source available here: https://github.com/anthropics/claude-code/tree/main/mods/age...
Apologies again folks, this was a fully human error on my part - I should've found a better way to launch with a kill-switch.
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 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.
You might argue that differences are small or negligible, but that is just an expectation.
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.
Q: Do Anthropic actually specify a document format?
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?
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
The FIRST website, nice.
No the joke is that you need to protect the review server from a runaway humanoid robot pulling the plug on the review server.
Or the opposite, the runaway humanoid robot is controlled by an openclaw server that can't be located and shut down.
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.
Read CLAUDE.md if it doesn't exist read AGENTS.md you don't need to overthink it so much.
And I say this as someone that loves the Unix philosophy dearly.
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...
> Some people might have a different CLAUDE.md and AGENTS.md
How exactly do these two conflict? If you have both, nothing changes.
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.
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.
Instead we get the implicated assertion that users’ existing workflows shouldn’t matter to Anthropic and accusations that someone you don’t agree with is a shill. When called on that you avoided the question.
To answer your question, although it wasn’t directed at me: YES. I want people to be able to discuss that exact issue even if it isn’t personally interesting to me.
Anthropic is the last company I would trust to make any decisions. Look at any discussions surrounding their "Claude is a tiny game engine" idiocy, numerous bugs that a junior can discover, a full "plugin system" in which they neeeed a dozen files in the worst Clean Code manner to read one of two files etc.
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?
> And I say this as someone that loves the Unix philosophy dearly.
Unix way would be just to tell users to `ln -s` and stop bothering with this.
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?
```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
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.
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.
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 workingSeriously, 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.
# Models.Claude\*:
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.
That said, I do find it somewhat funny that Anthropic themselves are falling victim to their own model's tokenmaxxing.
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 kill switch for the change 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.
Vibe-coding gotta vibe-code.
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.
Thanks!
> Are you gating by license or user, or just by percentage of installs?
The worst thing about AI is endless complexity slopification.
AGENTS.md seems to simply showcase what mods are capable of.
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.
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.
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?
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.)
{
"function_hooks": {
"version": 1,
"source_file": "./whatever.ts",
"language": "TypeScript",
"hash": "sha256:abcd..."
}
}
The point here is that there's a world adjacent to but not actually contained within Claude Code in which not everything blindly trusts everything else, and maybe it's time to start remembering some lessons from the 90's on. For example:
- Don't sniff content types and preferably don't infer them from filenames either.
- Don't trust your subresource to arrive intact. Pin those hashes and verify them!
- Leave some room for extensibility.
- Maybe don't require everyone to mix their code with the security policy that controls edits to that code? I realize that anyone cursed with GitHub Actions is forced to violate this rule in the most outrageous ways imaginable, but that doesn't mean that Claude Code needs to follow suit forever. Once there's subresource integrity, the actual subresource can be put somewhere else where it belongs better. If there's "source_file", in the future there can be "source_url" and such without trying to infer it from the formatting of the string.
(I've involved absolutely no AI in the preparation of this comment. I make plenty of use of AI, but I like my brain to stay exercised, and I like to think that I remain MUCH better at this kind of thing than even the best current models.)
https://www.pangram.com/history/93f9ec71-f7b3-4680-86b1-ff12...
The only thing that gets around that is StealthGPT, but it mangles your intent in the output so badly that it's easier to just write the thing yourself.
> A hook is Koa-style middleware: it reifies an endomorphic continuation
> Five forms, each on tool.call;
But on the other hand uses distinctly human phrases like “one may” and “etc./e.g.” that I rarely see LLMs use. Not sure what to think.
I'd love to do some stylometry on this...
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.
"Agent Skill to Force Docs in ASD-STE100 Simplified Technical English"
https://pdfhost.io/v/2CVhPGy9Kw_CLEAR_Function_Hooks_Core_Ar...
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?
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.
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"
Does that apply to WSL? I would assume everyone develops on WSL these days if they have to use Windows, at least...
WSL also has a huge perf hit when you cross FS boundary, but perhaps you have never experienced it, because you said, "Ah, right. Windows..."
But at least you've heard about WSL!
Or maybe you are just another brainwashed person who decided to follow the flock/horde, because OS'es are not about emotions, but about getting stuff done. If you feel emotional about the tool, I have bad news for you, and good news for your future therapist.
Are you alright?
At least make an argument for switching vendors based on the quality or price of their service.
After the last month or so in the Codex app, I was pleased with the Claude app.
It might be a case of the grass always being greener on the other side, but this is what stands out:
After 3-4 hours of usage, the weekly usage limit moved by only 1%.
Compared to Astra where I can watch the limit draining live, this is a great improvement.
I'd estimate it 3x cheaper, and that's with a 450k context limit instead of the 258k in Codex.
So far Opus 5.5 appears less prone to stopping for no apparent reason at checkpoints in the middle of a longer task.
It doesn't open an internal browser with a useless comparison page, where it then proceeds to add notes despite no one having asked for it.
It is a breath of fresh air: I get the response in the chat, while the Codex app recently loves randomly opening artifacts instead.
Opus 5.5 xhigh made great progress on the task, more so than Astra High, but that could be random chance.
Oh, and the 'Auto' mode actually works and does not force me to instead run 'Full access' like in the Codex app, lest it blocks even 'git push'.
I know I know, why are we giving money to trump? Its because he's going to take it anyways so can't we at least apply some window dressing?
I have heard ultra thinking might delegate to worse agents for some of its sub-tasks, but I don't use that much anymore since Astra came out. Just high seems good enough to throw most laundry lists at.
There’s also the fact that LLMs aren’t perfect, and sometimes even the best models act really stupid sometimes.
Same with Anthropic. On top of that Anthropic rarely or ever admits any issues, and even if they do, you get like 6 hours of reset. Rmemeber March?
fuckin laughable, literally invoked a laugh from me in real life.
I hope customers aren't so stupid that they think a chatty developer on twitter/hn/mastodon/screaming-in-the-wind/wherever (or any other public-facing-place) means shit about customer service, and that goes towards ANY company where the primary customer service is an LLM.
Anthropic is the only company where it took (!) 9 weeks (!) to convince to hand over a 4 dollar refund for book-keeping errors on their side that caused an inappropriately early account deactivation due to time zone issues on their end, while all the while telling me that they don't offer refunds. It took stacks of evidence and argument, and that was after spending two weeks in their system trying to convince every level that I was worth a human.
For me personally it'd require Dario to resort to armed mugging to see another buck out of my wallet. I'm not alone.
tl;dr : being able to convince the powers that be on highly active industry forums (hacker news, twitter, mastodon..?) to act right using the power of peer shaming doesn't good customer service make. That said -- I do appreciate the direct response/statement from mpoteat;
..I just don't appreciate the good actions of a decent individual being too broadly interpreted as the do-good customer-centric nature of Anthropic .. an element I do not believe exists there.
I've had to send such messages, but internally at work, not on HN!
Have a great day, human.
Blink twice if you need help
Would be interesting to know how much time you/your team spent on that design decision
You must be baffled by the fact they're fixing it.
"It's already been fixed as part of v2.1.281 releasing today."
IMHO it's worth keeping in mind that Anthropic employees are some of the least likely to casually pass off artificial prose as authentic, given the company's ethos/brand/cover story (depending on how cynical you are). To them this is all getting pretty high stakes pretty damn quickly; based on my usage of full strength Opus 5.5 today, I can't even imagine what working with their full internal stack must feel like. If they were willing to let the machines speak for them, they'd all be melancholically lounging around home by now instead of coming in to work!
...I am refusing to consider the fact that they probably are still WFH because of Salesforce forcing their shared security contractor to strike. Call that a mental health ignorance on my part :)
as i said in another comment. i don't want someone to toy with my software remotely. that seems wrong to me!
i do not like others to decide that they know what is best for me. and then force it on me without my consent.
i will decide if i like your changes. if i do like your fix, i will install it.
in my car, do not remotely turn off my air conditioning. don't turn off my AGENTS.md.
EDIT: i do not control the flags from admin console. holy shit.
It's much preferable to be able to instantly fix it if the rollout of a new feature goes wrong than have everyone who installed the broken version bring stuck with problems until the company realizes the issue and rolls forwards with a fixed version.
I fully believe GP that there was zero intent to gate this behind collecting telemetry. Sounds like a little tech debt and a little oversight, and the simplest explanation is that it is.
It’s not a crazy conspiracy. They messed up, it’s fine.
> claude update Current version: 2.1.280 Checking for updates to latest version... Claude Code is up to date (2.1.280)
Aka: "an issue even a junior would've spotted if we didn't rely on Claude of 100% of our tasks"
https://news.ycombinator.com/item?id=49815363
Nothing to do with AI patches at all, nor was it a bug. It was intentional human behavior, a temporary rollout setting, that seems to have made sense.
But I guess that doesn't fit the "narrative".
"LLMize the succeses, humanize the failures." is the PR strategy at play here. Anything goes well it's because AI did it, anything goes bad it's because a human didn't catch it.
No matter what happens to be the truth, HNers have a cynical narrative to fit it.
People aren't cynical enough here.
for an organization that is being used as a model for new agentic software development practices.... and every software exec on earth is trying to reshape their organizations after - its a pretty stupid bug for a feature that should've been straightforward in the first place + took forever for them to get around to.
its just kind of emblamatic of the rough edges that exist EVEN FOR SIMPLE THINGS whenever human judgement is totally removed the equation.
Oops, easy mistake!
Not sure if they later move the code from inside the flag check to the main code or that they keep the flag check.
But if they would keep all features behind a flag that would not make most sense as you then would have not many features without telemetry.
> Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead
My dumb brain tells me none of this is rolled out progressively (as of that version). You either have it or not.
Anthropic commonly gates behind feature flags that require telemetry until they're "promoted" and defaulted on.
A little bit annoying you can't manually control the flags without telemetry but I think the title is a bit click bait.
To always read both, you have to switch the 'Project instructions' setting to the non-default `claude-md-and-agents-md`.
Just in case anyone is wondering why their AGENTS.md still isn't being read.
If people only glance over the code agents generate for them and don't bother to spend even half a minute thinking through what's actually happening, this is inevitable.
Certainly this kind of things happened before LLMs existed. But I'm not optimistic about the direction of how things are going.
It’s a simple distributed systems problem. Separate the deployment of a new software feature (to umpteen hosts) from the triggering of that software with a lightweight switch.
If someone think that reading AGENTS.md is always benign, because they can’t imagine how it could be a problem…users are very creative.
Not sure what y’all are thinking with these unwritten conspiracy theories that begin and end with “it’s intentional”
https://www.thatprivacyguy.com/blog/anthropic-spyware/
+ not letting users change their email, or remove their payment methods, etc.
which works except that claude uses .skills/synced which is uses to sync changes to skills from claude servers into the skills folder.
every other agent I have used just directly syncs into .skills so it ends up duplicating skills
The same people who've spent years of their career making sure that never happens.
AGI was reached like 2 weeks ago, latest claude 5.x models rule supreme and software engineering is solved?
claude-md-or-agents-md
claude-md-and-agents-md
Claude Code now reads AGENTS.md if there is no Claude.md
So, these tools have a file they want to read in with some configuration.
That filename is hardcoded?
Fucking DOOM had a command line parameter to provide an arbitrary configuration file name!
That's completely irrespective of the fact that you need a feature flag set by remote infrastructure to change a setting of which completely local file to read.
It's weird, I feel like Claude would have tried to make this a configurable setting by default! Is that just not an option in JS land? Not a common pattern to have configuration in the first place? I don't know about that, all the JS based code editors have comprehensive configuration files.
What the hell is going on....
1. really REALLY care what the file name is
2. Can't put in a symlink
3. Don't want to write into that file to look at other files (which is the standard practice of the entire skills framework
4. Cannot even think to ask the model how to come up with many solutions
Then I postulate you should stick to the mobile app, computers are too complex for you.
Please don't do this.
There is nothing ironic about it.
I think the guidelines are a good idea and I would prefer to be in a community where they are upheld rather than one where they are not.
So I politely reminded you about them.
So I am unsure if it is fitting to call it a "closed source" harness.
[0] https://github.com/anthropics/claude-code
Edit: The linked repository does not contain source code for Claude Code, the harness, itself. It only contains the source code for (some) scripts, mods and plugins.
"This repository includes several Claude Code plugins that extend functionality with custom commands and agents. See the plugins directory for detailed documentation on available plugins."
But I'm not a TypeScript guy, so I concede I might be missing something incredibly obvious. I remember there was a leak of the Claude Code source code at one point, and people vibe coding conversions to other languages from the leak, but I don't think the Claude Code harness itself is open source or even source available.
I just read the first line in the README file which says:
> Claude Code is an agentic coding tool ...
and I immediately assumed that this is what this repository hosts.
It claims that it includes plugins but that does not mean it does not include anything else. It also never explicitly claims, as far as I can tell, that it does not hold the source code of Claude Code, the harness, itself.
It is all extremely misleading, in my opinion. Which might be on purpose, unfortunately.
@agents.md
The response as it is now sounds fair. Before that it was not.
As for whatever "had enough" he mentioned, I'm not sure whether he said it on purpose or genuinely misremembered.
Since that's how he remembers it, so be it. I can't be bothered to explain anymore.
Because "Even if this was an honest rollout mistake" this is a new addition, changes meaning quite a bit.
I disagree with what you wrote now partially (your comment on claude), but it does sound fair, and i wouldn't have written what i wrote.