💡 Compliant Claude Sign-In: Avatar-Guided Plan API Credit Claim Replacing Pro/Max Login

[github-actions[bot]]

Summary

TalkTerm's setup screen offers a "Claude Pro/Max" login, and claude-sdk-backend.ts sets forceLoginMethod: 'claudeai' for it. Anthropic's Agent SDK documentation now says plainly that third-party products may not offer claude.ai login unless Anthropic has approved them. A compliant path now exists for exactly these users: since October 7, 2026, Max, Ultra and Team plans include $100–$500 a month in API credits that can be used with the Agent SDK. This idea replaces the subscription login with an avatar-guided flow: link a Console organization, claim the credits, create a workspace with a spend limit, and paste a key.

Market Signal

• Policy, from the Agent SDK overview: "Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Use the API key authentication methods… instead." (code.claude.com/docs/en/agent-sdk/overview)
• A compliant way to pay with a subscription: API credits for Max, Ultra, and Team plans give $100 (Max), $200 (Ultra), or up to $500 pooled (Team) per month. They cover the Claude Agent SDK and the Claude API but not Claude Code. No payment method is needed on Claude Platform. When credits run out, requests stop; nothing is charged to the plan.
• Enforcement is getting more precise: On Oct 20, 2026 the platform added user profiles and organization webhooks that can restrict or ban individual end customers (release notes).
• History: server-side blocks on subscription OAuth in third-party tools started Jan 9, 2026, and the legal page was updated in Feb 2026 (The Register, WinBuzzer). A May 2026 "Agent SDK credit" plan (VentureBeat) was paused on June 15 and replaced by the October API-credit program.

User Signal

• src/renderer/components/setup/ApiKeySetup.tsx offers 'claude-subscription' ("Claude Pro/Max"), and src/main/agent/claude-sdk-backend.ts forces claudeai login in that mode.
• The PRD's API Key Model is BYOK, with keys in the OS keychain (NFR6). The compliant path fits the original design.
• Cost transparency ideas 💡 Live Cost Meter & Avatar-Spoken Budget Guardrails (BYOK Transparency) #69 and 💡 BYOK Cost Intelligence Dashboard: Real-Time Usage Transparency as Competitive Differentiator #411 only work with metered API usage. Credits plus a workspace spend limit make them concrete: "You have $62 of this month's $100 left."

Technical Opportunity

• The AuthMode type in src/shared/types/ports/agent-backend.ts already isolates the choice. This is mostly a setup-flow change in renderer/components/setup/ plus one new error classification.
• Error pipeline: map the documented exhaustion message ("Your credit balance is too low to access the Anthropic API…") to an avatar line ("Your monthly Claude credits ran out. They refresh on the 14th. Want me to show you how to add more?") with recovery options. No raw API text reaches the UI (Hard Rule 5).
• Avatar-guided claim: a step-by-step overlay with deep links (claude.ai → Settings → Billing → API credits → link organization → Console → create workspace with spend limit → create key). The existing safeStorage key path is reused unchanged.
• Migration: on launch, users in claude-subscription mode get a gentle avatar conversation explaining the change, not a hard block.

Assessment

Dimension	Score	Rationale
Feasibility	high	UI flow plus one error mapping. Auth plumbing and key storage already exist.
Impact	high	Removes a policy risk that could get users' own Claude accounts suspended, and turns their existing subscription into the "free" way to run TalkTerm.
Urgency	high	The policy is published and enforcement tooling shipped on Oct 20. Every new install that picks Pro/Max adds exposure.

Adversarial Review

Strongest objection: Pro subscribers, probably the largest group of non-technical Claude users, are not eligible for credits. Creating a Console organization is also new friction for exactly the users TalkTerm targets.

Rebuttal: The current path appears to break the published policy, and the cost of being wrong falls on the user's own account. That trust failure would be far worse than one extra guided step. Pro users get a guided pay-as-you-go key with a workspace spend cap (e.g., $10/month), which is safer than unlimited subscription use and makes the cost meter (#69) honest. Max, Ultra and Team users pay nothing extra. If Anthropic grants TalkTerm explicit approval, the subscription option can come back as a deliberate, documented choice.

Suggested Next Step

1. Ask Anthropic (sales/partner contact) whether TalkTerm can be approved for claude.ai login. Record the answer in the architecture doc.
2. In parallel, write a bmad-quick-spec for the credit-claim setup flow plus the credit-exhausted error classification, with acceptance tests on the setup reducer and ApiKeySetup.
3. Until then, add a warning to the "Claude Pro/Max" option, or hide it behind a flag.