CLAUDE_CODE_OAUTH_TOKEN silently deletes macOS Keychain credentials on exit

[LARIkoz]

Summary

Setting CLAUDE_CODE_OAUTH_TOKEN as an environment variable causes the CLI to silently delete the macOS Keychain credential entry ("Claude Code-credentials") on process exit. This breaks authentication for all other Claude Code sessions (VS Code extension, other terminals).

Environment

• Claude Code v2.1.81
• macOS Darwin 25.3.0 (Apple Silicon)
• Cursor (VS Code fork) + Terminal.app

Steps to Reproduce

1. Confirm Keychain entry exists:

   security find-generic-password -a "$USER" -s "Claude Code-credentials"
   # → returns entry

2. Run a single claude -p with the env var:

   TOKEN=$(security find-generic-password -a "$USER" -w -s "Claude Code-credentials" | python3 -c "import sys,json; print(json.loads(sys.stdin.read())['claudeAiOauth']['accessToken'])")
   CLAUDE_CODE_OAUTH_TOKEN="$TOKEN" claude -p "ping" --model haiku

3. Check Keychain after:

   security find-generic-password -a "$USER" -s "Claude Code-credentials"
   # → "The specified item could not be found in the keychain."

Expected Behavior

When CLAUDE_CODE_OAUTH_TOKEN is set, the CLI should bypass Keychain (which it does for reads) without modifying or deleting existing Keychain entries. The env var is documented as a way to provide a pre-authenticated token — it should be read-only with respect to credential storage.

Actual Behavior

The CLI deletes the Keychain entry on exit. This causes:

• VS Code extension loses auth → shows "How do you want to log in?" screen
• Other terminal sessions lose auth
• Any concurrent claude processes that rely on Keychain fail with 401

Source Code Analysis

From reverse-engineering cli.js v2.1.81:

1. When CLAUDE_CODE_OAUTH_TOKEN is set, the credential getter returns {accessToken: env.CLAUDE_CODE_OAUTH_TOKEN, refreshToken: null, expiresAt: null} — correctly bypassing Keychain reads

2. The credential store uses a fallback combiner (FI7): Keychain primary → plaintext fallback (~/.claude/.credentials.json). The combiner has cleanup logic: "successful write to backend A → delete from backend B"

3. The bug: During process lifecycle, some code path triggers a credential write to the plaintext file. The combiner's cleanup logic then fires: "successful plaintext write → delete Keychain entry." This deletion is incorrect when the env var is set, because:

   • The process never needed Keychain in the first place
   • Other processes/sessions depend on that Keychain entry
   • The deletion is a destructive side effect of a read-only operation

Impact

