Hermes Agent With Your Claude or ChatGPT Subscription: Setup and Limits

How to run Hermes on the subscription you already pay for, why limits run out faster than in the app, and when an API key is the better choice.

Checked against Hermes v0.22.5 on 27 October 2026.

The terms question first

Using a consumer subscription inside a third-party agent has been a moving target in 2026, so check the rules before you rely on it.

Here's where Anthropic's help centre stood when we checked on 27 October:

• The Agent SDK, claude -p and third-party apps built on it run against your plan's usage limits.
• Changes Anthropic announced for that usage in May were paused on 15 June, and the page says "nothing has changed for now."
• Since 7 October, Max and Team plans also include monthly API credits that cover the Agent SDK, claude -p and the Claude API.

The DirectSDK plugin goes through the official Claude Code CLI rather than copying your login, which is the route those rules describe. Policies can change at short notice, so read Anthropic's current terms for your plan.

Two ways to use a Claude plan, and they bill differently

Hermes has two Claude subscription routes. Picking the wrong one is the most common billing surprise.

So on Pro, the built-in sign-in simply doesn't work. Hermes's docs are blunt about it: "Pro looks like it should work; it doesn't." Use the plugin, or an API key.

Set up Hermes with your Claude subscription

You need Hermes 0.21.4 or newer and the official Claude Code CLI, logged in. The plugin has no credentials of its own; everything goes through claude.

npm install -g @anthropic-ai/claude-code
hermes plugins install claude-subscription-directsdk
claude auth login
hermes model
# pick "Claude Subscription DirectSDK (Experimental)"

When we installed it on Hermes v0.22.5, the install finished with "Plugin installed but not enabled", even though the plugin's README says model providers don't need enabling. One command fixed it:

hermes plugins enable claude-subscription-directsdk-experimental

To make it your default model, set this in ~/.hermes/config.yaml:

model:
  provider: claude-subscription-directsdk-experimental
  default: sonnet

Two errors we hit during setup

Claude Code not found. With no claude binary available, Hermes stopped before sending anything:

Claude Code is not installed (no `claude` on PATH or in the usual install directories).
Install it with `npm install -g @anthropic-ai/claude-code` or set
CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND to the binary.

An API key in your environment. With ANTHROPIC_API_KEY exported, the plugin refused the request on purpose, so it can never quietly bill your key instead of your plan:

❌ Claude Subscription DirectSDK (Experimental) rejected the request and
retrying won't help:
OAuth provider refuses conflicting native auth/backend overrides:
ANTHROPIC_API_KEY

Here's the part that cost us ten minutes. We unset the key and got the same error again, because the Hermes gateway had already started with the key in its environment. Run hermes gateway stop (or restart) after changing environment variables, then try again.

Why you hit limits so fast

In the Claude app, one message sends your message plus a short history. An agent turn is a different animal.

• Every turn resends the whole working context. In the plugin's own published test, a seven-call code review ran with 138,498 to 165,697 tokens of context per call. At list prices, those seven calls came to $0.88.
• One request becomes many. Hermes may make several model calls per task: tool rounds, summaries and title generation. By default, those side tasks use your main model too, which here means your plan.
• Some models cost extra on some plans. In the plugin's tests, Fable 5.1 answered "requires usage credits" on a Pro plan; Anthropic's plan rules put Fable on pay-as-you-go credits for Pro.
• Old CLI versions reject new models. The plugin needs Claude Code 2.1.280 or newer for Opus 5.5, 2.1.284 for Sonnet 5.5 and 2.1.293 for Haiku 5.5. An older CLI answers with a 400 "does not support this model". Run claude update.

That's why a plan that lasts a week of chatting can run dry in an afternoon of agent work.

Fix the 429 and "usage limit" errors

A 429 here means you hit a plan or session limit. It's not a bug, and retrying won't clear it until the window resets. The plugin passes Claude Code's rate_limit errors through as 429 exactly so Hermes can tell them apart from real failures.

What to do:

• Type /usage in a Hermes chat. With the plugin, it asks Claude Code for your plan limits, so you can see how much is left and when it resets.
• Add a fallback, so Hermes switches instead of stopping: hermes fallback add, or a fallback_providers list in config.yaml pointing at an API-key provider.
• Point side tasks at a cheaper model. In config.yaml, the auxiliary settings let you move summaries and vision off your plan.
• Decide about extra usage. If your Claude account has extra usage turned on, heavy runs can keep going past your limit and bill overage. Turn it off in your Claude account if you'd rather stop.
• After you've fixed the cause, hermes auth reset <provider> clears Hermes's own "exhausted" mark so it tries that credential again.

Already pay for ChatGPT Plus or Pro? Sign in with it on any BetterClaw agent, or use your own key at zero markup. Start your first agent.

Using ChatGPT Plus or Pro with Hermes

This one is built in, with no plugin. Run hermes model and pick ChatGPT or Codex Subscription. Hermes shows a link and a code; you approve it in the browser, and it saves the login in ~/.hermes/auth.json.

A few details from Hermes's docs:

• If your organisation blocks device-code logins, use hermes auth add openai-codex --browser instead. It listens on port 1455, so over SSH you need a tunnel to that port.
• If you already use OpenAI's Codex CLI, Hermes can import its login from ~/.codex/auth.json.
• You get OpenAI's Codex models, with a context window of 272K tokens for most of them.

On limits, OpenAI's help centre says Codex usage counts toward an "agentic usage limit" shared with other ChatGPT agent features, and that bigger, longer tasks use more of it. Hermes's own docs say plainly that how its usage counts against your plan "is not currently documented", so watch your usage page for the first few days.

Hermes also knows the ChatGPT-specific errors. When a model isn't available on a ChatGPT account ("model is not supported when using Codex with a ChatGPT account"), it skips that model and moves on to your fallback rather than failing the whole run.

Subscription vs API key: which costs less?

Here's the honest maths, using Anthropic's API prices on 27 October: Sonnet 5.5 at $2 per million input tokens, $0.10 for cached input and $10 for output.

We assumed a modest agent turn of 20,000 input tokens and 1,000 output tokens, with and without 90% of the input cached.

Compare that with Claude Pro at $20 a month ($17 billed annually) and Max from $100. For light and daily use, a subscription is often the better deal, until you hit its limits. For heavy loops, the plan's limits stop you long before the dollar maths matters, so an API key with caching, or a cheaper model for routine turns, is the reliable choice.

Real agent turns are often far bigger than 20,000 tokens (remember the 138,000-token review), so treat these as a floor, not a quote.

Use your ChatGPT subscription in BetterClaw

If you'd rather not manage CLIs, gateways and environment variables, BetterClaw lets you sign in with ChatGPT Plus or Pro on any agent's Model tab. The models you get match what your ChatGPT plan includes.

You can switch that agent back to your own API key from any of 28+ providers at any time, with zero markup, and give each agent a different model.

If Hermes keeps rejecting your login instead, our Hermes auth error fix covers the sign-in failures.

Your subscription or your key, your choice. BetterClaw: always-on agents, 28+ model providers. Start your first agent.

Frequently Asked Questions

Can I use my Claude subscription with Hermes Agent? Yes. The official experimental "Claude Subscription DirectSDK" plugin runs Hermes turns on a Pro or Max plan through the Claude Code CLI. Hermes's built-in Anthropic sign-in only works on Max with extra usage credits, and only uses those credits.

Why does Hermes give a 429 with my Claude subscription? A 429 means you hit your plan's or session's usage limit. Agent turns resend large contexts and make several model calls per task, so limits run out much faster than in the Claude app. Check /usage, wait for the reset, or add a fallback API-key provider.

Can I use ChatGPT Plus with Hermes? Yes. Run hermes model and choose ChatGPT or Codex Subscription, then approve the device-code login. Hermes uses OpenAI's Codex models, and usage counts toward your plan's agentic usage limit.

Is a subscription cheaper than an API key for agents? For light and daily use, usually yes, as long as you stay within the plan's limits. For heavy agent loops, plan limits run out first, and an API key with prompt caching is more predictable. At Sonnet 5.5 prices, 1,500 modest turns a month cost about $24 to $75 on the API.

Is it allowed to use a Claude subscription in Hermes? Anthropic's help centre, when we checked on 27 October 2026, said the Agent SDK and third-party apps built on it run against your plan's usage limits, and that changes announced in May were paused. The plugin uses the official Claude Code CLI. Rules change, so check Anthropic's current terms for your plan.