feat: support OAuth subscription auth for Claude, ChatGPT Codex, and Gemini

[roninjin10]

Summary

Crush currently supports OAuth-backed auth flows for Copilot and Hyper, plus API-key-based auth for providers like Anthropic, OpenAI, and Gemini. We should add first-class OAuth subscription auth support for:

• Claude / Anthropic subscription auth
• ChatGPT Plus/Pro Codex auth
• Gemini / Google Cloud Code Assist auth

Motivation

Users increasingly authenticate coding agents with subscription-backed OAuth instead of raw API keys. Supporting these flows would let Crush match tools like pi-mono for personal interactive use while preserving API-key flows for production and automation.

Current state

• internal/oauth/ has provider-specific OAuth implementations for Copilot and Hyper.
• internal/config.ProviderConfig already supports oauth tokens alongside api_key.
• internal/config/store.go already persists and refreshes OAuth tokens, but refresh is hard-coded to Copilot and Hyper.
• internal/cmd/login.go and the TUI OAuth dialog are currently oriented around device-code flows.
• internal/config/load.go currently removes Anthropic OAuth config entirely because Claude subscription support is not supported anymore.

Requested outcome

Implement provider-specific OAuth subscription support for Anthropic, OpenAI Codex, and Gemini in a way that:

1. integrates with existing provider config and token refresh plumbing,
2. supports browser callback flows plus manual fallback when necessary,
3. preserves provider-specific metadata where needed (for example Gemini project ID), and
4. surfaces clear UX / billing semantics to users.

[roninjin10]

Concrete implementation plan based on Crush's current architecture and pi-mono's provider-specific OAuth patterns.

Design goals

• Reuse Crush's existing providers.<id>.oauth + providers.<id>.api_key storage shape.
• Generalize refresh and login so OAuth is provider-driven instead of hard-coded to Copilot/Hyper.
• Support browser callback flows with manual fallback for remote/SSH environments.
• Preserve provider-specific metadata for subscription auth.
• Keep API-key auth fully supported and separate from subscription auth.

Proposed implementation

1) Expand the OAuth token model to carry provider-specific metadata

Today internal/oauth/token.go only supports:

• access_token
• refresh_token
• expires_in
• expires_at

That is enough for Copilot/Hyper, but not enough for Gemini and likely not ideal for ChatGPT Codex.

Proposed change:

• extend oauth.Token with a generic metadata bag, e.g. Metadata map[string]any json:"metadata,omitempty"``
• add typed helpers for common lookups to avoid sprinkling casts throughout the codebase
• keep JSON backward compatible so existing Copilot/Hyper tokens still deserialize cleanly

Expected metadata:

• Anthropic: likely none required initially
• OpenAI Codex: account_id
• Gemini / Google Cloud Code Assist: project_id, optionally email

Alternative if we want stricter typing:

• add explicit fields like AccountID, ProjectID, Email
• but a metadata map is probably the least invasive first step

2) Introduce a provider-driven OAuth interface in internal/oauth

Current state:

• Copilot and Hyper have bespoke packages and ad hoc wiring in config store + CLI/TUI

Proposed addition:

• create an internal/oauth/provider.go abstraction along the lines of:
  • ID() string
  • DisplayName() string
  • AuthKind() OAuthKind (device_code vs auth_code_pkce)
  • StartLogin(...)
  • RefreshToken(ctx, token)
  • AccessToken(token) or ApplyToProviderConfig(...)
  • optional PrepareProviderConfig(*config.ProviderConfig, *oauth.Token)

Also add a registry:

• GetProvider(id string) (Provider, bool)
• Providers() []Provider

This lets config, CLI, and TUI stop special-casing exact providers.

3) Add provider packages for Anthropic, OpenAI Codex, and Gemini

Add new packages:

• internal/oauth/anthropic
• internal/oauth/openai
• internal/oauth/google (or googlecodeassist)

Each package should encapsulate:

• auth URL construction
• PKCE generation/state handling
• local callback server startup
• manual paste fallback parsing
• token exchange
• refresh token flow
• provider-specific metadata extraction

Provider-specific notes:

Anthropic

• Authorization code + PKCE flow
• local callback server
• manual redirect/code paste fallback
• refresh support
• access token becomes provider API credential
• add explicit product warning in UX: subscription-backed third-party usage may bill separately from Claude plan limits

OpenAI Codex

• Authorization code + PKCE flow
• local callback server
• manual fallback
• refresh support
• extract/store account_id if useful for diagnostics and future UX
• access token becomes provider API credential

Gemini / Google Cloud Code Assist

