[FEATURE] Warn when CLAUDE_CODE_OAUTH_TOKEN env var overrides credentials file

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When the CLAUDE_CODE_OAUTH_TOKEN environment variable is set, Claude Code silently uses it instead of credentials stored in ~/.claude/.credentials.json. This caused me weeks of troubleshooting and unexpected API billing charges.

I have a Max subscription ($200/month). Despite logging in correctly via claude login, my usage was being billed to my API account instead of my Max subscription allocation. Multiple complete reinstalls of Claude Code did not fix the issue.

The root cause: an old OAuth token from months ago was persisted in my system environment (loaded via shell profile scripts). This stale token silently overrode my fresh, valid Max subscription credentials in the credentials file.

The official documentation at https://support.claude.com/en/articles/12304248 only mentions ANTHROPIC_API_KEY precedence—there is no documentation warning that CLAUDE_CODE_OAUTH_TOKEN also overrides the credentials file.

Proposed Solution

1. Show a warning on startup when both CLAUDE_CODE_OAUTH_TOKEN env var AND ~/.claude/.credentials.json exist with different tokens:

⚠ Warning: CLAUDE_CODE_OAUTH_TOKEN environment variable is overriding credentials in ~/.claude/.credentials.json

1. Enhance /status output to show credential source:

Authentication: OAuth (from environment variable CLAUDE_CODE_OAUTH_TOKEN)

vs

Authentication: OAuth (from ~/.claude/.credentials.json)

1. Update documentation to include CLAUDE_CODE_OAUTH_TOKEN in the environment variable precedence article alongside ANTHROPIC_API_KEY.

Alternative Solutions

Current workaround is to manually unset the environment variable:

unset CLAUDE_CODE_OAUTH_TOKEN

Or add to ~/.bashrc:

unset CLAUDE_CODE_OAUTH_TOKEN ||:

However, this requires users to first discover that the env var is the problem—which took me weeks of debugging and multiple reinstalls before identifying.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. User runs claude setup-token to get OAuth token for CI/CD or container use
2. User exports token: export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
3. Months later, user forgets about this or the token is persisted in system credential store
4. User logs into Claude Code with Max subscription via claude login
5. Fresh credentials saved to ~/.claude/.credentials.json with subscriptionType: "max"
6. Claude Code silently uses the old env var token instead of fresh credentials
7. User's usage is billed to API account, not Max subscription
8. User reinstalls Claude Code multiple times—problem persists because env var survives
9. User has no indication that env var is overriding their credentials file

Additional Context

Related issues:

• #7855 - Environment variables ANTHROPIC_AUTH_TOKEN and CLAUDE_CODE_OAUTH_TOKEN interfere with local interactive mode
• #11587 - Auth conflict warning exists for API key + OAuth token, but not for OAuth env var + OAuth credentials file
• #6955 - MAX tier recognition issues

Environment:

• Claude Code version: 2.0.76
• OS: Ubuntu 24.04
• The stale token was stored in a systemd-creds encrypted credential store (/etc/credstore/) which survived Claude Code reinstalls

Technical note:
Claude Code already has conflict detection for ANTHROPIC_API_KEY vs OAuth. Similar logic could detect when CLAUDE_CODE_OAUTH_TOKEN env var differs from the token in ~/.claude/.credentials.json.