Support device-code authentication flow (RFC 8628) for Pro/Max subscription users in headless environments

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/21765
2. https://github.com/anthropics/claude-code/issues/1178
3. https://github.com/anthropics/claude-code/issues/21914

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

This is not a duplicate of the flagged issues. Those are bug reports about existing OAuth failing in remote sessions. This is a feature request for a new authentication method — specifically RFC 8628 (OAuth Device Authorization Grant) — which would eliminate the need for a browser redirect entirely. None of the linked issues propose this.

yes please!

Still relevant — especially with Agent Teams now shipping in Opus 4.6. The docs recommend tmux for split-pane agent workflows, which is the standard setup for headless/SSH environments. But the first barrier for Pro/Max users on headless VMs is still getting authenticated. This needs a proper device-code flow, not workarounds.

Yes this would be much appreciated :)

Please, I need this is Github Codespace... opens in browser proxy... need device code flow

This is a high priority issue for Pro/Max plan subscribers. It renders several of the core use cases for Claude Code impossible.

For my usecase in Codespaces, one workaround I was able to do is capture the redirect URL in my browser, and then run CURL with that in my codespace.

IE: curl 'http://localhost:46037/callback?code=REDACTED&state=gtpH-REDACTED'

I just spent a couple of hours wrangling with this trying to figure out why my claude.ai MCPs weren't working on my headless machine only to find that I was limited to inference using my OAuth token rather than being able to authenticate as a Max subscriber. Especially given the lack of MCP support for Gmail, it's a bummer there isn't a more elegant headless authentication option

Notes on workaround for headless pro/max users:

You can create an OAuth token for your Pro/Max account on another machine with access to a browser, and then pass that to your headless Claude code as an environment variable.

Create token:

claude setup-token

Pass it to claude code as CLAUDE_CODE_OAUTH_TOKEN

CLAUDE_CODE_OAUTH_TOKEN=your-token claude

You can create an OAuth token for your Pro/Max account on another machine with access to a browser, and then pass that to your headless Claude code as an environment variable.

Yes, this works, but it doesn't offer the same sort of connective tissue as more typical authentication flows. Claude Code basically doesn't recognize that you're on a subscription, so you can't see usage in a session, nor do you have access to things tied to your account, like claude.ai connectors.

I ran into this now that I've started experimenting with the Discord MCP and headless Claude running in the cloud.

Given how new the Telegram/Discord workflows are I suspect this issue will start getting more attention. I have a hook on my laptop that pushes the claude oauth token into a secrets vault where the Claude instance can "reload" a valid token, but it still takes a HUP and if I'm in the middle of something it will break the session.

Reference implementation: OpenAI Codex just shipped this

For anyone tracking this — OpenAI's Codex CLI merged device-code auth into their app server last week. Their implementation follows the standard RFC 8628 flow and offers a clean protocol-level reference for how Claude Code could implement this.

How their flow works (protocol level)

1. Client sends account/login/start with { "type": "chatgptDeviceCode" }
2. Server immediately returns { loginId, verificationUrl, userCode } — no browser redirect needed
3. Client displays the URL and one-time code (the client owns the UX)
4. Server polls the token endpoint in the background using tokio::select! to race cancellation vs completion
5. On success: emits account/login/completed (success) + account/updated notifications, persists tokens
6. On failure/cancel: emits only account/login/completed (failure)

The device-code login resolves to the same auth state as the browser flow — it's not a new auth mode, just an alternative grant type for obtaining the same tokens.

Key design decisions worth noting

• ActiveLogin refactored to an enum with Browser (wraps shutdown handle) and DeviceCode (wraps cancellation token) variants — both share login_id() and cancel() methods
• Security review caught an environment variable for overriding the auth issuer URL; they gated it behind #[cfg(debug_assertions)] so it only applies in test builds
• Error handling distinguishes "feature not available" (HTTP 404 from the usercode endpoint → INVALID_REQUEST) from other failures (INTERNAL_ERROR)

Why this matters for Claude Code

With Codex now supporting device-code auth, Claude Code is the only major AI coding CLI that forces subscription users through a browser redirect. This is especially painful given:

• The growing adoption of headless agent workflows (Agent Teams with tmux, as noted above)
• Remote dev environments (GitHub Codespaces, cloud VMs, SSH sessions) where browser redirects fundamentally don't work
• The existing workarounds (installing a full desktop environment, or manually transferring OAuth tokens via setup-token) are fragile and error-prone

The Codex implementation is a good reference — ~170 lines of core server logic, plus protocol schema updates and tests. Claude Code could adopt a similar approach using its existing OAuth infrastructure, adding --use-device-code to /login or auto-detecting headless environments.

Happy to help with implementation details if this moves forward.

This issue also affects Anthropic Console account users (e.g., claude auth login --console over SSH), not just those with a Pro/Max subscription.

A workaround is to start Claude Code, type /login, choose the “Anthropic Console account” auth option, and then it correctly prints “Browser didn't open? Use the url below to sign in (c to copy)”, letting you input the code returned from a browser on the local machine.

So the functionality is there, it's just not exposed to this use case.

Just to chime in, for what it is worth Amazon's kiro-cli also handles login from an ssh machine seemlessly (it does still require opening in a url, but the url is 1.) short enough to cut and paste and 2.) does not require tunnel connection for 8080 to the ssh, which is what the Claude website recommended. Also, immediately after logging in, I was challenged to login again, I poked at it a few times, and couldn't get it to work, but when I canceled the action and asked Claude if I was logged in, it said I was. This just not a good customer experience.

❤️ I submitted a feature request to add TOTP to the authentication flow for headless/ssh sessions #74204.

For my usecase in Codespaces, one workaround I was able to do is capture the redirect URL in my browser, and then run CURL with that in my codespace. IE: curl 'http://localhost:46037/callback?code=REDACTED&state=gtpH-REDACTED'

Only thing that worked for me; but considering how primitive this feature is its absolutely insane Claude can't figure it out.