Solanasis Docs

claude-code-auth-handoff-2026-03-18

22 min read

Claude Code Remote Auth Persistence, setup-token, and Session Behavior

Artifact type: Research-grade extraction / playbook / briefing memo / AI handoff
Prepared: 2026-03-18
Scope: This document extracts, organizes, verifies, and improves the key parts of the discussion about Claude Code authentication on remote servers, repeated logouts, claude setup-token, CLAUDE_CODE_OAUTH_TOKEN, session behavior, remote control, install/update paths, and persistence across shells / tmux.

How to read this document

Evidence status legend

  • Verified = confirmed directly in current official documentation or primary-source issue tracker evidence.
  • User-stated = supplied by the user in the conversation; not independently verified here.
  • Assistant-stated but unverified = previously asserted in the discussion, but not directly confirmed in official docs; may be supported only by issue reports or inference.
  • Tentative / speculative = reasoned hypothesis or recommended interpretation, not directly established.

Important caution

This artifact mixes:

  1. official Claude Code documentation, which is the best source of truth for intended behavior, and
  2. GitHub issues, which are valuable for identifying real-world bugs and regressions but are not the same as product guarantees.

Where docs and issue reports diverge, this artifact calls that out explicitly.

Executive Summary

Bottom line

The discussion converged on a practical conclusion:

  1. Officially documented interactive login for Claude Code is still: run claude and complete browser-based login, or use claude auth login / /login. Verified. [R1] [R2] [R3]
  2. CLAUDE_CODE_OAUTH_TOKEN is real and in use, especially in GitHub Action workflows, but the current official docs do not clearly present claude setup-token + CLAUDE_CODE_OAUTH_TOKEN as the standard long-lived interactive login replacement for a personal remote dev shell. Verified for action usage; assistant-stated but not fully documented for interactive persistence. [R4] [R5]
  3. There are multiple current/recent bug reports showing that OAuth/session persistence has been fragile in several scenarios, including:
    • tokens not persisting across terminal sessions,
    • CLAUDE_CODE_OAUTH_TOKEN not being enough to fully authenticate a fresh CLI session,
    • long-running tmux agents losing auth after refresh events,
    • env-var auth conflicts overriding proper subscription login,
    • and scope problems when using setup-token with /remote-control. Verified via issue tracker, not official product guarantees. [R6] [R7] [R8] [R9] [R10] [R11]
  4. The user’s reported install path (/home/zasage/.npm-global/bin/claude) means the box was using the deprecated npm installation, not the recommended native installer. Official docs now recommend native install and explicitly say npm install is deprecated. Verified. [R12]
  5. For the user’s specific symptom (“it works if I export the token, but Claude still seems to forget it / logs me out / asks me to log in again”), there are likely multiple overlapping factors:
    • shell startup file placement,
    • tmux environment inheritance,
    • long-running session refresh bugs,
    • env-var precedence/conflict,
    • deprecated npm install path,
    • and the possibility that setup-token itself is currently unreliable for this interactive use case. Mixed: some verified, some tentative. [R6] [R8] [R10] [R12] [R13] [R14]

Best current practical guidance

For a long-lived remote interactive server:

  • Treat native install + normal browser login as the official/default path. Verified. [R1] [R2] [R12]
  • If you insist on CLAUDE_CODE_OAUTH_TOKEN, make it persistent at the shell/tmux/service layer, not by retyping export manually or using a text-expander. Verified in general shell/tmux behavior; Claude-specific outcome still partly unverified. [R13] [R14]
  • Do not assume the token method is a perfect substitute for browser login in interactive use; current issue reports say otherwise. Verified via issue reports only. [R6] [R7] [R8] [R10]
  • Clean up auth conflicts and old installs before drawing conclusions. Verified / reasonable operational guidance. [R12] [R15] [R16]

1) User Context and Goals Preserved from the Discussion

User goal

User-stated: The user wants Claude Code on a remote server to stay authenticated without repeated logins, and specifically explored using claude setup-token plus export CLAUDE_CODE_OAUTH_TOKEN=... to avoid being logged out roughly every 8 hours.

