[FEATURE] TOTP-based per-session authentication option for headless/SSH environments

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

The issue

Claude Code's OAuth login flow depends on a browser-to-CLI redirect (or a manual copy/paste of a one-time authorization code) to complete authentication. Over SSH into a headless machine, this flow is fragile:

• The browser redirect can't reach the CLI's local listener.
• The manual fallback (copy URL → complete login in a browser → paste code back) can itself fail — in my case, the browser returned an error resembling "unable to open location" rather than showing a code or completing the redirect.
• If both the redirect and manual-code paths fail, the practical options are: fix or retry the underlying redirect/callback path, use claude setup-token to generate a long-lived CLAUDE_CODE_OAUTH_TOKEN (stays on a Pro/Max subscription, but still requires completing OAuth successfully at least once to generate), or fall back to ANTHROPIC_API_KEY, which bills separately from a Pro/Max subscription.

Every login attempt also requires a brand-new one-time authorization code — there is no option for a stable, locally-generatable credential for authenticating a session.

This is a known and recurring pain point (see related issue #22992 requesting a device-code flow per RFC 8628), but the specific option below hasn't been proposed there and may be worth considering as a distinct, complementary path.

Proposed Solution

Proposed feature: TOTP as a per-session authentication option

Offer TOTP (Time-based One-Time Password) — the same mechanism used by authenticator apps like Google Authenticator, Microsoft Authenticator, or 1Password — as an alternative authentication method for Claude Code sessions.

How this would work:

1. During one-time setup (similar to claude setup-token), the user registers a TOTP secret with their Claude account (e.g., scan a QR code or enter a key into their authenticator app of choice).
2. On subsequent logins — including over SSH, in containers, or on any headless machine — the user is prompted to enter the current 6-digit code from their authenticator app instead of going through a browser redirect.
3. Because the code is generated locally by the authenticator app from a shared secret, no browser, no callback listener, and no network round-trip to a browser are required at all — it works entirely within the terminal.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Suggested flow (illustrative)

$ claude /login
Choose authentication method:
  1) Browser (default)
  2) Manual code (browser on another device)
  3) TOTP (authenticator app)
> 3

Provided app or link to get QR code to use your authenticator app, or enter this key manually:
[QR code / secret key]

Enter the 6-digit code from your app to confirm setup:
> 482913
✓ TOTP registered.

Subsequent logins on any machine:

$ claude /login
Enter your authenticator code:
> 118204
✓ Authenticated.

Additional Context

Why this is a good fit for this specific problem

• No browser dependency at all. Unlike the current OAuth flow (browser redirect) or even the manual fallback (copy URL, open browser, paste code), TOTP requires no browser interaction during login itself — only the terminal and a phone/app.
• Per-session authorization, not a standing credential. This suits security-conscious users who specifically don't want a single long-lived reusable token (like the CLAUDE_CODE_OAUTH_TOKEN from claude setup-token) sitting on multiple machines. A TOTP code authorizes one login event and expires within seconds — there's nothing durable to leak or revoke across machines.
• Well-understood, standard pattern. Users are already familiar with TOTP from banking, email, and other account security. There's no new mental model to learn.
• Complementary, not a replacement. This wouldn't need to replace the browser flow or the long-lived-token option — it would sit alongside them as a third choice, letting users pick based on their environment and risk tolerance.