feat(provider): register `claude-code` as first-class subprocess provider (Claude Max OAuth via local CLI)

[zkhalpey]

Summary

claude-code is currently registered as an alias of anthropic (hermes_cli/providers.py:282, plugins/model-providers/anthropic/__init__.py:44), so provider: claude-code in config.yaml routes to https://api.anthropic.com with API-key/OAuth-token auth. There is no path for the local claude --print subprocess transport that the official Claude Code CLI uses to authenticate against a flat-fee Claude Max plan (Keychain OAuth, no metered key, no API quota wall).

This forces users on Claude Max to either:

1. Set provider: claude-code and silently hit api.anthropic.com with whatever ANTHROPIC_API_KEY/ANTHROPIC_TOKEN/CLAUDE_CODE_OAUTH_TOKEN is in env (metered billing, no Max benefit), or
2. Stand up a local OpenAI-compatible reverse-proxy that shells out to claude --print per request, and point config.yaml at it via a custom claude-code-proxy provider block. This is the workaround most Max users converge on.

Every conversation turn currently logs:

agent.conversation_loop: conversation turn: model=claude-opus-4-7 provider=anthropic
agent.chat_completion_helpers: Streaming failed before delivery: Error code: 400 - "You're out of extra usage..."
agent.conversation_loop: API call failed provider=anthropic base_url=https://api.anthropic.com
agent.chat_completion_helpers: Fallback activated: claude-opus-4-7 → claude-opus-4-7 (claude-code-proxy)

i.e. the primary attempt is a useless 400 round-trip to api.anthropic.com, every turn, on every Max user's gateway.

Proposed change

Register claude-code as a first-class provider with its own profile (not an alias), backed by a subprocess driver around claude --print --output-format stream-json. Sketch:

claude_code = SubprocessProfile(
    name="claude-code",
    api_mode="claude_cli_stream_json",
    binary="claude",
    args=["--print", "--output-format", "stream-json", "--input-format", "stream-json"],
    auth_type="none",  # OAuth is handled by ~/.claude/.credentials.json
    auth_probe=lambda: shutil.which("claude") is not None,
    default_aux_model="claude-haiku-4-5",
)
register_provider(claude_code)

…plus a translator from Claude CLI stream-json → OpenAI SSE chunks with tool_calls deltas so the existing agent loop doesn't need changes.

Why this matters

• Cost: Max users currently waste one failed api.anthropic.com request per turn; some never notice and end up on metered billing for the primary lane.
• Auth hygiene: Removes the need to keep CLAUDE_CODE_OAUTH_TOKEN in env (which currently shadows Keychain OAuth and silently switches to metered).
• UX: Today Max users get cold UX (chat-completions translation only). Native tool_use blocks and 1M-token context would Just Work if Hermes drove the CLI subprocess directly.
• Fallback chain: Allows claude-code (Max OAuth, $0) → anthropic (metered API, capped) as a clean primary/fallback pair instead of users running a private fork or a reverse proxy.

Acceptance criteria

• provider: claude-code in config.yaml resolves to a distinct provider (not aliased to anthropic).
• Requests use the local claude CLI subprocess; api.anthropic.com is not contacted unless provider: anthropic is explicitly set.
• Streaming, tool-use, and 1M context survive the translator.
• hermes doctor reports claude-code as a separate provider with its own auth probe.
• Anthropic plugin keeps claude / claude-oauth aliases (HTTP path), but claude-code is removed from that alias tuple.

Workaround until then

Add a custom proxy provider that shells out to claude --print:

providers:
  claude-code-proxy:
    api_mode: chat_completions
    base_url: http://127.0.0.1:18796/v1
    api_key: dummy-key
model:
  provider: claude-code-proxy
  default: claude-opus-4-7

Happy to upstream the subprocess provider + stream-json→SSE translator as a PR if there's interest.

---

Hermes version: v0.14.0 (2026.5.16)
Filed by: @zkhalpey

[kimsew7-del]

Field report from a Windows Hermes user who already has Claude Code authenticated via Claude Max/OAuth.

The current practical workaround is to keep Hermes as the orchestrator and call Claude Code as an external coding worker instead of trying to route it through the native anthropic API provider.

Observed local working pattern:

claude -p "<task>" \
  --model sonnet \
  --effort low \
  --max-turns 8 \
  --output-format json \
  --allowedTools 'Read,Grep,Glob,LS'

For write-enabled tasks, expand tools only by explicit opt-in, e.g. Edit,Write,Bash(...), and keep a Hermes-side verification step for git diff, tests, and summary.

Recommended product direction:

• Treat claude-code as an external subprocess/SDK/ACP worker lane, not as an alias of anthropic.
• Preserve the user's existing Claude Code OAuth/Max auth path; do not require ANTHROPIC_API_KEY.
• Default to safe/cost-aware settings: Sonnet, low effort, max turns, read-only tools.
• Make writes explicit, auditable, and scoped.
• Let Hermes remain the orchestrator that decides when to delegate code tasks to Claude Code.

Related prior art / ecosystem notes:

• oh-my-claudecode / OMC: Claude Code plugin + multi-agent orchestration layer. Useful prior art for team workflows, but not an API bridge.
• OhMyGPT Claude Code docs: demonstrates ANTHROPIC_BASE_URL provider override for Claude Code. This is provider routing, not Claude Max OAuth reuse.
• Meridian: local Anthropic/OpenAI-compatible bridge built on the official Claude Code SDK. This is the closest prior art for exposing Claude Code/Max access through a compatibility endpoint, while claiming not to extract OAuth tokens or patch binaries.
• LiteLLM Claude Code Max docs: gateway pattern for routing Claude Code traffic through an observability/budget/guardrail layer via header forwarding.
• Superpowers (obra/superpowers): cross-agent software-development methodology/skills framework. Relevant as an optional workflow layer for Claude Code workers: spec first, plan review, TDD, subagent development, review gates. This should be layered on top of a Claude Code worker, not mixed into provider auth.
• gstack (garrytan/gstack): opinionated Claude Code setup with specialist slash-command skills for product, design, engineering review, QA, security, release, docs, and browser workflows. Relevant as another optional workflow preset for Claude Code workers. Some commands assume a full Claude Code session/slash-command environment, so it likely fits interactive/ACP workers better than single-shot claude -p.
• claude-code-reverse / leaked-source archives: useful for understanding CLI internals and failure modes, but should not be used as an implementation dependency.

Suggested non-goals / guardrails:

• No OAuth token extraction.
• No browser session replay.
• No binary patching.
• No leaked-source-derived implementation behavior.
• No silent fallback from Claude Code OAuth/Max to metered Anthropic API billing.

Possible UX shape:

workers:
  claude_code:
    command: claude
    mode: print_json       # or acp / interactive
    model: sonnet
    effort: low
    max_turns: 8
    default_tools: [Read, Grep, Glob, LS]
    write_tools: [Read, Grep, Glob, LS, Edit, Write, Bash]
    workflow_preset: none  # none | superpowers | gstack | custom

This keeps the problem separated cleanly:

1. Transport/auth layer: Claude Code CLI/SDK/ACP worker.
2. Safety/cost layer: tool allowlists, max turns, model/effort defaults, verification.
3. Workflow layer: optional presets such as Superpowers, gstack, or OMC.

That separation would let Hermes support Claude Code users safely without coupling provider auth, coding methodology, and plugin ecosystems into one fragile implementation.

[nsxelent]

Field report — another Windows + Claude Max OAuth user here, adding a data point and a +1 for prioritization.

Confirmed working interim pattern: keep Hermes as the orchestrator and drive Claude Code as an external subprocess coding worker (it uses its own Read/Write/Edit/Bash tools; Hermes verifies the result). Prompt via stdin, not a trailing arg (trailing args after flags get swallowed → "Input must be provided through stdin or as a prompt argument"):

echo '<task>' | claude -p \
  --add-dir "<project root>" \
  --allowedTools 'Read,Write,Edit,Bash' \
  --permission-mode bypassPermissions \
  --max-turns 12 --output-format json

This runs entirely on the Max flat fee ($0 marginal) and works great for the coding-worker lane. --output-format json returns result, is_error, num_turns, and rate_limit_info (handy — overageStatus: rejected means it hard-stops at the ceiling rather than surprise-billing).

Where the gap really bites: using Claude Max as a Hermes main model for normal tool-using agent work. The only path today is a local OpenAI-compatible proxy over claude --print, and every community proxy I've examined (e.g. the popular claude-max-api-proxy fork) drops request.tools on the way in and never emits tool_calls on the way out — so it degrades to chat-only. The agent goes deaf to its own tools (terminal, web, etc.). That's not a proxy bug so much as an impedance mismatch: claude --print is itself an agent harness that wants to execute its own tools, not return tool-call requests for the host to execute.

A first-class ClaudeCodeProvider that parses the native stream-json event stream and translates tool_use blocks → Hermes' internal tool-call deltas (reading OAuth creds from ~/.claude/, no ANTHROPIC_API_KEY) would close this cleanly and remove the fork pressure of everyone rolling their own lossy shim.

Strong +1 on the proposed direction. Happy to test a build on Windows (Claude Code v2.1.x, Max 20x OAuth) if that helps.

[konsisumer]

These issues look like facets of one underlying problem: #33462, #47291, #47638.

They were grouped by a semantic pass as different symptoms of one underlying problem in comp/agent. A single coordinated fix may resolve them together — flagging for visibility; no action has been taken on the individual issues.

Automated root-cause grouping. Reply to correct if these are unrelated.

[teknium1]

Thanks for the detailed transport analysis and the Windows/Max field reports. This is an automated hermes-sweeper review.

• Current main deliberately maps claude-code to the native Anthropic HTTP profile (plugins/model-providers/anthropic/__init__.py:44-52; hermes_cli/providers.py:284-286).
• A distinct claude --print / stream-json translator would be a new in-tree integration with a third-party vendor CLI and provider transport. The standing policy is that new vendor/provider integrations ship as standalone plugins rather than becoming maintained core-tree integrations.
• The repository already supports user-installed model-provider plugins, including overrides of bundled provider names (AGENTS.md:815-831). A standalone Claude Code transport/plugin is the appropriate route for this work.
• The external coding-worker direction discussed by @kimsew7-del and @nsxelent is also already supported by the bundled Claude Code skill (skills/autonomous-ai-agents/claude-code/SKILL.md:16-48, 169-188).

Closing under the in-tree provider-integration policy, not as a judgment on the reported need or implementation quality. A standalone plugin repository can be published for installation under ~/.hermes/plugins/ and promoted in #plugins-skills-and-skins.

---

Closed as not-planned per standing maintainer policy (in-tree-provider-integration). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.