Environment clues from the discussion

  • User-stated: Remote server use is central.
  • User-stated: The user may have multiple active Claude Code surfaces/sessions, including remote server, desktop, and possibly Cowork / another server.
  • User-stated: The normal login flow logs the user out after about eight hours.
  • User-stated: The user previously adjusted system clock settings and still had the logout/persistence problem.
  • User-stated: The user reported:
    • which claude → /home/zasage/.npm-global/bin/claude
    • claude --version → 2.1.76 (Claude Code)
  • User-stated: Exporting a stored CLAUDE_CODE_OAUTH_TOKEN appears to help at first but does not reliably remain effective day to day.

User’s core questions

  1. Is Claude Code limited to one session at a time?
  2. Are multiple open sessions causing logouts?
  3. Does setup-token need a special order of operations?
  4. What does it do to existing sessions?
  5. How do you make CLAUDE_CODE_OAUTH_TOKEN persistent?
  6. Why does Claude still ask for login after setting the token?
  7. Does Claude Code auto-update, and did that nuance matter here?

2) Verified Facts Extracted and Corrected

2.1 Interactive login path

  • Verified: Official setup/auth docs say that after installing Claude Code, the standard flow is to run claude and follow the browser prompts. [R1] [R2]
  • Verified: claude auth login, claude auth logout, and claude auth status are official CLI commands. claude auth status --text is supported. [R3]
  • Verified: Troubleshooting docs explicitly say that if Claude prompts for login again after a session, the OAuth token may have expired; the recommended action is /login, and if this happens frequently, check that the system clock is accurate. [R16]

Implication

The browser/OAuth login flow is definitely the documented interactive path. That does not prove that setup-token is unsupported for interactive use, but it does mean the docs do not elevate it to the primary day-to-day remote-shell method.

2.2 Remote Control session behavior

  • Verified: Remote Control requires Claude Code v2.1.51 or later. [R17]
  • Verified: Each interactive Claude Code process supports one remote session at a time, not one total account-wide session. [R17]
  • Verified: If you run multiple Claude Code instances, each one gets its own environment and session. [R17]
  • Verified: Remote Control docs say authentication should be done by running claude and using /login through claude.ai if not already signed in. [R17]

Correction to an earlier simplification

Earlier in the discussion, “you can only have one session at a time” was corrected to “one remote session per interactive process.” That correction is Verified. [R17]

2.3 Install/update behavior

  • Verified: Native install is the recommended install method. [R12]
  • Verified: Native installations automatically update in the background. Claude checks on startup and periodically while running; updates take effect next time Claude Code starts. [R12]
  • Verified: Homebrew and WinGet installs do not auto-update and must be updated manually. [R12]
  • Verified: claude update is an official command. [R3] [R12]
  • Verified: npm installation is deprecated; Anthropic recommends migrating from npm to native install. [R12]

Important correction

An earlier assistant message said that version 2.1.76 was current. That is now outdated / incorrect as of the artifact date. The changelog shows 2.1.78 dated 2026-03-17, and 2.1.77 also dated 2026-03-17, while 2.1.76 is dated 2026-03-14. Verified. [R18]

2.4 Config and reset locations

  • Verified: Troubleshooting docs list config/state locations and say Claude Code stores configuration in several locations. [R16]
  • Verified: Reset commands documented by Anthropic are:
# Reset all user settings and state
rm ~/.claude.json
rm -rf ~/.claude/
 
# Reset project-specific settings
rm -rf .claude/
rm .mcp.json

This removes settings, MCP configurations, and session history. [R16]

2.5 Settings and API key helper conflict surface

  • Verified: Claude Code settings include apiKeyHelper, which runs a custom script to generate an auth value that is sent as API headers for model requests. [R19]
  • Verified in support docs: Claude Code prioritizes environment-variable API keys over authenticated subscriptions, and Anthropic recommends keeping ANTHROPIC_API_KEY unset if you want to use your Claude subscription. [R15]

