NousResearch/hermes-plugin-claude-subscription-directsdk

NousResearch/hermes-plugin-claude-subscription-directsdk

Description: Hermes Agent model-provider plugin: Claude Pro/Max subscription through the official Claude Code CLI (experimental)

Language: Python

License: MIT

Stars: 9

Forks: 0

Open issues: 0

Created: 2026-09-20T19:26:20Z

Pushed: 2026-09-20T23:42:16Z

Default branch: main

Fork: no

Archived: no

README:

Claude Subscription DirectSDK (Experimental) — Hermes plugin


Standalone Hermes Agent model-provider plugin: claude-subscription-directsdk-experimental, displayed as Claude Subscription DirectSDK (Experimental). It drives the unmodified official Claude Code executable as a request-scoped model client for your Claude Pro/Max subscription. Hermes keeps its normal agent loop, tools, approvals and compaction. Despite the name, the implementation speaks native stream-json directly and does not require the Python Agent SDK package.

Requirements

• Hermes Agent 0.21.4 or newer, or main at/after 118984d7a02f (hermes-agent PR #117451, the core half of #105863). On an older Hermes the plugin fails to load with a clear Failed to load user provider plugin warning rather than half-working.
• Python 3.10+ on Linux, macOS or Windows. Native runs in its own process group (POSIX session / Windows CREATE_NEW_PROCESS_GROUP) and cancellation kills the whole tree (killpg / taskkill /T), so the node child behind the npm claude.cmd shim never outlives a cancelled request. The suite runs on all three in CI.
• The official Claude Code CLI, installed and logged in. This plugin has no credentials of its own; everything goes through claude.

The plugin checks for claude at every seam and never guesses:

| When | What happens without claude | | --- | --- | | plugin load | one warning in the log; the provider stays registered so setup can explain what is missing | | hermes model → this provider | the flow stops with the install hint and writes nothing to config | | /model, Desktop/TUI picker | the pinned catalog is listed (no live account picker) | | a request | fails immediately with the install hint instead of a Popen traceback |

Install Claude Code with npm install -g @anthropic-ai/claude-code, or point CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND at the binary if it lives outside PATH. The plugin.yaml declares the same requirement under external_dependencies.

Install

hermes plugins install claude-subscription-directsdk # from the Hermes plugin catalog (pinned, reviewed)
# or straight from GitHub (tracks main):
hermes plugins install NousResearch/hermes-plugin-claude-subscription-directsdk
# or, by hand:
git clone https://github.com/NousResearch/hermes-plugin-claude-subscription-directsdk \
~/.hermes/plugins/claude-subscription-directsdk-experimental

claude auth login
hermes model # pick "Claude Subscription DirectSDK (Experimental)"

Per-profile installs go under ~/.hermes/profiles//plugins/ instead. The plugin declares kind: model-provider, so Hermes' provider discovery imports it directly; no plugins.enabled entry is needed.

Status

Single-request admission is implemented and live-qualified. Native 2.1.263 can attempt extra generations despite --max-turns 1 and disabled HTTP retries. A request-scoped loopback relay now forwards only the first Messages request and rejects subsequent attempts locally. Hermes receives the first completed upstream response, its actual usage and native stop reason; blocked native recovery does not turn a completed response into an exception. Truncated/incomplete streams and upstream HTTP errors remain failures.

The integrated subscription-backed review completed seven Hermes calls with exactly seven upstream requests, twelve Hermes tool executions and twelve durable tool results. Context grew from 138,498 to 165,697 tokens; follow-up cache reads averaged 97.13%. Native accounting reported $0.8793728 in list-price equivalent, not a verified subscription charge. An earlier attempt began at 187K but exceeded the current native route's 200K bound after tools; that incomplete attempt is not counted as a successful review.

A real subscription-backed Hermes task built and tested a CSV auditor. Separate live qualifications exercised streaming tool rounds, restart/resume, host-side denial, authentic steering, cancellation during generation, and a real CLI subagent completion. This is a review build, not a full-parity or production-readiness claim. See the remaining limitations below.

Native Claude Code 2.1.263 is qualified. Replay acknowledgments and extra-body behavior are version-sensitive interfaces, not a public arbitrary-history SDK guarantee. The generic host support (external-process providers, replay carriers, setup gating) lives in Hermes core; this repository is only the provider.

Login and select

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

Authentication belongs to the official CLI. The plugin never opens, copies, refreshes, or prints its credential files. No Hermes API key is required or sent by the plugin. The normal Hermes client path rejects inherited API-key, custom Anthropic endpoint, and cloud-backend overrides before spawning; the error names conflicting environment variables without printing their values. Remove those overrides from the launching environment when selecting OAuth. There is no silent HTTP/API-key fallback in this client.

Subscription entitlement and extra-usage settings still belong to the account and native service. Disable extra usage in the account if you do not want overage billing. A native list-price cost estimate is not proof of a subscription charge.

For a separately CLI-managed auth directory:

CLAUDE_CONFIG_DIR=/path/to/official-cli-config claude auth login
export CLAUDE_SUBSCRIPTION_DIRECTSDK_CONFIG_DIR=/path/to/official-cli-config

An inherited CLAUDE_CONFIG_DIR also works. To select an executable outside PATH, set CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND to its absolute path. There is no unrestricted public CLI-flags setting; isolation and denial flags are plugin-owned. The low-level Python Client(env=...) injection is available for explicitly controlled local fixtures and does not apply the inherited-environment guard. It is not the normal...