After investigating, the @anthropic-ai/claude-agent-sdk has a macOS-
specific upstream bug that breaks subscription auth: 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 spawned CLI then misclassifies the OAuth token
as an API key and bills against API credits.
Changes:
- ClaudeCodeConfig.oauthToken: new optional config field that exports
CLAUDE_CODE_OAUTH_TOKEN before invoking the SDK. Wired up and ready
for when the upstream bug is fixed; currently affected by it on macOS.
- README, JSDoc: clearly document the limitation. API-key mode works
reliably; subscription mode is broken on macOS pending upstream fix.
- billing_error message: explain the bug and recommend ClaudeProvider +
ANTHROPIC_API_KEY as the workaround so users can self-diagnose.
- examples/claude-code.ts: read CLAUDE_CODE_OAUTH_TOKEN from env so the
smoke test attempts the subscription path when configured.
No code changes silently in flight — when the SDK fixes the Keychain
handling, subscribers will Just Work without any code changes here.
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).