Implication

Even if the user thinks they are “logged in,” environment-based auth can override or conflict. Official support docs explicitly confirm this for ANTHROPIC_API_KEY; issue reports suggest similar pain can happen with CLAUDE_CODE_OAUTH_TOKEN, but that latter part is not yet clearly documented officially. [R15] [R9]

3) Claims from the Discussion, Classified

3.1 Claims that are now clearly Verified

Claim A

Claude Code is not limited to one total session per account; Remote Control is one remote session per interactive process.

Status: Verified
Evidence: Remote Control docs. [R17]

Claim B

Native installs auto-update; Homebrew and WinGet do not; npm is deprecated.

Status: Verified
Evidence: Setup docs. [R12]

Claim C

claude auth login, claude auth logout, claude auth status --text, and claude update are valid commands.

Status: Verified
Evidence: CLI reference. [R3]

Claim D

Frequent “Not logged in” or “token expired” should trigger /login and system clock checking.

Status: Verified
Evidence: Troubleshooting docs. [R16]

Claim E

The user’s path /home/zasage/.npm-global/bin/claude indicates npm-global install, not native install.

Status: Verified from user output + install docs.
Evidence: User-stated path plus setup docs describing native location/migration and npm deprecation. [R12]

3.2 Claims that are Supported only by issue reports / not fully official

Claim F

CLAUDE_CODE_OAUTH_TOKEN can silently override credentials stored in ~/.claude/.credentials.json.

Status: Assistant-stated but unverified in official docs
Evidence: GitHub issue #16238 says this happened and proposes better warnings; official support docs explicitly document precedence for ANTHROPIC_API_KEY, but not clearly for CLAUDE_CODE_OAUTH_TOKEN. [R9] [R15]

Claim G

claude setup-token + exported CLAUDE_CODE_OAUTH_TOKEN is not enough to fully authenticate a fresh interactive CLI session.

Status: Assistant-stated but supported by issue report
Evidence: GitHub issue #8938 reproduces exactly this behavior. [R6]

Claim H

Long-running tmux agents can lose OAuth auth after refresh-related failures every ~12 hours.

Status: Assistant-stated but supported by issue report
Evidence: GitHub issue #29896. [R8]

Claim I

setup-token may fail to provide the scope required for /remote-control.

Status: Assistant-stated but supported by issue report
Evidence: GitHub issue #33105 reports user:sessions:claude_code scope failure with setup-token. [R10]

Claim J

A stale CLAUDE_CODE_OAUTH_TOKEN in shell startup files can cause confusing billing/auth behavior and override fresh login.

Status: Assistant-stated but supported by issue report
Evidence: GitHub issue #16238. [R9]

3.3 Claims that remain Tentative / speculative

Claim K

setup-token is mainly intended for CI/automation, not long-lived interactive remote shells.

Status: Tentative / speculative
Why: The docs do not clearly say this. However:

  • official interactive docs focus on browser login, and
  • the official GitHub Action docs accept claude_code_oauth_token, which together make the “automation-oriented” interpretation plausible. [R1] [R2] [R4]

Claim L

Multiple concurrently open local Claude Code terminals on the same host are a likely direct cause of the user’s logout problem.

Status: Tentative / speculative
Why: Changelog entries prove there were concurrency/auth/config bugs fixed in Feb 2026, but that does not prove concurrency is the user’s main cause today. [R20]

Claim M

The user’s specific “~8 hour” relogin interval corresponds to token expiry behavior.

Status: Tentative / speculative
Why: The docs say token expiry can cause relogin prompts but do not specify that exact interval. [R16]

4) What the Discussion Missed or Only Partially Covered

4.1 The user’s actual shell startup chain was never verified

Missing. We did not inspect whether the server is using:

  • bash vs zsh,
  • login shell vs non-login shell,
  • SSH spawning login shells or not,
  • .bashrc, .bash_profile, .profile, .zshrc, or .zprofile,
  • or whether a wrapper script/service launches Claude.

