[Enhancement] Add flag to ignore ANTHROPIC_API_KEY when using subscription authentication

[gmelli]

Summary

Add a command-line flag or configuration option to allow Claude Code to ignore the ANTHROPIC_API_KEY environment variable when users want to authenticate with their Claude Max/Pro subscription instead.

Use Case

I'm a Claude Max Pro subscriber who also develops custom agents (e.g., private-llm-manager-aget) that make direct API calls to Claude using the official SDK. These agents legitimately need ANTHROPIC_API_KEY set in my environment.

However, when I run Claude Code, I encounter this warning:

⚠Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set. 
This may lead to unexpected behavior.

Current Workarounds

1. Unsetting the variable - Doesn't work because my agents need it
2. Shell alias - alias claude='env -u ANTHROPIC_API_KEY /opt/homebrew/bin/claude' works but is hacky
3. Modifying agent code - If agents spawn Claude Code as subprocess, need to remove the env var programmatically

Proposed Solutions

Option 1: Command-line Flag

claude --use-subscription  # Ignore ANTHROPIC_API_KEY
claude --ignore-env-api-key  # Alternative naming

Option 2: Environment Variable

CLAUDE_CODE_AUTH_METHOD=subscription claude

Option 3: Configuration File

{
  "authPrecedence": "subscription",
  "ignoreEnvApiKey": true
}

Option 4: Smart Detection

Automatically prefer subscription auth when user is logged in with Max/Pro and only show warning if subscription auth fails.

Related Issues

• [Bug/Documentation] 'Organization has been disabled' error when ANTHROPIC_API_KEY overrides Max/Pro subscription #8327 - ANTHROPIC_API_KEY overriding Max/Pro subscriptions
• [Feature Request] Per-Project Anthropic API Account Configuration #7200 - Per-project API account configuration request

Benefits

• Allows legitimate multi-tool workflows (Claude Code + custom agents)
• Cleaner than shell aliases/wrappers
• Gives users explicit control over authentication precedence
• Reduces confusion for Max/Pro subscribers

Additional Context

As a Max Pro subscriber, Claude Code usage is included in my subscription (/cost confirms this), but the presence of ANTHROPIC_API_KEY for other tooling creates unnecessary friction.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] When ANTHROPIC_API_KEY env variable is set, Claude shows a conflict warning on startup #9515
2. [Bug/Documentation] 'Organization has been disabled' error when ANTHROPIC_API_KEY overrides Max/Pro subscription #8327
3. Persistent Warning When Using API Key Directly #4733

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[gmelli]

Closing as duplicate of #8327, which covers this use case with broader scope.

However, I want to strongly advocate for the --use-subscription flag solution proposed in both issues.

Why This Matters

My use case represents a growing pattern: Max Pro subscribers who also develop custom agents. I need:

• ANTHROPIC_API_KEY in my environment for private-llm-manager-aget (makes direct API calls via SDK)
• Claude Code using my Max Pro subscription (not the API key)

This is a legitimate dual-use workflow, not a misconfiguration.

Solution Priority

From my original proposal, I recommend:

1. ✅ --use-subscription flag (Option 1) - Simplest, most explicit

   claude --use-subscription  # Ignore ANTHROPIC_API_KEY

2. ✅ Environment variable (Option 2) - Alternative approach

   CLAUDE_CODE_AUTH_METHOD=subscription claude

3. ⚠️ Config file option - More complex, lower priority

4. ⚠️ Smart detection - Nice-to-have, but explicit control is better

Impact

As agent development grows, more Max/Pro subscribers will encounter this. The current workaround (shell aliases) works but is hacky and requires documentation hunting.

Adding to #8327's discussion to push for implementation.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.