Hermes Agent is everywhere right now. The self-improving agent from Nous Research passed 250,000 GitHub stars.
I keep getting the same question about it: can I run it on my Claude subscription?
Technically, yes. The Hermes Agent Claude integration picks up the login that Claude Code already stored on your machine.
Its documentation describes what happens next in one sentence:
"Hermes routes as Claude Code against your Anthropic account."
Everything in this article hangs on that sentence. Anthropic has a rule for tools that do that, and it is not a grey one.
In April I wrote about the OAuth ban that broke OpenClaw. This is the follow-up, because the same pattern is back with a much bigger audience.
The lesson hasn't moved: that something works technically doesn't mean it's allowed.
What the Hermes Agent Claude integration does with your login
This is not a Hermes Agent vs Claude Code question. The two stack fine. The question is which of them holds your login.
Hermes offers several ways to reach Claude. The one people mean by "use my subscription" is Anthropic OAuth, set up through hermes model.
On that route Hermes doesn't run the Claude Code binary. It makes its own API calls. For credentials, its provider docs say it "prefers Claude Code's own credential store over copying the token into ~/.hermes/.env."
So a login that was issued to Claude Code ends up in a different client. That client then tells Anthropic it is Claude Code.
That isn't my reading of one line in the docs. It is in the code.
On the OAuth route, Hermes's Anthropic adapter sends a claude-code/... user agent. It opens the system prompt with "You are Claude Code, Anthropic's official CLI for Claude."
And it replaces "Hermes Agent" with "Claude Code" and "Nous Research" with "Anthropic" before the request goes out.
According to the docs, the route "only works if you're on a Claude Max plan and have purchased extra usage credits." The docs add that your base Max allowance is not touched, and that Pro subscribers can't use the route.
The code tells a different story about that allowance. More on that below.
Users ran into the extra-usage side early. In Hermes issue #12905, a Max subscriber got "You're out of extra usage" on the first real message.
At that moment the plan showed only 20% of the session quota and 15% of the weekly quota used. Anthropic recognised the traffic as third-party and billed it separately.
Claude extra usage: what Anthropic allows, at its discretion
This is where the debate usually goes wrong. "I pay for extra usage, so it's fine."
Anthropic does bill that route. Here is the full statement an Anthropic spokesperson gave The Register in April:
"Starting April 4, third-party tools will draw from extra usage instead of subscription limits. Using Claude subscriptions with third-party tools isn't permitted under our Terms of Service, and they put an outsized strain on our systems."
The billing change is half of that statement. The other half is that this use isn't permitted.
Anthropic's support page on logging in describes the room it leaves itself. It now calls extra usage "usage credits":
"Anthropic may at its discretion allow paid subscribers who have enabled usage credits to use certain third-party tools to access Anthropic services included in paid subscription plans, but reserves the right to draw use of such third-party tools from usage credits rather than subscription limits."
Look at the words that carry the weight: "may", "at its discretion", "certain third-party tools". That is a tolerance you pay for, not a right.
Anthropic's legal page adds that it may enforce its restrictions without prior notice.
Paying settles who covers the cost. It doesn't settle how the tool presents itself to Anthropic.
Where the line is
The same support page has a second sentence. This one is not discretionary:
"Use of third-party tools that misrepresent their identity to Anthropic's servers, attempt to route third-party traffic against subscription limits, or otherwise violate applicable terms or policies is prohibited and such use may be enforced against."
Put it next to what is in the Hermes repository:
| Anthropic prohibits | Hermes Agent docs and code |
|---|---|
| Tools that "misrepresent their identity to Anthropic's servers" | Docs: "Hermes routes as Claude Code against your Anthropic account". Code: a claude-code/... user agent and a system prompt that opens with "You are Claude Code" |
| Tools that "attempt to route third-party traffic against subscription limits" | Merged #47723 (June 17): "no single-underscore mcp_ tool names on the OAuth wire (plan-limit billing)". Merged 9d3f1de (September 1): "alias session_search/memory OAuth billing-classifier triggers" |
This table is not a verdict on Nous Research. It puts two sets of public sentences side by side.
The code comment above those aliases explains the goal. Anthropic's billing classifier "fingerprints certain Hermes tool schemas/prose as a third-party app and reroutes to the metered extra-usage lane."
So Hermes renames two tools on the OAuth wire only, and maps them back when the response comes in.
That is why the docs and the code disagree. The docs say the base Max allowance isn't used. The code is written to keep requests off the extra-usage lane.
A community pull request, #72173, is still open and goes further: "keep OAuth requests on included subscription billing".
For the builders of such tools, the Claude Code legal page adds one more rule: "developers may not collect, store, or intermediate Claude.ai credentials or session tokens." Sign-in to a Claude account has to complete through Anthropic's own flow.
The bypass layer
Outside the main repository it goes further still. A third-party repository with almost 400 stars describes itself as a "Claude Code OAuth bypass for hermes-agent".
It patches Hermes at startup so its requests pass what the README calls "Anthropic's server-side OAuth content validation".
The file that does the work is named anthropic_billing_bypass.py. According to the README it adds "the billing header signature and system prompt structure the API expects."
I'm not linking it. The file name says enough.
Why does all of this touch the system prompt? Contributors found by A/B testing that the classifier looks at tool names and at the content of the system prompt, not just at the token.
That is described in Hermes issue #72171 and in the adapter's own comments. Anthropic hasn't documented how it decides.
So this works until the next classifier update. That is exactly the gap between can and may.
It has been enforced before. On January 9, Anthropic said it had "tightened our safeguards against spoofing the Claude Code harness", according to VentureBeat.
The same report said some accounts were banned automatically by abuse filters, and that Anthropic was reversing those bans.
In March, OpenCode removed its Anthropic login in a pull request titled "anthropic legal requests".
I haven't seen bans proven as a pattern since then, and I don't need to. A blocked token on the account I work on all day is reason enough.
Nous also ships a CLI route
Next to the OAuth route, Nous Research ships an official plugin: Claude Subscription DirectSDK. It is marked experimental. On credentials it takes the opposite route:
"This plugin has no credentials of its own; everything goes through
claude."
It drives the unmodified Claude Code executable. Per its docs, it "never opens, copies, refreshes, or prints its credential files." Its disclosure says every turn is billed against your Claude subscription's Agent SDK allowance.
On credentials, that is the right direction. It is still not the same as running Claude Code for your own work.
According to its README, Hermes keeps its own agent loop and Claude Code's native tools are switched off. Hermes's prompt and tools are fed in, and a local relay sits between the CLI and Anthropic.
Whether a third-party product may offer that to its users is an open question.
The Agent SDK overview says third-party developers may not offer claude.ai login or rate limits for their products "unless previously approved". I found no approval or partnership for Nous Research.
The legal page does allow an end user to sign in to the unmodified binary with their own subscription. Anthropic's help center says third-party app usage through the Agent SDK still draws from subscription limits. So this one is not settled.
The alternative: Claude Code headless mode
If you want Claude inside another framework for your own work, don't lift the login out of Claude Code. Run Claude Code itself.
Anthropic documents this route. The Agent SDK overview says: "To drive the same agent loop from a language other than Python or TypeScript, run the CLI as a subprocess with the -p flag and --output-format json."
From a shell:
claude -p "Summarize the open issues in this repo" --output-format json | jq -r '.result'The JSON carries the result and a session_id, so you can pick the conversation up later:
sid=$(claude -p "Start a review of src/auth" --output-format json | jq -r '.session_id')
claude -p "Now check the error handling" --resume "$sid"From any framework that can start a process, it becomes a tool function:
import json
import subprocess
def claude_tool(prompt: str, cwd: str, tools: str = "Read,Grep") -> dict:
proc = subprocess.run(
["claude", "-p", prompt,
"--output-format", "json",
"--tools", tools, # which built-in tools exist in this run
"--allowedTools", tools], # and which of them run without a prompt
cwd=cwd, stdin=subprocess.DEVNULL,
capture_output=True, text=True, timeout=600,
)
if proc.returncode != 0:
# failures inside the run land on stdout, bad flags on stderr
raise RuntimeError(proc.stdout.strip() or proc.stderr.strip())
out = json.loads(proc.stdout)
return {"text": out["result"], "session_id": out["session_id"]}Register that as a tool in LangGraph, CrewAI or your own loop. The binary authenticates itself. Your code never holds a token.
This is what I run in my own framework, VNX Orchestration. It spawns claude -p workers, each with explicit --allowedTools and --disallowedTools lists.
When I audited the codebase after the OpenClaw ban, I found zero Anthropic OAuth tokens and zero Anthropic SDK imports. The only thing that talks to Anthropic is Anthropic's own binary.
Two things to know before you script it.
A headless run loads more than you think. Without --bare, claude -p runs the hooks in a project's .claude/settings.json and connects the servers in its .mcp.json. The headless docs say this happens "even in a folder you've never trusted", with no prompt.
My workers run with --strict-mcp-config and an empty MCP config, so only what I pass in connects. That flag doesn't stop project hooks.
The permissions docs list what runs in an untrusted folder under -p, and how to keep each part out. How I enforce that boundary in my own setup is in Claude Code security: what the agent may touch.
The defaults can change. Anthropic recommends --bare for scripted calls and says it "will become the default for -p in a future release."
In bare mode Claude Code "never reads OAuth credentials or the system keychain." When that ships, every headless call on a subscription needs a second look.
Billing almost moved once already. Anthropic announced that from June 15, claude -p and Agent SDK usage would leave plan limits for a separate monthly credit. It paused that on the day.
Its help center now promises: "When we have an update, we'll share it before anything takes effect."
Building something for others? Use an API key
The CLI route is for your own work on your own subscription. The legal page says it directly: "Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Code and the Agent SDK."
For a product or service, Anthropic says developers "should use API key authentication through Claude Console or a supported cloud provider." In practice that is the Agent SDK with your own key, billed per token.
The legal page leaves one narrow door. A platform may run the unmodified Claude Code binary while each end user signs in with their own subscription.
That requires the Commercial Terms and rules out paying for, reselling or intermediating that usage. It is a contract question, not a weekend project.
What I'd tell a Hermes user
- Claude in Hermes without the grey zone: use an
ANTHROPIC_API_KEY. Hermes's own docs point there for anyone without Max plus extra usage. - Already on the OAuth route: you are paying for a tolerance, not a permission. The client still presents itself as Claude Code, and current Hermes code works to stay off the extra-usage lane. Weigh that against the account you depend on.
- Patches that make Hermes look even more like Claude Code: don't install them. Stock Hermes already does part of this on its OAuth route.
- Claude inside your own scripts and agents: spawn the official CLI. It is the route Anthropic documents.
Frequently Asked Questions
Vincent van Deth
AI Strategy & Architecture
I build production systems with AI — and I've spent the last six months figuring out what it actually takes to run them safely at scale.
My focus is AI Strategy & Architecture: designing multi-agent workflows, building governance infrastructure, and helping organisations move from AI experiments to auditable, production-grade systems. I'm the creator of VNX, an open-source governance layer for multi-agent AI that enforces human approval gates, append-only audit trails, and evidence-based task closure.
Based in the Netherlands. I write about what I build — including the failures.