You have a Claude Max subscription and you use claude in the terminal every day. Naturally you want Hermes on the same plan: the agent that remembers things across sessions, running on the quota you already pay for. Then the setup wizard asks for an API key, you buy metered credit to get through the door, and by the end of the month you are paying for both — with two separate pools of allowance. That awkward gap now has an official answer: point Hermes at the official claude executable itself.

What the plugin actually does

The plugin is Claude Subscription DirectSDK (Experimental), installable as claude-subscription-directsdk-experimental. It drives the unmodified official Claude Code executable as a request-scoped model client, so the work runs on your Claude Pro/Max subscription — while Hermes keeps its own agent loop: tools, approval policy, compaction, memory and skills all stay on the Hermes side.

The name is slightly misleading. Despite “DirectSDK”, the implementation speaks the native stream-json protocol directly and does not require the Python Agent SDK package. The plugin declares its dependency on the claude binary in plugin.yaml under external_dependencies but holds no credentials of its own — authentication belongs to the official CLI, and the plugin never opens, copies, refreshes or prints its credential files. There is no silent fallback to HTTP plus API key.

What it needs:

• Hermes Agent 0.21.4 or newer (or main at/after 118984d7a02f, the core half in PR #117451). On an older Hermes the plugin fails to load with a clear Failed to load user provider plugin warning instead of half-working.
• Python 3.10+ on Linux, macOS or Windows. Native runs in its own process group and cancellation kills the whole tree, so the node child behind the npm shim never outlives a cancelled request.
• The official Claude Code CLI, installed and logged in: npm install -g @anthropic-ai/claude-code, then claude auth login.

The plugin is explicit about every path where claude is missing: at plugin load it logs one warning and stays registered so setup can explain what is missing; hermes model stops with the install hint and writes nothing to config; a request fails immediately with the same hint instead of a Popen traceback.

Install and select

# 1) the official CLI (the plugin stores no credentials)
npm install -g @anthropic-ai/claude-code
claude auth login

# 2) install from the Hermes plugin catalog (pinned, reviewed)
hermes plugins install claude-subscription-directsdk

# or straight from GitHub (tracks main)
hermes plugins install NousResearch/hermes-plugin-claude-subscription-directsdk

# 3) select it
hermes model          # pick "Claude Subscription DirectSDK (Experimental)"

Per-profile installs go under ~/.hermes/profiles/<profile>/plugins/. The plugin declares kind: model-provider, so provider discovery imports it directly — no plugins.enabled entry required.

For a single run:

hermes --provider claude-subscription-directsdk-experimental -m sonnet

Persistent configuration is the ordinary provider pair:

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

Two environment variables matter in real projects: CLAUDE_CONFIG_DIR (or the plugin-side CLAUDE_SUBSCRIPTION_DIRECTSDK_CONFIG_DIR) to point at a separately managed CLI auth directory, and CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND for a binary outside PATH. One more thing to know: if the launching environment carries an inherited ANTHROPIC_API_KEY, a custom Anthropic endpoint, or a cloud-backend override, the Hermes client path refuses before spawning anything — the error names the conflicting variables without printing their values. Remove those overrides when you want OAuth.

One Hermes call, one upstream request: the admission relay

This is the part worth understanding. Native Claude Code 2.1.263 can attempt extra generations even with --max-turns 1 and HTTP retries disabled. Left alone, a single Hermes call could mean two upstream requests, quietly doubling both usage and cost.

So the plugin puts a request-scoped relay in the middle: it forwards only the first Messages request and rejects subsequent attempts locally. Hermes receives the first completed upstream response with its actual usage and native stop reason, and a blocked native recovery does not turn a completed response into an exception — truncated streams and upstream HTTP errors remain failures.

The qualification numbers are the proof that the admission boundary holds: an integrated subscription-backed review completed seven Hermes calls with exactly seven upstream requests, twelve tool executions and twelve durable tool results. Context grew from 138,498 to 165,697 tokens, follow-up cache reads averaged 97.13%, and native accounting reported $0.8793728 in list-price equivalent.

Isolation is built in the same way: each chat.completions.create starts a fresh process in a private temporary directory with native tools, skills and setting sources disabled; MCP advertises only the current Hermes tool inventory, with inert callbacks and execution denied by native dontAsk; the system prompt and generation fields travel through private files to avoid the OS per-argument length limit. Authentication and identity fields are never replaced.

Billing: list price is not an invoice

The official wording here is deliberately careful, and it is worth keeping verbatim in your head. When every reported model carries costBasis: list and the total is finite and non-negative, Hermes records that amount as an estimated API list-price equivalent — it is not your subscription invoice or an extra-usage charge, it is never marked free or included, and it is never replaced with guessed alias prices. Missing or invalid final accounting stays unknown, and an interrupted request must not be read as free or zero-token work.

Which reduces to two sentences: subscription entitlement and extra-usage settings belong to your account and the native service — disable extra usage in the account if you do not want overage billing; and a native list-price estimate is not proof of a subscription charge.

Two real caching pitfalls (and how they were fixed)

For any “wrap a CLI” design, prompt caching is where it goes wrong. The plugin documents two long-context qualifications, and they are worth reading together.

First: a real Sonnet 5 review task sent 187,049 input tokens on its first request, and the next tool round read only 6,989 of 190,840 input tokens from cache (3.66%), rewriting 183,849 tokens into the one-hour cache. Identical-request testing at 179K tokens had passed — it simply never exercised that replay boundary.

The cause was the native token-budget reminder injected into context: Hermes owns budgets and reconstructs that reminder across the cache boundary during replay, so the prefix stopped being stable. The fix was to disable the native reminder — no extra cache markers, no TTL change. After it: a completed seven-call review with ten real tool executions grew context from 187K to 212K, with follow-up requests averaging 97.99% cache reads (85.45% including the cold start) and $1.1030034 in native list-price accounting.

Read those two together and the takeaway is: the cache can be made to work, and workloads above roughly 187K context are worth measuring before you commit. Also note these are Sonnet 5 results — Fable 5.1 on the same account required paid usage credits and was not exercised.

Boundaries and caveats

• This is a review build, not a full-parity or production-readiness claim. Native Claude Code 2.1.263 is the qualified version; replay acknowledgments and extra-body behaviour are version-sensitive interfaces.
• Tool names map through mcp__hermes__, and original names must be unique ASCII alphanumeric/underscore/hyphen identifiers of at most 50 characters.
• Text streams incrementally, but a complete tool batch is published only after the assistant turn settles (native message_stop, final usage, process exit). Hermes then applies its own hooks, approvals, tools and persistence.
• Native autocompaction is disabled so Hermes owns compaction; that is not the same as parity for every history transformation or cross-model signed replay.
• Auxiliary and fallback routing stay host-owned: configure them explicitly if they must also use the subscription. This provider does not silently change your other selected providers.

The short version

If you have both a Claude Pro/Max subscription and Hermes, this plugin turns “buy a second pool of API credit” into a choice: three install commands, pick the provider, and the rest is the official CLI’s native protocol doing the work. Only two things really need your hands — the extra-usage setting on the account, and your own environment (clear inherited overrides like ANTHROPIC_API_KEY so the client path does not refuse at startup). To see which release carries the core half the plugin depends on, read what v0.21.4 actually shipped; for day-to-day model work, see the hermes model command reference and provider plugin hooks.