PR #12 shipped oauthToken support with optimistic framing, but testing
revealed @anthropic-ai/claude-agent-sdk has a macOS-specific bug: the
SDK isolates CLAUDE_CONFIG_DIR per invocation and tries to copy
~/.claude/.credentials.json, which doesn't exist on macOS (creds live
in the Keychain). The OAuth token gets misclassified as an API key
and requests are billed against API credits instead of the
subscription — subscribers without API credits see "Credit balance is
too low" errors.
Direct `claude -p` works fine, so the upstream SDK is the broken layer.
Changes:
- README Claude Code section: lead with the macOS status note and
point subscribers at ClaudeProvider + ANTHROPIC_API_KEY as the
current workaround.
- JSDoc on ClaudeCodeProvider: same status note.
- billing_error message: explain the bug and recommend the workaround
so users can self-diagnose from the error alone.
No code removal — when the SDK fix lands upstream, oauthToken users
will Just Work without any code changes here.
`claude login` alone does not authorize SDK / non-interactive
(`claude -p`) usage. Anthropic gates that behind a separate long-lived
token minted by `claude setup-token`. Without it, subscription users
hit `billing_error` from the SDK even though interactive Claude Code
works fine.
Changes:
- ClaudeCodeConfig.oauthToken: new optional field. When set, the
provider exports it as CLAUDE_CODE_OAUTH_TOKEN before invoking the
SDK, which makes the SDK bill against the user's Pro/Max
subscription instead of API credits.
- apiKey continues to work for users with a console API key. If both
are present, oauthToken takes precedence.
- billing_error / authentication_failed messages now point users at
`claude setup-token` so the fix is obvious from the error alone.
- README: rewrite the Claude Code section to document both modes and
the `claude setup-token` step explicitly.
- examples/claude-code.ts: read CLAUDE_CODE_OAUTH_TOKEN from env so
the smoke test actually works for subscribers.
Full rewrite focused on what consumers actually need: install, a
working snippet per provider, and the public API surface.
Changes vs the previous version:
- Document ClaudeCodeProvider, including the subscription-via-CLI
auth path that the new provider enables.
- Remove the ProviderRegistry section (the class was removed in R1).
- Drop the stale Provider Comparison and Detailed Capabilities
tables; vendor capabilities and model lists move too fast for a
README to track.
- Remove the inaccurate Zero Dependencies and Comprehensive Testing
claims (post-refactor 44/91 tests need updating).
- Refresh default models (Gemini 1.5 -> 2.5) and the package list to
match the current build.
- Add a brief Architecture note covering the base hooks introduced
in R2 and the OpenWebUI strategy split from R3.
README is 315 lines (was 701).