This bug is particularly severe for batch workflows. Users running parallel claude -p processes (e.g., for classification tasks) who set CLAUDE_CODE_OAUTH_TOKEN to avoid the Keychain race condition (#24317) end up destroying the credentials that their VS Code extension session depends on.

It creates a catch-22:

• Without CLAUDE_CODE_OAUTH_TOKEN: Keychain race condition kicks out the extension (Frequent re-authentication required with multiple concurrent Claude Code sessions (OAuth refresh token race condition) #24317)
• With CLAUDE_CODE_OAUTH_TOKEN: Keychain entry gets deleted, kicks out the extension

Proposed Fix

When CLAUDE_CODE_OAUTH_TOKEN is set (or EH8() returns true for setup-token mode):

1. Skip all credential writes (not just reads) — the env var token is ephemeral and shouldn't persist
2. Skip the fallback combiner's cleanup logic entirely
3. Never call security delete-generic-password for the main credentials entry

Pseudocode:

// In the credential write path:
if (process.env.CLAUDE_CODE_OAUTH_TOKEN || isSetupTokenMode()) {
  return; // Don't write, don't delete — env var mode is read-only
}

Workaround

We built a wrapper script that:

1. Extracts the token from ~/.claude/.credentials.json (not Keychain)
2. Passes CLAUDE_CODE_OAUTH_TOKEN only to the child process
3. Restores the Keychain entry after batch completion if deleted

#!/bin/bash
# claude-batch — wrapper for parallel claude -p without auth kickout
CREDS_FILE="$HOME/.claude/.credentials.json"

extract_token() {
    python3 -c "
import json, sys
with open('$CREDS_FILE') as f:
    data = json.load(f)
print(data['claudeAiOauth']['accessToken'])
"
}

restore_keychain() {
    if security find-generic-password -a "$USER" -s "Claude Code-credentials" > /dev/null 2>&1; then
        return 0  # already exists
    fi
    security add-generic-password -a "$USER" -s "Claude Code-credentials" \
        -w "$(cat "$CREDS_FILE")" 2>/dev/null
}

TOKEN=$(extract_token) || exit 1
CLAUDE_CODE_OAUTH_TOKEN="$TOKEN" claude "$@"

Usage: claude-batch -p "prompt" --model sonnet instead of claude -p.
After batch: call restore_keychain.

Tested: 30 parallel calls from Cursor Bash tool, 30/30 success, extension auth preserved.

Related Issues

• Frequent re-authentication required with multiple concurrent Claude Code sessions (OAuth refresh token race condition) #24317 — OAuth token refresh race condition (primary tracking issue)
• Background agents completing in parallel trigger 'Not logged in' and corrupt session credentials #37203 — Background agents trigger 'Not logged in'
• Session token expires within minutes when multiple subagents are spawned concurrently #37324 — Session token expires with concurrent subagents
• [BUG] Session Token Expiry Kills Active Agents Without Warning #37468 — 5 parallel agents, 3 hours of work lost
• [BUG] macOS Keychain: security -i 4096-byte line buffer causes credential corruption with MCP OAuth plugins #30337 — macOS Keychain 4KB buffer credential corruption (fixed v2.1.78)

[github-actions]

Found 3 possible duplicate issues:

1. CLAUDE_CODE_OAUTH_TOKEN breaks Chrome extension (--chrome) #29924
2. [BUG] OAuth credentials not persisted to Keychain — only mcpOAuth stored, auth token missing #36779
3. Background agents completing in parallel trigger 'Not logged in' and corrupt session credentials #37203

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

[LARIkoz]

This is not a duplicate of any of the suggested issues. Here's why:

#29924 — CLAUDE_CODE_OAUTH_TOKEN breaks Chrome extension (--chrome). Different feature (Chrome extension), different symptom (extension disconnection). Our bug is about Keychain entry deletion on macOS during parallel CLI usage.

#36779 — OAuth credentials not persisted to Keychain (only mcpOAuth stored). This is about credentials never being written to Keychain in the first place. Our bug is about credentials being actively deleted from Keychain when CLAUDE_CODE_OAUTH_TOKEN env var is set.

#37203 — Background agents trigger 'Not logged in'. This is about the Agent tool with run_in_background: true in interactive sessions. Our bug is specifically about CLAUDE_CODE_OAUTH_TOKEN env var causing silent Keychain deletion on process exit — a distinct code path in the credential store's fallback combiner logic.

What makes this issue unique:

1. We reverse-engineered the exact mechanism: the credential store uses a fallback combiner (FI7) where "successful write to backend A → delete from backend B." When CLAUDE_CODE_OAUTH_TOKEN is set, a write to the plaintext file triggers deletion of the Keychain entry — even though the env var should make the process read-only with respect to credential storage.

2. This is a destructive side effect of a documented feature (CLAUDE_CODE_OAUTH_TOKEN). The env var is supposed to bypass credential storage, not destroy it.

3. Reproduction is straightforward and deterministic (see Steps to Reproduce in the original report).

4. The workaround (backup + restore) is provided with tested code.

None of the suggested duplicates describe this specific credential deletion behavior.

[LARIkoz]

Update: 100% Fix Found — PATH Shim Interceptor

After extensive testing and a multi-model code review consilium (Gemini 2.5 Pro, Grok-4, DeepSeek R1, Mistral Large, Codex GPT-5.4 — all 5 independently proposed the same approach), we found a 100% reliable workaround for this bug.

The Approach: PATH Shim

A temporary wrapper script for /usr/bin/security is placed first in PATH for worker processes. It inspects arguments — if it's delete-generic-password for Claude Code-credentials, it exits 0 (success) without calling the real binary. Everything else passes through.

#!/bin/bash
# /tmp/shim/security — placed first in PATH for workers
REAL_SECURITY="/usr/bin/security"

is_delete=false
for arg in "$@"; do
    [ "$arg" = "delete-generic-password" ] && is_delete=true
done

if $is_delete; then
    for arg in "$@"; do
        [ "$arg" = "Claude Code-credentials" ] && exit 0  # block silently
    done
fi

exec "$REAL_SECURITY" "$@"  # pass through everything else

Workers are launched with:

PATH="/tmp/shim:$PATH" \
CLAUDE_CODE_OAUTH_TOKEN="$token" \
CLAUDE_CONFIG_DIR="/tmp/worker_N/" \
claude -p "..." --model sonnet

Test Results

Scenario	Before fix	After fix
10 parallel from Cursor Bash	Keychain deleted sometimes	10/10 OK, Keychain intact
30 parallel from Cursor Bash	Keychain DELETED (1/3 tests)	30/30 OK, Keychain INTACT
Extension auth	Kicked out after ~60 calls	Never kicked out
Post-batch credentials	File or Keychain missing	Both intact

Why This Works

1. The CLI's shutdown handler calls security delete-generic-password — the shim intercepts this and returns success
2. The CLI thinks deletion succeeded — no error handling, no retry
3. Real Keychain entry is never touched
4. Combined with CLAUDE_CODE_OAUTH_TOKEN (bypasses Keychain reads) and CLAUDE_CONFIG_DIR (isolates file ops), workers are fully sandboxed

Full Wrapper

The complete claude-batch v3 wrapper with all protections (token gate, concurrency cap, circuit-breaker, interceptor, backup/restore) is available. Happy to share if useful for others hitting this issue.

Root Cause Reminder

The underlying bug remains: CLAUDE_CODE_OAUTH_TOKEN should make the CLI read-only with respect to credential storage, but the shutdown/cleanup handler ignores this env var and deletes Keychain entries anyway. The fix should be a one-line check in the CLI:

// In the credential cleanup/shutdown handler:
if (process.env.CLAUDE_CODE_OAUTH_TOKEN) return; // don't touch storage

[LARIkoz]

Update 2: tmux isolation = complete fix

The PATH shim from Update 1 prevented Keychain deletion but did NOT prevent the refresh token race condition. Extension was still kicked out after ~400 calls at 10 parallel.

Root cause clarification: The problem is not just Keychain deletion — it's that ANY claude processes spawned from Cursor's process tree (Electron → Node.js → PTY Host → bash → claude) share auth state with the Extension. Even with CLAUDE_CODE_OAUTH_TOKEN bypassing Keychain reads, the processes somehow disrupt Extension auth.

Solution: tmux-isolated execution

Workers now run in detached tmux sessions instead of directly from Cursor's Bash tool:

tmux new-session -d -s "worker-$id" \
    "claude -p '...' --model sonnet > /tmp/job/stdout.log 2>stderr.log; echo \$? > exit_code"

Key insight (from code review consilium): Do NOT pass CLAUDE_CODE_OAUTH_TOKEN. Let tmux-hosted claude processes authenticate exactly like Terminal.app does — naturally, with their own Keychain access in a separate process tree.

Why this works

tmux server (/opt/homebrew/bin/tmux) is a separate daemon, not a child of Cursor/Electron. Same isolation as Terminal.app which was proven 48/48 with zero kickouts.

Test results

Scenario	v3 (PATH shim)	v4 (tmux)
10 parallel	Extension kicked after ~400	7/10 OK, Extension intact
30 parallel	Extension kicked	22/30 OK, Extension intact
Extension auth	Lost	Never lost

3/10 and 8/30 failures are rate limits / tmux session collisions, not auth issues. Retry handles them.

Wrapper available

claude-batch v4.3 — drop-in replacement: claude-batch -p "prompt" --model sonnet. Includes retry with exponential backoff, concurrency cap, trap cleanup. Code-reviewed by 6 models across 3 rounds (final: 6/6 SHIP).

[LARIkoz]

Update 3: "Prevent refresh, don't fix race" — validated strategy

After red team review (5 agents) found that tmux workers still share Keychain and CAN race on token refresh, we identified the core insight:

Terminal.app's 48/48 success wasn't from "magical isolation" — it worked because the token was fresh (8h) and the 40-min batch triggered ZERO refreshes. No refresh = no race = no kickout.

Strategy (6/6 consilium APPROVE)

Instead of fixing the race condition (that's Anthropic's job), guarantee no refresh happens during batch:

1. Pre-batch force refresh — single claude -p "ping" → fresh 8h token
2. 2-hour token gate — refuse to start batch if token < 2h remaining. For 800 calls at 10 parallel (~40 min), this gives 3x safety margin
3. tmux isolation — insurance: even if something unexpected triggers refresh, Extension is in a separate process tree
4. Jitter in retry — stagger retries to prevent thundering herd
5. Per-job 5-min timeout — kill hung workers that stall capacity
6. Prompt via temp file — avoid shell argument overflow for large prompts

Why this works

The CLI's refresh code (_P1()) only triggers when expiresAt is reached. With a fresh 8h token and a 40-min batch, the refresh path is never entered. No refresh = no Keychain write = no race condition = no kickout.

Limitations (honest)

• ~95-98% protection, not 100% (server-side revocation could force refresh — but negligible in 40-min window)
• If Anthropic changes token lifetime to < 1h, the gate needs adjustment

claude-batch v5

Updated wrapper implements all 7 points. Drop-in: claude-batch -p "prompt" --model sonnet.