• Authorization code + PKCE flow
• local callback server
• manual fallback
• refresh support
• discover/provision project ID and store it in metadata
• likely need provider-specific request shaping because token alone is insufficient

4) Generalize ConfigStore.RefreshOAuthToken

Current state in internal/config/store.go:

• refresh logic is hard-coded to Copilot and Hyper in a switch

Proposed change:

• replace switch with registry lookup
• call provider refresh through the new interface
• persist both:
  • providers.<id>.oauth
  • providers.<id>.api_key
• if provider needs extra config mutation, call provider hook before storing

This is the main enabling change for long-term maintainability.

5) Generalize provider config preparation from OAuth tokens

Current state:

• SetProviderAPIKey copies AccessToken into APIKey
• Copilot additionally calls SetupGitHubCopilot()
• internal/config/load.go has a special-case that deletes Anthropic OAuth config entirely

Proposed change:

• introduce a helper such as applyOAuthToProviderConfig(providerID string, cfg *config.ProviderConfig, token *oauth.Token)
• this helper should:
  • set cfg.OAuthToken
  • derive cfg.APIKey for the provider
  • mutate headers / extra params when needed
  • preserve APIKeyTemplate semantics for non-OAuth providers

Examples:

• Copilot: set bearer token + GitHub Copilot headers
• Anthropic: set API key from access token
• OpenAI Codex: set API key from access token
• Gemini: set API key to a serialized credential payload or, preferably, store provider-specific extra params in config and teach provider execution how to consume them

Important cleanup:

• remove the internal/config/load.go behavior that strips providers.anthropic when OAuth is present

6) Decide how Gemini credentials are passed downstream

This is the biggest integration question.

Crush currently assumes providers mostly authenticate with a string API key plus some extra params. Gemini subscription auth may require both:

• OAuth access token
• project ID

Two viable approaches:

Option A: encode both into APIKey

• mirror pi-mono and serialize {token, projectId} into APIKey
• minimal plumbing changes
• downside: mixes structured auth into a field that is conceptually a plain API key

Option B: use provider config fields intentionally

• keep APIKey as access token
• place project / project_id into ProviderOptions or ExtraParams
• update the Gemini/Vertex request path to consume OAuth token + project ID together

I recommend Option B because it aligns better with Crush's typed config model and will be easier to reason about later.

7) Extend the login command for subscription providers

Current internal/cmd/login.go only supports:

• hyper
• copilot

Proposed CLI UX:

• crush login anthropic
• crush login openai-codex
• crush login gemini

Implementation approach:

• keep device-code logic for providers that use it
• add auth-code + PKCE path for callback-server providers
• if interactive browser callback cannot complete, prompt for pasted redirect URL/code

Nice-to-have UX:

• crush login with provider picker instead of requiring an argument

8) Extend the TUI OAuth dialog model to support auth-code flows

Current internal/ui/dialog/oauth.go is built around device-code UX:

• shows user code
• opens verification URL
• polls for completion

That model works for Copilot/Hyper but not for Claude/OpenAI/Gemini.

Proposed refactor:

• split OAuth UI into two flow types:
  • device-code
  • browser callback / PKCE
• preserve the existing dialog for device-code providers
• add a new callback flow dialog that can:
  • show the URL
  • open the browser
  • wait on local callback
  • offer manual paste fallback
  • show provider-specific guidance/warnings

This can likely share some of the same state machine but should not force callback flows into the device-code abstraction.

9) Surface subscription-specific warnings and affordances

Recommended initial UX:

• Anthropic: warning that third-party subscription usage may bill separately / use extra usage
• OpenAI Codex: clarify this is personal subscription auth, not API platform auth
• Gemini: clarify that paid Google Cloud Code Assist may require GOOGLE_CLOUD_PROJECT or equivalent project selection

Potential UI follow-up:

• distinguish oauth vs api_key auth in settings/provider status screens

10) Preserve existing auto-refresh behavior in coordinator

Current coordinator behavior is already a good fit:

• refresh expired OAuth before requests
• retry once on 401 after refresh

After the provider-registry refactor, this should continue to work unchanged except that refresh becomes provider-driven.

11) Testing plan

Add unit coverage for:

• token serialization/backward compatibility
• provider registry lookup
• provider-specific refresh logic
• config-store refresh via registry
• config load preserving OAuth-backed anthropic instead of deleting it
• provider config application hooks

Add flow tests where practical for:

• callback URL parsing
• state mismatch rejection
• manual paste fallback
• missing code failures
• expiry handling

Add integration tests for:

• crush login anthropic
• crush login openai-codex
• crush login gemini
• coordinator refresh + retry behavior with mocked providers

