hermes - 💡(How to fix) Fix [Feature]: Claude Agent SDK model provider with subscription OAuth (Codex-style) [1 participants]

Problem or Use Case

I want to run Hermes with Claude as the model backend while staying on my Claude subscription, but the existing anthropic provider requires a Developer Platform API key and bills separately — so Claude-subscribed users effectively pay twice (subscription + per-token API).

Starting June 15, 2026, Anthropic decouples Agent SDK and claude -p usage from interactive subscription limits and introduces a separate monthly Agent SDK credit:

The credit explicitly covers "third-party apps that authenticate with your Claude subscription through the Agent SDK." Source: Anthropic Help Center.

Today there's no way to route Hermes into that credit — even Pro / Max subscribers must fund an API key on top of their plan. A Claude-subscription-OAuth provider would close the gap, the same way the existing Codex OAuth credential pool already does for OpenAI subscribers.

Proposed Solution

A new model-provider plugin that wraps the Claude Agent SDK with Claude subscription OAuth, mirroring the existing Codex OAuth path. Coexists with the current anthropic (API-key) provider rather than replacing it, so users on the Developer Platform are unaffected.

Plugin layout

• New plugin at plugins/model-providers/claude-agent-sdk/, wrapping claude-agent-sdk (Python) or @anthropic-ai/claude-agent-sdk (TypeScript).
• Either a new ClaudeAgentSdkTransport under agent/transports/, or extend the existing AnthropicTransport to swap auth header / endpoint by credential type — whichever fits the ProviderTransport ABC more cleanly.

Auth integration

• Detect Claude Code OAuth credentials at ~/.claude/, paralleling the existing ~/.codex/auth.json import path.
• Reuse the Codex credential-pool plumbing for refresh, rotation, and stale-token handling.

Config / UX

• New provider option (e.g. claude_subscription) selectable in hermes model, symmetric to the Codex subscription option.
• New env var, e.g. HERMES_CLAUDE_SUBSCRIPTION_AUTH=1, or auto-detect when ~/.claude/ credentials exist and no Anthropic API key is set.
• Surface a docs / UX warning when a subscription provider is selected for shared multi-user deployments — per Anthropic, the credit is "sized for individual experimentation"; production multi-tenant automation should still use API keys.

Open implementation questions

• The Agent SDK ships its own agent loop. Since Hermes is itself an agent, the cleanest integration is likely the SDK's lower-level / non-interactive surface rather than letting both loops fight for control of tool use and context. Worth scoping during design.
• Anthropic's formal terms for subscription auth in third-party Agent SDK apps will be posted when the claim flow opens — worth re-checking against Hermes' usage pattern before merging.

References

• Help Center: https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
• Agent SDK overview: https://code.claude.com/docs/en/agent-sdk/overview
• Claude Agent SDK (Python): https://github.com/anthropics/claude-agent-sdk-python

Alternatives Considered

• Keep the status quo (anthropic provider with API key). Works, but Claude-subscribed users pay twice. The new June 15 credit policy makes this less defensible: there's now a published, supported path for third-party apps to authenticate through the subscription.
• Route Claude via OpenRouter. Adds ~5.5% platform fee on top, still pay-per-token, and doesn't touch the new subscription credit. Useful for multi-provider flexibility, not for cost.
• Switch to Codex / OpenAI subscription via the existing Codex OAuth pool. Already supported and works today, but forces users away from Claude as the backend, which isn't a trade-off Claude-subscription users would want to make.
• Community subscription-auth shims (claude_max, claude-code-router, etc.). Technically bolt-on-able, but lives in ToS gray-area territory and is likely to break as Anthropic tightens auth flows around the formal credit program. A first-class provider plugin is cleaner and more durable.

Feature Type

Other

Scope

None

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)