This matters because export in one shell does not automatically persist to future shells.

4.2 tmux environment inheritance was not directly diagnosed on the user’s machine

Missing. General tmux behavior explains why this often fails, but the user never provided:

  • whether tmux is in use,
  • whether tmux kill-server was tested,
  • whether tmux show-environment -g includes CLAUDE_CODE_OAUTH_TOKEN,
  • or whether Claude is being relaunched from old panes inheriting stale env.

4.3 No direct inspection of auth state was performed

Missing. The discussion recommended claude auth status --text, but the user never pasted the output. That means the actual active auth source and login state remain unconfirmed.

4.4 No direct inspection of conflicting env vars/settings

Missing. The discussion did not obtain live outputs for:

  • ANTHROPIC_API_KEY
  • ANTHROPIC_AUTH_TOKEN
  • CLAUDE_CODE_OAUTH_TOKEN
  • apiKeyHelper
  • ANTHROPIC_BASE_URL
  • project .env files

Given recent auth-conflict issue reports, this is a serious missing step. [R11] [R19]

4.5 The deprecated npm install path was identified, but not yet remediated

Missing follow-through. The discussion correctly identified npm-global install, but no actual migration sequence/output was captured.

5) Current Best-Fit Interpretation for the User’s Problem

High-confidence interpretation

The user’s problem is not likely a simple “only one session allowed” issue. That theory is contradicted by the Remote Control docs. Verified. [R17]

More plausible combined explanation

Layer 1: persistence mechanics

The token may not be getting injected into the actual process tree that launches Claude every time.

  • If export is typed manually, it only affects the current shell.
  • If tmux is already running, new panes may inherit tmux’s old environment, not the shell’s new one.
  • If another launcher/service starts Claude, the shell export may never be seen.

Status: Verified for shell/tmux mechanics generally. [R13] [R14]

Layer 2: Claude-side auth fragility

Even when CLAUDE_CODE_OAUTH_TOKEN is set, there are multiple reports that Claude Code may still:

  • ask for login,
  • fail to persist auth,
  • lose auth after refresh,
  • or fail on remote-control scope checks.

Status: Supported by issue tracker, not official docs. [R6] [R7] [R8] [R10]

Layer 3: install/update path risk

The user was on deprecated npm-global install. That does not prove causation, but it raises the odds that weird auth/update/path behavior is install-related.

Status: Verified risk factor, not proven root cause. [R12]

Layer 4: env-var conflict risk

If any of these are present in the shell/session/project environment, they may disrupt or override OAuth behavior:

  • ANTHROPIC_API_KEY
  • ANTHROPIC_AUTH_TOKEN
  • ANTHROPIC_BASE_URL
  • apiKeyHelper
  • stale CLAUDE_CODE_OAUTH_TOKEN

Status: mixed; official support docs verify API-key precedence, issue tracker verifies several additional conflict scenarios. [R11] [R15] [R19]

6) Actionable Playbook

6.1 Fast diagnosis checklist

Run these from a fresh SSH session on the remote server before starting Claude:

echo "$SHELL"
printf '%s\n' "${CLAUDE_CODE_OAUTH_TOKEN:+set}"
env | grep -E '^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|CLAUDE_CODE_OAUTH_TOKEN)=' | sed 's/=.*/=<set>/'
which -a claude
claude --version
claude auth status --text

Why these matter

  • Confirms shell type and whether the token is actually in the new shell.
  • Exposes conflicting auth env vars.
  • Confirms whether Claude is still coming from npm-global path.
  • Uses official claude auth status to inspect login state. [R3]

6.2 If using tmux, diagnose that separately

tmux show-environment -g | grep CLAUDE_CODE_OAUTH_TOKEN || echo no-tmux-var
pgrep -af claude || echo no-claude

If tmux is in play and the env var is missing there, either:

tmux set-environment -g CLAUDE_CODE_OAUTH_TOKEN "$CLAUDE_CODE_OAUTH_TOKEN"

or restart tmux entirely:

tmux kill-server

Evidence note

tmux maintains its own environment model; shell exports do not automatically rewrite an already-running tmux server’s environment. Verified generally from tmux documentation. [R14]

6.3 Make CLAUDE_CODE_OAUTH_TOKEN persistent correctly

Create a dedicated file:

mkdir -p ~/.config/claude-code
cat > ~/.config/claude-code/token.env <<'EOF2'
export CLAUDE_CODE_OAUTH_TOKEN='YOUR_TOKEN_HERE'
EOF2
chmod 600 ~/.config/claude-code/token.env

Source it from ~/.bashrc:

grep -qxF '[ -f ~/.config/claude-code/token.env ] && . ~/.config/claude-code/token.env' ~/.bashrc 2>/dev/null || \
  echo '[ -f ~/.config/claude-code/token.env ] && . ~/.config/claude-code/token.env' >> ~/.bashrc

Ensure login shells source .bashrc:

grep -qxF '[ -f ~/.bashrc ] && . ~/.bashrc' ~/.bash_profile 2>/dev/null || \
  echo '[ -f ~/.bashrc ] && . ~/.bashrc' >> ~/.bash_profile

Open a new SSH session and verify:

printf '%s\n' "${CLAUDE_CODE_OAUTH_TOKEN:+set}"

Evidence note

This pattern is based on Bash startup-file behavior, not a Claude-specific guarantee. Bash docs explicitly state that interactive non-login shells read ~/.bashrc, and typically ~/.bash_profile sources ~/.bashrc. [R13]

Important limitation

Making the env var persistent does not guarantee Claude Code will stop asking for login. It only ensures the variable exists in new shells. The Claude-side behavior remains partly bug-prone according to current issue reports. [R6] [R7] [R8]

6.4 Eliminate auth conflicts

Before starting Claude in a troubleshooting session, check and possibly unset:

unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_BASE_URL

Then verify apiKeyHelper is not set in config:

grep -R "apiKeyHelper" ~/.claude ~/.claude.json 2>/dev/null

Why

  • Official support docs verify API-key env vars take precedence over subscription auth. [R15]
  • Issue reports indicate other env/config values can also break OAuth-mode behavior. [R9] [R11]

6.5 Clean reset path

If the box is in a bad auth state:

claude auth logout
pkill -f claude
rm ~/.claude.json
rm -rf ~/.claude/
rm -rf .claude/
rm .mcp.json

Then start fresh.

Evidence note

Reset commands are officially documented. [R16]

6.6 Installation cleanup / migration

Because the user’s path was npm-global, the best cleanup sequence is:

# Install native Claude Code
curl -fsSL https://claude.ai/install.sh | bash
 
# Remove deprecated npm install
npm uninstall -g @anthropic-ai/claude-code
 
# Confirm path order
which -a claude
claude --version

Why

This removes one major source of ambiguity. Anthropic explicitly recommends migrating from npm to native install. [R12]

6.7 Decide whether to keep using setup-token

Strong recommendation for this exact user case

For a daily interactive remote server, the most defensible recommendation is still:

  1. migrate to native install,
  2. remove auth conflicts,
  3. use normal claude / browser login,
  4. then test persistence again.

Why this recommendation is stronger than the token path

  • It is the official documented path. [R1] [R2]
  • It avoids relying on a path with multiple live bug reports. [R6] [R7] [R8] [R10]
  • It reduces the chance of stale env-var override confusion. [R9] [R15]

If the user still insists on setup-token

Then the safest operational rule is:

  • set the token at the shell/tmux/service layer,
  • use a fresh shell/process,
  • do not assume it will fully replace login reliably,
  • and avoid mixing it casually with normal subscription login until auth precedence is fully understood on that host.

Status: mixed; this is a practical recommendation, not an official statement of intended product design.

7) Recommended Decision Tree

Option A — most conservative / highest-confidence

