feat: Support Claude Pro/Max subscription as a provider (via Claude Code OAuth)

[Jing-yilin]

Summary

Allow users to drive TrySkills with their existing Claude Pro ($20/mo) or Max ($100-200/mo) subscription, without needing a separate Anthropic API key. This mirrors how Hermes Agent's native anthropic provider works — it reads Claude Code's OAuth credentials directly.

Why

• Largest potential user base: Claude Pro/Max is the most popular AI subscription among developers. Many users have it but do NOT have a pay-per-token Anthropic API key.
• Zero extra cost: Users already paying $20-200/month get to try skills for free — no API credit purchase needed.
• Hermes already supports it natively: hermes chat --provider anthropic auto-detects Claude Code credentials. We just need to wire the auth flow into TrySkills.

How It Works in Hermes Agent

From the Hermes source (auth.py), the Anthropic provider checks credentials in this order:

1. ANTHROPIC_API_KEY — standard pay-per-token key
2. ANTHROPIC_TOKEN — manual OAuth token / setup-token
3. Claude Code credential store — auto-reads from ~/.claude/ credential files (refreshable OAuth tokens from Claude Code CLI)

For TrySkills, we need approach 2 — the user authenticates via OAuth in the browser, and we inject the token into the sandbox.

Technical Design

Authentication Flow

Claude Code uses Anthropic's OAuth with PKCE. The flow for TrySkills:

User selects "Claude Subscription" as provider
    ↓
TrySkills frontend initiates OAuth Authorization Code + PKCE flow
    → Redirect to console.anthropic.com/oauth/authorize
    → User approves access
    → Callback with authorization code
    ↓
TrySkills backend exchanges code for access_token + refresh_token
    (POST console.anthropic.com/oauth/token)
    ↓
Inject credentials into sandbox:
    ~/.claude/ credential files  (so Hermes auto-detects them)
    OR
    ANTHROPIC_TOKEN env var in ~/.hermes/.env
    ↓
Sandbox Hermes config:
    model:
      provider: "anthropic"
      default: "claude-sonnet-4-6"

Key Implementation Details

1. OAuth Client Registration: We need to register TrySkills as an OAuth client with Anthropic, or reuse the Claude Code public client credentials (desktop OAuth clients are not confidential — PKCE provides security, same pattern as Hermes's Google Gemini OAuth).

2. Token Storage: The OAuth token should be stored server-side (encrypted in Convex apiKeys table) and injected into the sandbox at launch time. Unlike API keys which are static, OAuth tokens expire and need refresh.

3. Token Refresh: Hermes Agent handles refresh automatically when it detects Claude Code credentials. We write the full credential set (access_token + refresh_token + expires_at) into the sandbox, and Hermes's built-in refresh logic takes care of the rest.

4. Sandbox Config:

# ~/.hermes/config.yaml
model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

# ~/.hermes/.env
ANTHROPIC_TOKEN=<oauth_access_token>

Provider Registry Entry

// registry.ts
{
  id: "claude-subscription",
  name: "Claude Pro/Max",
  Icon: Anthropic,
  keyPrefix: "",
  keyUrl: "https://claude.ai/settings",
  envVar: "ANTHROPIC_TOKEN",
  authType: "oauth",  // new field to distinguish from API key providers
  models: ["claude-sonnet-4-6", "claude-opus-4-7", "claude-haiku-4-5"],
}

UI Flow

The Config Panel should show two Anthropic options:

• Claude Subscription (OAuth) — "Use your existing Claude Pro/Max subscription"
• Anthropic API (API Key) — "Pay-per-token with an API key"

When "Claude Subscription" is selected, show a "Sign in with Claude" button instead of an API key input field.

Rate Limits

Claude subscription usage through this method is subject to the same rate limits as Claude Code / claude.ai. Heavy agentic use (long tool-calling sessions) may hit these limits faster than typical chat usage.

Risks & Open Questions

Question	Notes
Can we reuse Claude Code's OAuth client_id?	Hermes does this for Google Gemini CLI. Anthropic may or may not allow it — need to check ToS or register our own client.
Will Anthropic restrict third-party OAuth usage?	They temporarily banned OpenClaw's creator in April 2026 after pricing changes (TechCrunch). We should register a proper OAuth app to avoid issues.
Token refresh in long-lived sandboxes	Hermes handles this natively, but sandboxes auto-stop after 30min idle, so this is low risk.

Implementation Phases

1. P0: Register OAuth client with Anthropic + implement browser OAuth flow in frontend
2. P1: Token injection into sandbox (ANTHROPIC_TOKEN in .env or credential files)
3. P2: Token refresh handling (store refresh_token in Convex, refresh before sandbox launch if expired)
4. P3: UI — "Sign in with Claude" button + session indicator

References

• Hermes Agent Anthropic provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers/#anthropic-native
• Hermes auth.py source: PROVIDER_REGISTRY["anthropic"] with api_key_env_vars=("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN")
• Anthropic banned OpenClaw creator: https://techcrunch.com/2026/04/10/anthropic-temporarily-banned-openclaws-creator-from-accessing-claude
• Teknium on OAuth vs API key: https://x.com/Teknium/status/2043476804384727044