Suggested rollout phases

Phase 1: Plumbing

• add OAuth provider interface + registry
• extend token model for metadata
• refactor config-store refresh path to use registry
• refactor provider-config application hook

Phase 2: CLI support

• implement Anthropic/OpenAI Codex/Gemini providers
• wire them into crush login
• keep TUI unchanged if necessary for initial delivery by supporting CLI-first login

Phase 3: TUI support

• add callback-flow OAuth dialog
• provider picker / onboarding integration
• add warnings and status messaging

Phase 4: Provider polish

• improve Gemini project selection UX
• expose auth type/status in UI
• consider import/migration helpers if any external tokens can be reused from vendor CLIs

Specific code areas to touch

• internal/oauth/token.go
• internal/oauth/ (new provider interface + registry)
• internal/oauth/anthropic/*
• internal/oauth/openai/*
• internal/oauth/google/*
• internal/config/store.go
• internal/config/load.go
• internal/config/config.go
• internal/cmd/login.go
• internal/ui/dialog/oauth.go or sibling dialog(s)
• provider execution paths for Gemini/Vertex if project-aware OAuth data needs explicit handling

Recommendation

I would ship this CLI-first:

1. build the provider registry + token metadata support
2. add crush login anthropic|openai-codex|gemini
3. ensure request-time refresh works end to end
4. then add TUI polish

That sequence keeps scope under control and de-risks the hardest part first: provider-specific auth and refresh semantics.

[roninjin10]

Additional implementation context that may be useful for whoever picks this up:

Repo-specific details not fully captured above

1. Anthropic OAuth is explicitly stripped today

   • internal/config/load.go:258
   • Current behavior deletes providers.anthropic when oauth is present:
     • // Claude Code subscription is not supported anymore. Remove to show onboarding.
   • So supporting Anthropic OAuth requires intentionally removing/replacing that guard.

2. Coordinator refresh/retry logic already exists

   • internal/agent/coordinator.go:263 and :289
   • Crush already:
     • refreshes OAuth before requests if expired
     • retries once on 401 for OAuth-backed providers
   • So the main missing piece is provider registration + refresh support, not retry behavior.

3. OAuth persistence currently mirrors access token into api_key

   • internal/config/store.go:218-227, :295-307
   • For OAuth providers Crush persists both:
     • providers.<id>.oauth
     • providers.<id>.api_key = access_token
   • New providers should either preserve this behavior or make any Gemini-specific exception explicit.

4. Refresh is hard-coded only for Copilot and Hyper

   • internal/config/store.go:282-288
   • This is the main choke point to generalize first.

5. login is still branded/scoped as platform login

   • internal/cmd/login.go
   • Current copy says:
     • “Login Codeplane to a platform”
     • available platforms are hyper, copilot
   • Adding Anthropic/OpenAI/Gemini likely needs both implementation and CLI copy/UX updates.

6. The current TUI OAuth dialog is device-code-shaped

   • internal/ui/dialog/oauth.go
   • It assumes:
     • user code
     • verification URL
     • polling
   • It is not a generic browser-callback/PKCE UI yet, so trying to force callback flows into it may be awkward.

7. UI changes should follow local UI architecture rules

   • internal/ui/AGENTS.md
   • Relevant constraints:
     • no IO in Update
     • use tea.Cmd
     • avoid unnecessary nested models
     • top-level UI orchestrates dialogs centrally

8. oauth.Token is intentionally minimal today

   • internal/oauth/token.go
   • Fields are only:
     • AccessToken
     • RefreshToken
     • ExpiresIn
     • ExpiresAt
   • So Gemini/OpenAI metadata support needs a real design choice, not just a tiny patch.

9. Copilot already sets a precedent for provider-specific post-auth shaping

   • internal/config/config.go:175
   • SetupGitHubCopilot() injects extra headers
   • That’s a good precedent for provider-specific hooks rather than forcing everything through one generic string field.

10. There are unrelated existing repo diagnostics

    • notably under internal/ui/styles/styles.go
    • Whoever implements this should keep scope tight and avoid trying to fix unrelated project-wide issues.

Suggested handoff prompt for an implementation agent

You are implementing OAuth subscription support in /Users/williamcory/crush.

Context:

• Repo: Go project, module github.com/charmbracelet/crush
• Working tree also contains a cloned reference repo at /Users/williamcory/crush/pi-mono which you can inspect for OAuth patterns, but do not modify.
• Read this issue and the prior implementation-plan comment before coding.
• Follow project instructions in:
  • /Users/williamcory/crush/AGENTS.md
  • /Users/williamcory/crush/internal/ui/AGENTS.md if you touch TUI code

Goal:
Implement the groundwork for OAuth subscription auth for:

• Anthropic / Claude
• OpenAI Codex / ChatGPT Plus/Pro
• Gemini / Google Cloud Code Assist

Important repo-specific facts:

1. Crush already has OAuth token storage in internal/config.ProviderConfig via OAuthToken *oauth.Token.
2. Crush already persists OAuth tokens and mirrors access token into providers.<id>.api_key.
3. Crush already refreshes OAuth before requests and retries once on 401 in internal/agent/coordinator.go.
4. The main missing piece is that refresh and login are hard-coded only for Copilot and Hyper.
5. internal/config/load.go currently explicitly deletes Anthropic OAuth config:
   • // Claude Code subscription is not supported anymore. Remove to show onboarding.
   • That behavior must be removed/replaced for Anthropic OAuth support to work.
6. internal/ui/dialog/oauth.go is device-code specific today; do not assume it cleanly supports PKCE browser callback flows.
7. Existing repo has unrelated diagnostics in internal/ui/styles/styles.go; do not broaden scope trying to fix unrelated issues.

Reference patterns to study:

• Crush:
  • internal/oauth/token.go
  • internal/oauth/copilot/*
  • internal/oauth/hyper/*
  • internal/config/store.go
  • internal/config/load.go
  • internal/cmd/login.go
  • internal/ui/dialog/oauth.go
  • internal/agent/coordinator.go
• pi-mono:
  • pi-mono/packages/ai/src/utils/oauth/index.ts
  • pi-mono/packages/ai/src/utils/oauth/anthropic.ts
  • pi-mono/packages/ai/src/utils/oauth/openai-codex.ts
  • pi-mono/packages/ai/src/utils/oauth/google-gemini-cli.ts
  • pi-mono/packages/coding-agent/docs/providers.md

Recommended scope for this implementation pass:

1. Build the shared plumbing first.
2. Prefer CLI-first support before full TUI callback-flow support.
3. Keep the change set focused and shippable.

Suggested implementation plan:

1. Generalize OAuth provider handling in internal/oauth/:
   • add a provider interface/registry so refresh/login are provider-driven rather than switch-based.
2. Extend internal/oauth.Token or add an adjacent metadata mechanism so provider-specific fields can be stored:
   • OpenAI Codex: account_id
   • Gemini: project_id, maybe email
3. Refactor internal/config/store.go:
   • replace hard-coded refresh switch with registry lookup
   • preserve existing persistence behavior unless a provider needs special handling
4. Refactor provider-config application logic:
   • centralize how OAuth token -> provider config/API key/headers/extra params is derived
   • preserve Copilot’s extra header setup
   • remove the Anthropic OAuth stripping behavior in internal/config/load.go
5. Add provider packages for:
   • internal/oauth/anthropic
   • internal/oauth/openai or internal/oauth/openaicodex
   • internal/oauth/google or internal/oauth/googlecodeassist
6. Add CLI login support in internal/cmd/login.go:
   • crush login anthropic
   • crush login openai-codex
   • crush login gemini
   • support local callback server + manual paste fallback
7. Only if time/scope allow, start adapting TUI flows; otherwise leave a clear seam/TODO for later.

Gemini-specific guidance:

• This is the trickiest integration.
• Avoid jamming structured {token, projectId} JSON into a plain API key unless absolutely necessary.
• Prefer using ProviderOptions / ExtraParams / provider-specific config shaping if the existing provider execution path allows it.
• If the current provider stack fundamentally expects only a string key, document the compromise clearly in code/tests.

Anthropic-specific guidance:

• Add support intentionally; do not forget to remove the current config-load behavior that deletes Anthropic OAuth.
• Consider whether any user-facing warning about subscription billing/extra usage belongs in CLI/TUI copy, but do not let that block plumbing.

Testing expectations:

• Add unit tests for token serialization/backward compatibility.
• Add tests for refresh registry behavior.
• Add tests for config persistence and load behavior.
• Add tests ensuring Anthropic OAuth config is preserved instead of deleted.
• Add focused tests for callback parsing/state mismatch/manual fallback where practical.
• Do not try to solve unrelated failing diagnostics outside this feature area.

Deliverables:

• Code changes for the plumbing and whichever provider flows you can implement robustly in this pass
• Tests
• A short summary of:
  • what was implemented
  • what was intentionally deferred
  • any Gemini-specific compromises

If you need to choose, prioritize:

1. provider registry + refresh plumbing
2. Anthropic + OpenAI Codex CLI login
3. Gemini support
4. TUI polish