Goal: stable remote interactive use with lowest ambiguity.

  1. Migrate from npm to native install. Verified recommended path. [R12]
  2. Unset conflicting env vars. Verified / supported. [R15] [R11]
  3. Start a fresh SSH session.
  4. If using tmux, kill/restart tmux.
  5. Run claude and complete normal browser login. Verified official path. [R1] [R2]
  6. Confirm with claude auth status --text. Verified. [R3]
  7. If frequent expiry still happens, document exact frequency, version, and auth status output, then treat as likely bug.

Option B — user insists on token persistence

Goal: keep CLAUDE_CODE_OAUTH_TOKEN injected every day.

  1. Store token in ~/.config/claude-code/token.env.
  2. Source from shell startup files.
  3. Restart tmux or inject token into tmux environment.
  4. Start Claude from a fresh session that definitely sees the variable.
  5. If Claude still prompts for login, stop blaming shell persistence alone and classify as likely Claude-side auth bug / unsupported edge for the current build.

Option C — mixed/advanced environment

Use this if the server also runs bots, apps, or projects with Anthropic-related env vars.

  1. Inspect shell, tmux, systemd, Docker, project .env, and wrapper scripts.
  2. Remove or isolate:
    • ANTHROPIC_API_KEY
    • ANTHROPIC_AUTH_TOKEN
    • ANTHROPIC_BASE_URL
    • CLAUDE_CODE_OAUTH_TOKEN
  3. Consider separate Unix users or separate shell profiles for:
    • bot/API-key workloads
    • interactive Claude subscription login

This is not explicitly documented by Anthropic, but it is a clean operational pattern given the auth conflict evidence.

8) Commands Worth Preserving for Another AI or Operator

Inspect auth and path

which -a claude
claude --version
claude auth status --text
env | grep -E '^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|CLAUDE_CODE_OAUTH_TOKEN)=' | sed 's/=.*/=<set>/'
grep -R "apiKeyHelper" ~/.claude ~/.claude.json 2>/dev/null

Check tmux env

tmux show-environment -g | grep CLAUDE_CODE_OAUTH_TOKEN || echo no-tmux-var

Kill Claude/tmux for clean retest

pkill -f claude
tmux kill-server

Reset Claude config/state

rm ~/.claude.json
rm -rf ~/.claude/
rm -rf .claude/
rm .mcp.json

Install native Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Remove deprecated npm install

npm uninstall -g @anthropic-ai/claude-code

Force immediate update

claude update

9) Risks, Caveats, and Pitfalls

9.1 Biggest pitfall: stale env vars

A stale env var can make the user think Claude is “logged in wrong” or “ignoring fresh login.” Official docs confirm this for ANTHROPIC_API_KEY; issue reports strongly suggest similar confusion with CLAUDE_CODE_OAUTH_TOKEN. [R9] [R15]

9.2 Biggest process pitfall: tmux

If tmux was started before the env var was added, new panes may still not have the right auth context. [R14]

9.3 Biggest product pitfall: setup-token may not be a drop-in replacement for browser login

The issue tracker strongly suggests that expectation currently fails in at least some environments/builds. [R6] [R10]

9.4 Biggest maintenance pitfall: deprecated npm install

Even if it seems to work, it is now an off-recommended path and should be removed from the problem space first. [R12]

9.5 Biggest factual pitfall from the prior conversation

Earlier advice said 2.1.76 was current. That is no longer true as of this artifact date; 2.1.78 is listed on the changelog dated 2026-03-17. [R18]

10) Reviewer Pass / Self-Review

What this artifact does well

  • Separates official docs from issue-tracker evidence.
  • Preserves the user’s concrete environment clues and goals.
  • Corrects at least one earlier outdated statement (version currency).
  • Converts the discussion into a real diagnostic and remediation playbook.

Where this artifact is still weak

  • No live diagnostics from the user’s box were captured beyond which claude and claude --version.
  • No direct evidence was gathered for the user’s actual shell startup files or tmux usage.
  • No direct reproduction of setup-token behavior on the user’s machine was performed.
  • Some important claims rely on issue reports rather than official docs.

