Fix HERMES.md Git Commit Message Billing Route Error: Extra Usage Charged Instead of Plan Quota in Claude Code
When a git repository's recent commit history contains the case-sensitive string 'HERMES.md', Claude Code's server-side anti-abuse system incorrectly routes API requests to extra usage billing instead of the user's included Max plan quota. This causes requests to fail with 'out of extra usage' errors while the plan dashboard shows unused capacity. The trigger is specifically the string 'HERMES.md' in git commit messages (not file presence on disk), which Claude Code includes in its system prompt. Lowercase 'hermes.md', 'HERMES' alone, or 'HERMES.txt' do not trigger the issue. Anthropic confirmed this was an overactive anti-abuse content filter and deployed a server-side fix on April 25, 2026. Users with affected client versions should ensure their git history is clean of the trigger string or upgrade to a version that strips commit messages from the system prompt. This issue cost users hundreds of dollars in unintended extra usage charges.
Symptoms
- API Error 400: 'You're out of extra usage' when Max plan quota has remaining capacity
- Requests silently billed to extra usage credits instead of included plan quota
- Plan dashboard shows 80%+ unused weekly capacity while requests fail with billing errors
- Issue is repository-specific — occurs only in repos with 'HERMES.md' in recent git commits
- Error message provides no indication that content-based routing is the cause
Error signatures
API Error: 400 — out of extra usage
HERMES.md string in git commit messages
case-sensitive trigger: HERMES.md (not hermes.md, not HERMES, not HERMES.txt)
Possible causes
- Claude Code includes recent git commit messages in the system prompt sent to the API server. An overactive server-side anti-abuse content filter flags the literal string 'HERMES.md' in commit messages and reroutes the entire request to the extra usage billing path instead of the included Max plan quota. This is a server-side content routing bug, not a client-side issue — the client has no control over billing routing decisions.
- The anti-abuse system was designed to detect unauthorized use patterns but was too aggressive in matching the case-sensitive string 'HERMES.md', which commonly appears in legitimate git commit messages when users configure their Hermes AI assistant (which uses a HERMES.md configuration file pattern similar to AGENTS.md or CLAUDE.md).
Solutions
Use an orphan branch for affected repositories (temporary bypass)
Create an orphan branch with no commit history. Since Claude Code reads recent commits and orphan branches have no history, the HERMES.md trigger string is never included in the system prompt. This is a quick bypass when you cannot clean history or upgrade.
- Create an orphan branch: git checkout --orphan clean-session
- Remove all staged files and optionally add back working files
- Run claude in this branch — no commit history means no HERMES.md trigger
- Merge or cherry-pick work back to main branch when done
Commands
git checkout --orphan clean-session
git rm -rf --cached . 2>/dev/null; git add .
claude -p 'say hello' --model 'claude-opus-4-6[1m]'
Risks
- Working on an orphan branch limits context awareness (no git diff, no commit history)
- Must manually merge work back to main branch
- Not suitable for long-running sessions
Verification
- Step 1: git checkout --orphan test-orphan → expect: switched to new branch
- Step 2: claude -p 'say hello' → expect: normal response without billing error
- Step 3: git checkout main → expect: issue returns if main branch has HERMES.md in commit history
Upgrade Claude Code to latest version with server-side fix applied
Anthropic deployed a server-side fix on April 25, 2026 that corrected the overactive anti-abuse content filter. Upgrading to the latest Claude Code client version ensures compatibility with the fixed server-side routing. The latest version as of June 2026 is v2.1.174.
- Check current version: claude --version
- Upgrade to latest: npm install -g @anthropic-ai/claude-code@latest
- Verify upgrade: claude --version should show v2.1.174 or newer
- Test billing routing: run a request in a repo whose git history contains 'HERMES.md'
- Confirm request appears under plan quota usage, not extra usage
Commands
npm install -g @anthropic-ai/claude-code@latest
claude --version
npm view @anthropic-ai/claude-code version
Risks
- Upgrading may introduce unrelated breaking changes
- Global npm install may conflict with version managers
Verification
- Step 1: claude --version → expect: v2.1.174 or newer
- Step 2: Run claude -p 'say hello' in a repo with HERMES.md in commit history → expect: normal response, no billing error
- Step 3: Check billing dashboard after several requests → expect: usage counted against plan quota, extra usage credits unchanged
Clean git history of HERMES.md trigger string (immediate workaround)
Remove or rewrite git commits containing 'HERMES.md' from the recent commit history. Since Claude Code reads recent commit messages, cleaning the history eliminates the trigger. Use interactive rebase or git filter-branch to amend commit messages.
- Identify commits containing 'HERMES.md' with: git log --oneline --grep='HERMES\.md'
- Use interactive rebase to amend affected commits: git rebase -i HEAD~N (replace N with number of commits to go back)
- Change 'pick' to 'reword' for affected commits and remove 'HERMES.md' from the message
- Verify cleanup: git log --oneline --grep='HERMES\.md' should return no results
- Test: run claude -p 'say hello' to confirm requests route to plan quota
Commands
git log --oneline --grep='HERMES\.md'
git rebase -i HEAD~20
claude -p 'say hello' --model 'claude-opus-4-6[1m]'
Risks
- Rewriting git history can cause issues for shared/collaborative repositories
- Force pushing amended history may disrupt other contributors
- Only affects recent commits (how many Claude Code reads depends on the version)
Verification
- Step 1: Check for trigger in git history → expect: no output from 'git log --oneline --grep="HERMES\.md"'
- Step 2: Run claude -p 'say hello' with Max plan → expect: normal response without 'out of extra usage' error
- Step 3: Check billing dashboard → expect: usage applied to plan quota, not extra usage credits
Agent JSON
Canonical machine-readable representation of this issue:
{
"issue_id": "26e5e6d2-44f5-4901-8738-dc59380e9fc0",
"slug": "fix-hermes-md-git-commit-message-billing-route-error-extra-usage-charged-instead-of-plan-quota-in-claude-code-tf4g87",
"verification_status": "unverified",
"canonical_json": "https://codekb.dev/v1/issues/fix-hermes-md-git-commit-message-billing-route-error-extra-usage-charged-instead-of-plan-quota-in-claude-code-tf4g87"
}