Claude Code HERMES.md Bug: How to Avoid the $200 Charge

The #1 mistake people are making with the HERMES.md story right now: assuming it can’t happen to them because they’ve never used Hermes Agent. Wrong. The trigger is a five-character string sitting in your git commit log – and a coworker who once wrote a markdown doc called HERMES.md is enough to charge your card.

This blew up around April 26 after a Reddit PSA, then jumped to X and Hacker News within hours. GitHub issue #53262 has the full reproducer; issue #53171 has the bisect log. Here’s how to audit your repos in two commands, and what to do if you’ve already been hit.

What actually happened (the 30-second version)

A git repo’s recent commit history containing the case-sensitive string HERMES.md causes Claude Code to route API requests to “extra usage” billing instead of the included Max plan quota (per #53262). One user silently burned through $200 in extra usage credits while their Max 20x plan sat at 13% weekly usage – 86% of prepaid capacity untouched.

The kicker: support initially refused to refund the $200, categorizing it as an un-refundable technical error. After the post hit X and HN, the position flipped. Refunds and free credits – announced by Nous Research’s Teknium on X – would go to all Hermes users or anyone who’d used Claude Code to help develop Hermes Agent.

So the headline is half-resolved. But the underlying detection logic is still live, and the same misleading error message is still firing for unrelated users (more on that below).

Audit your repos in two commands

Run this from any directory containing your active projects:

# Scan all git repos under current dir for the trigger string in commit messages
find . -name .git -type d -prune | while read d; do
 cd "$(dirname "$d")"
 git log --all --pretty=format:'%H %s%n%b' 2>/dev/null | grep -l 'HERMES.md' > /dev/null 
 && echo "HIT: $(pwd)"
 cd - > /dev/null
done

Anything that prints HIT: is at risk the next time you run Claude Code in that repo. The match is case-sensitive – a commit message containing “add HERMES.md” triggers the 400 error (confirmed by the bisect reproducer in issue #53262); “add hermes.md” lowercase succeeds normally. Lowercase variants and partial matches like hermesmd are safe.

The fix – and why deleting the file does nothing

The trigger isn’t the file on disk. It’s the string in commit messages: Claude Code includes recent commits in its system prompt, and something server-side re-routes the request when that string appears (GitHub issue #53171 categorizes this as a content filter false-positive misrouting to the disabled “extra usage” lane). Renaming or deleting HERMES.md from your working tree changes nothing if your git log still mentions it.

Three fixes, ranked by effort. Fastest: git clone --depth=1 <your-repo> into a fresh directory and run Claude Code there – shallow clones don’t carry the full commit history that holds the trigger. More permanent: git rebase -i the offending commits and edit the messages to lowercase or a different name (only viable if you control the repo and rewriting history is acceptable). Third option: just rename the file going forward. The Hermes ecosystem doesn’t require uppercase – hermes.md, hermes-spec.md, anything without the exact substring works.

Pre-commit hook tip: Add a hook that rejects commit messages containing HERMES.md verbatim. One grep -q in .git/hooks/commit-msg prevents a future billing surprise. Run it across your team’s repos – the likely scenario is a teammate writing the doc, not you.

Common pitfalls when diagnosing this yourself

The error in your terminal reads: API Error: 400 "You're out of extra usage. Add more at claude.ai/settings/usage and keep going." Actively misleading. The Max plan has plenty of quota – the request was misrouted, not rejected for overuse.

Because the error blames quota, the natural debugging path takes hours. The original reporter’s path (from issue #53171): move CLAUDE.md → move .claude/ → remove project entry → bisect git history → bisect commit by commit → bisect words. Don’t repeat that. Hit a 400 “out of extra usage” while your dashboard shows capacity? Jump straight to the git log audit above.

A billing classifier reading your commit messages, a file-naming convention from a different AI project, and an error string about quota – none of these have anything to do with each other on paper. The bug only exists because a substring match on what looked like a Hermes doc filename ended up inside the routing logic. That’s the kind of thing that’s obvious in hindsight and invisible before it bites you.

The cross-reference nobody’s making

The same 400 "out of extra usage" error has been hitting a different population of users for weeks, from a completely separate root cause.

Turns out Hermes Agent users on a Max subscription with OAuth credentials get the identical HTTP 400 – “You’re out of extra usage. Add more at claude.ai/settings/usage and keep going” – despite plenty of quota remaining. Third-party OAuth client requests appear to route to a separate extra_usage billing pool, which is effectively empty for most users (NousResearch/hermes-agent issues #6475 and #12905, filed weeks before the HERMES.md PSA went viral).

Two different failure modes, identical client-side error. From your terminal, there’s no way to tell which one you’ve hit. In practice, if the git audit comes back clean and you’re still getting the 400, you’re probably in the OAuth-routing bucket – check whether any third-party tool on your machine has reused your Claude Code OAuth token.

Performance and what “resolved” actually means right now

As of late April 2026, here’s the state of play. Treat all of this as fluid – it’s a live issue.

The April 4 policy itself isn’t the bug – that’s deliberate. Boris Cherny, Head of Claude Code, told TechCrunch that subscriptions weren’t built for the usage patterns of third-party agentic tools, and that those tools would require a separate pay-as-you-go billing path. The HERMES.md flaw is collateral damage from the detection logic that enforces that policy – apparently a substring match on what looked like a Hermes doc filename.

When NOT to bother with this

Claude.ai chat, the Claude desktop app, and direct API key usage aren’t affected. The bug lives specifically in the OAuth subscription path that Claude Code uses – if you’re not running Claude Code, none of this applies to you.

Hobbyists on the $20 Pro plan running light, non-agentic workflows are also unlikely to hit the painful version of this. Extra-usage charges only accrue if you have extra usage enabled and funded in your billing settings. If the toggle is off, the worst case is errored requests – not a charge. Worth checking your Claude billing settings to confirm.

FAQ

I already got charged. Can I actually get the money back?

Yes – but expect to ask twice. The first support response refused, calling it an un-refundable technical error. Reply to that ticket, reference the public refund announcement and GitHub issue #53262, and request escalation.

Why was a string in my git history being read by Claude’s servers in the first place?

Claude Code builds the system prompt it sends to Anthropic from your project’s context – and recent git commit messages are part of that context. So the chain is: your local commit message → packed into the system prompt → matched by a server-side substring filter → request re-routed to the wrong billing lane. Step three is the flaw. Steps one and two are by design and documented behavior. If you think about it, that’s actually a useful feature most of the time – Claude knowing your recent commit history makes code suggestions more relevant. The routing logic that reads it for billing purposes is the part that went wrong.

Is uppercase HERMES.md the only trigger string?

It’s the only one confirmed via bisect. The original reporter narrowed it down to the exact byte sequence HERMES.md – case-sensitive, not a prefix or suffix match. Other all-caps agent doc filenames (AGENTS.md, OPENCLAW.md) haven’t been reproduced as triggers yet. But one confirmed substring rule strongly suggests siblings exist that nobody’s bisected. If you maintain a project with an unusual all-caps markdown filename and start seeing the 400 error, run the audit command above with that string substituted in. And if you find one, filing a GitHub issue with a minimal reproducer would close the open question for everyone.

Next action: run the audit command from the second section against your ~/projects directory right now. If anything prints HIT:, decide whether you’re rewriting history or just renaming the file going forward – and add the pre-commit hook before your team adds another HERMES.md doc.