Reviewer judgment

This is strong enough for operational handoff, but not enough to claim definitive root cause on the user’s machine.

11) Handoff Notes for Another AI

The next AI should not re-explain basics first. Start by narrowing the user’s exact environment.

Assume these facts already exist

  • User is trying to keep Claude Code authenticated on a remote server.
  • User believes normal browser login expires after about eight hours.
  • User tried claude setup-token and manually exporting CLAUDE_CODE_OAUTH_TOKEN.
  • User’s Claude binary path was /home/zasage/.npm-global/bin/claude.
  • User’s reported version at the time was 2.1.76.
  • Artifact evidence now shows npm install is deprecated and latest changelog is beyond 2.1.76.

Highest-value next actions

Ask for or inspect the following outputs from a fresh SSH session:

echo "$SHELL"
printf '%s\n' "${CLAUDE_CODE_OAUTH_TOKEN:+set}"
env | grep -E '^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL|CLAUDE_CODE_OAUTH_TOKEN)=' | sed 's/=.*/=<set>/'
which -a claude
claude --version
claude auth status --text
tmux show-environment -g | grep CLAUDE_CODE_OAUTH_TOKEN || echo no-tmux-var
grep -R "apiKeyHelper" ~/.claude ~/.claude.json 2>/dev/null

Likely next decision

Unless the user has a compelling reason to stay on setup-token, recommend:

  1. migrate to native install,
  2. kill tmux / old Claude processes,
  3. use official browser login path,
  4. verify persistence,
  5. only then revisit token-based auth if necessary.

Tone guidance

Be direct. Do not treat setup-token as fully settled or officially blessed for this use case. Distinguish “documented” from “people report it works sometimes.”

12) Open Questions / What Still Needs Validation

  1. Does the user actually run Claude inside tmux on the affected server?
    This is currently unconfirmed.

  2. Which shell startup files are active on that server?
    Need to inspect .bashrc, .bash_profile, .profile, .zshrc, etc.

  3. What does claude auth status --text show in a fresh SSH session before the user starts troubleshooting?
    This is critical and currently missing.

  4. Are any of these env vars present in the active shell, project .env, service env, or tmux env?

    • ANTHROPIC_API_KEY
    • ANTHROPIC_AUTH_TOKEN
    • ANTHROPIC_BASE_URL
    • CLAUDE_CODE_OAUTH_TOKEN

  5. Is apiKeyHelper configured?
    Unconfirmed.

  6. Does the issue persist after migrating from npm to native install?
    This is the single highest-value remediation test still not done.

  7. Is the user’s eight-hour logout problem still reproducible on Claude Code 2.1.78 or later?
    This is unknown and matters because several auth/session bugs were fixed across recent versions. [R18] [R20]

  8. Does the user need /remote-control or only terminal auth persistence?
    If remote-control is needed, setup-token may be materially worse because of scope issues reported in #33105. [R10]

  9. Was the token added only to one shell manually, or persisted in startup files?
    The user implied manual export, but the exact persistence layer was never confirmed.

  10. Is there a service/IDE/wrapper launching Claude outside the user’s shell?
    If yes, shell exports alone may never solve the problem.

13) Sources and Evidence Notes

Official Claude / Anthropic sources

Supporting non-Anthropic primary references for shell/tmux behavior

GitHub issue tracker evidence (valuable but not authoritative product guarantees)

14) Final Takeaway

The strongest, most defensible conclusion from this discussion is:

  • Do not reduce this to “Claude only allows one session.” That is not what the current docs say. [R17]
  • Do not reduce this to “just export the token and it will be fine.” Current issue evidence says that is not reliably true. [R6] [R7] [R8]
  • Do remove ambiguity first: migrate off npm, inspect env conflicts, understand shell/tmux startup behavior, and test from a clean session. [R12] [R13] [R14] [R15]
  • If the normal login still dies repeatedly after that, treat it as a likely product bug/regression rather than user error. That is the fairest interpretation based on current docs + issue tracker evidence.

Graph View