fix(windows): support CLAUDE_CODE_OAUTH_TOKEN env var and write auth.json to Roaming AppData

[jstruv-bot]

Problem

Two Windows-specific bugs that prevent the plugin from working when Claude Code is launched from Claude Desktop:

Bug 1 — Credentials never found when CLAUDE_CODE_OAUTH_TOKEN is set

Claude Desktop sets CLAUDE_CODE_OAUTH_TOKEN in the environment of every process it spawns (including terminal windows). When this env var is present, claude auth login considers the session already authenticated and exits without writing ~/.claude/.credentials.json. The plugin's readAllClaudeAccounts() finds no credentials file and returns an empty list, causing OpenCode to show:

Claude Code credentials are unavailable or expired. Run `claude` to refresh them.

Bug 2 — Plugin syncs auth.json to the wrong Windows path

getAuthJsonPaths() wrote auth.json to %LOCALAPPDATA%\opencode\auth.json and the XDG path, but OpenCode stores its data directory in %APPDATA% (Roaming). OpenCode never saw the credentials the plugin synced.

Fix

src/keychain.ts

• Added readEnvToken(): reads CLAUDE_CODE_OAUTH_TOKEN, decodes the JWT exp claim for expiresAt (defaults to 10 h if decode fails), returns credentials with empty refreshToken
• readAllClaudeAccounts(): falls back to readEnvToken() (source: "env") when the credentials file is absent on non-macOS
• writeBackCredentials("env"): returns false immediately (read-only source)
• refreshAccount("env"): re-reads the env var

src/credentials.ts

• getAuthJsonPaths(): adds %APPDATA%\opencode\auth.json (Roaming) to the Windows sync targets
• refreshIfNeeded(): for "env" source, skips the 60-second CLI fallback and returns null immediately if the token has expired, avoiding a long hang

[bvironn]

Read the diff — base on main: 213/213 tests pass, but the PR adds 0 new tests despite introducing three non-trivial code paths:

• readEnvToken() (JWT decode + 10h fallback) — src/keychain.ts:181-217
• Roaming AppData path in getAuthJsonPaths() — src/credentials.ts:98-115
• Env-source short-circuits in refreshIfNeeded(), writeBackCredentials(), refreshAccount()

Suggestions for tests:

1. readEnvToken() with valid JWT, malformed JWT (covers 10h fallback), and missing env var
2. getAuthJsonPaths() with process.platform === 'win32' mocked, asserting both Local and Roaming paths appear
3. refreshIfNeeded() returns null immediately for source: "env" when token is expired (avoiding the 60s CLI hang you mention in the PR body)

Windows-specific behavior is hard to verify in CI without coverage — easy to regress silently. Code itself looks correct; just needs the safety net.

[griffinmartin]

Pushed 7eaa628 to address @bvironn's review (no new tests).

Added 14 tests covering all three areas you flagged. Tests now go from 213 → 227, all passing on a non-Windows runner via platform mocking.

readEnvToken (src/keychain.test.ts) — exercised through the already-exported refreshAccount("env") so no internals had to be exposed:

• Valid JWT with exp claim → expiresAt = exp * 1000.
• Three malformed-JWT variants (not base64, single segment, missing exp) → all hit the 10h fallback.
• Missing CLAUDE_CODE_OAUTH_TOKEN → null.
• Empty refreshToken is asserted on the returned creds.
• writeBackCredentials("env", …) returns false.

getAuthJsonPaths (src/credentials.test.ts) — needed a 1-keyword export (no behaviour change). Tests use Object.defineProperty(process, "platform", …) to simulate Windows on a Linux/macOS runner:

• non-Windows → [xdg] only.
• Windows w/ both env vars → [xdg, %LOCALAPPDATA%/opencode/auth.json, %APPDATA%/opencode/auth.json] in that order.
• Windows w/o env vars → fallback to homedir()/AppData/{Local,Roaming}/....
• Explicit regression guard: both Local and Roaming are present (this is bug 2 in your PR description).

refreshIfNeeded env short-circuit (src/credentials.test.ts) — extends the existing temp-file rewrite pattern with a stubbed refreshAccount that returns the configured env credentials and counts calls. The CLI fallback would call refreshAccount a second time after refreshViaCli(), so asserting the call count is exactly 1 proves the env block engaged and the 60s CLI hang was avoided. Three scenarios:

• Env token also expired → null, count===1.
• Env var rotated to a fresh token → returns refreshed creds, account updated in place, count===1.
• Env var unset entirely → null, count===1.

Small production-code nit also included (src/keychain.ts): the catch block inside readEnvToken now logs the decode failure instead of swallowing it silently, matching the style of readKeychainEntry earlier in the same file. Felt right given the spirit of the PR is "don't fail silently."

Verified: make all clean (lint + build + 227/227 tests pass).

[griffinmartin]

Pushed aefe0a8 to update the README. Three things were stale or missing:

1. "How it works" still listed the Windows sync as two paths (XDG + Local). Updated to three (XDG + Local + Roaming) with a short note that OpenCode itself reads from the Roaming %APPDATA% location — that's what motivated bug 2 in this PR.
2. New paragraph in "How it works" describing the CLAUDE_CODE_OAUTH_TOKEN fallback path: why it exists (Claude Desktop suppresses claude auth login writes), when it activates (Windows + no on-disk credentials), and that it has no refresh token.
3. "Environment variable overrides" table now lists CLAUDE_CODE_OAUTH_TOKEN with a clear note that it's read-only and set automatically by Claude Desktop, not intended for manual use — to avoid users thinking they should set it themselves.
4. "How it works (technical)" bullets updated to match: three Windows paths instead of two, plus a new bullet for the env fallback's read-only nature, JWT exp decoding, and the no-CLI-fallback short-circuit on expiry.
5. "Prerequisites" notes the env fallback in passing.

make all clean (lint + build + 227/227 tests pass).

[griffinmartin]

@jstruv-bot @bvironn — pushed 930cf37: merged latest main into the branch and applied two follow-up fixes from a Windows regression analysis I ran on the branch.

Merge conflict resolution

• README.md: env-var override table — both branches added a row. Kept the new OPENCODE_CLAUDE_AUTH_MAX_RETRY_MS row from main and re-added CLAUDE_CODE_OAUTH_TOKEN from this PR after it.
• src/keychain.ts: auto-merged. PR fix: increase max buffer for reading keychain dump #201 (now in main) edited the catch block of listClaudeKeychainServices to capture the underlying error; this PR added readEnvToken further down. Both preserved cleanly.

Follow-up fixes from regression analysis

1. src/index.ts — sourceDescription env arm. The auth-picker description used a 2-arm conditional that bucketed every non-'file' source as 'macOS Keychain'. With this PR's new 'env' source, a Windows user authenticated via Claude Desktop's CLAUDE_CODE_OAUTH_TOKEN would have seen "credentials loaded from macOS Keychain" — wrong on every axis. Added an 'env' arm that says "CLAUDE_CODE_OAUTH_TOKEN environment variable".

2. src/credentials.ts — syncAuthJson continue-on-error. The sync loop re-threw on the first per-path failure, aborting subsequent paths and tearing down the unhandled callers (plugin init, account-switch authorize). With this PR adding a third Windows path (Roaming), the failure surface is 50% larger; an AV-locked or network-share-borked %APPDATA%\opencode\auth.json could break plugin startup. Per-path failures are now logged and the loop continues — each target is independent.

3. src/credentials.test.ts — regression test for feat: add release workflow with auto-tagging #2. Pre-creates a directory at the XDG target path so writeFileSync fails with EISDIR, asserts syncAuthJson does not throw.

Verification: make all clean (lint + build + 233/233 tests pass — was 227/227 before merge; main contributed +5 tests, this commit adds +1 for the new contract).

PR is back to non-conflicting state and ready for re-review.

[griffinmartin]

@greptileai

[greptile-apps]

Greptile Summary

This PR fixes two Windows-specific bugs that prevented the plugin from working when OpenCode is launched from Claude Desktop: credentials were never found because CLAUDE_CODE_OAUTH_TOKEN stops the CLI from writing a credentials file, and auth.json was synced to %LOCALAPPDATA% while OpenCode reads from %APPDATA% (Roaming).

• Adds readEnvToken() in src/keychain.ts to decode CLAUDE_CODE_OAUTH_TOKEN as a last-resort credential source on non-macOS when the credentials file is absent; the JWT exp claim is decoded for expiresAt with a 10-hour default fallback, and the source is marked read-only (writeBackCredentials returns false).
• Adds %APPDATA%\opencode\auth.json (Roaming) to the Windows sync targets in getAuthJsonPaths() and removes the throw err inside syncAuthJson so a failure on one path no longer aborts writes to the remaining paths.
• Adds refreshIfNeeded short-circuit for source === "env" that re-reads the env var and returns null immediately on expiry, avoiding a 60-second CLI timeout that would have no effect.

Confidence Score: 4/5

Safe to merge; the new env-token path is well-isolated and tested, and the two concrete Windows bugs are correctly addressed.

The two main code changes (env fallback and Roaming AppData path) are correct and well-tested. The one behavioural change worth watching is in syncAuthJson: removing throw err was necessary for the Windows multi-path case but also makes macOS/Linux sync failures silent — a persistent filesystem error on those platforms will now only appear in debug logs. There is also a mildly misleading comment in refreshIfNeeded about the parent process rotating the env var, which could confuse future maintainers. Neither concern affects runtime correctness for the target scenario.

Files Needing Attention: src/credentials.ts — the syncAuthJson error-swallowing change and the env-rotation comment both live here.

Important Files Changed

Filename	Overview
src/keychain.ts	Adds readEnvToken() to decode CLAUDE_CODE_OAUTH_TOKEN as a fallback credential source; extends readAllClaudeAccounts(), writeBackCredentials(), and refreshAccount() to handle the new "env" source cleanly.
src/credentials.ts	Exports getAuthJsonPaths() and adds the Roaming %APPDATA% path for Windows; adds env source short-circuit in refreshIfNeeded(); removes the throw in syncAuthJson so a single bad path no longer aborts subsequent writes.
src/index.ts	Minor UI copy update: adds an "env" branch to the sourceDescription ternary so the auth confirmation message is accurate for the new env credential source.
src/keychain.test.ts	Adds comprehensive tests for readEnvToken (via refreshAccount("env")): JWT exp decoding, malformed/missing exp fallback, unset var, and writeBackCredentials no-op for "env" source.
src/credentials.test.ts	Adds tests for getAuthJsonPaths() (XDG, Local+Roaming Windows, fallback without env vars), syncAuthJson error-handling (EISDIR resilience), and the refreshIfNeeded env short-circuit with a counting stub keychain.
README.md	Documentation updated to cover the Roaming AppData path, the env var fallback behaviour, and a new CLAUDE_CODE_OAUTH_TOKEN row in the env-vars reference table.

Sequence Diagram

sequenceDiagram
    participant CD as Claude Desktop
    participant P as Plugin
    participant F as Credentials File
    participant E as CLAUDE_CODE_OAUTH_TOKEN env var
    participant R as refreshIfNeeded

    CD->>CD: "Set CLAUDE_CODE_OAUTH_TOKEN in child env"
    CD->>P: "Spawn OpenCode process"

    P->>F: "readCredentialsFile()"
    F-->>P: "null — CLI never wrote it"

    P->>E: "readEnvToken()"
    E-->>P: "{ accessToken, refreshToken:'', expiresAt }"
    P-->>P: "return [{ source:'env', credentials }]"

    Note over R: "On token near-expiry..."
    R->>E: "refreshAccount('env') → readEnvToken()"
    alt "env token still valid"
        E-->>R: "fresh credentials"
    else "env token expired"
        E-->>R: "expiresAt in past → return null, skip CLI"
    end

    Note over P: "Windows auth.json sync"
    P->>P: "syncToPath(XDG path)"
    P->>P: "syncToPath(%LOCALAPPDATA%)"
    P->>P: "syncToPath(%APPDATA% Roaming)"

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
src/credentials.ts:308-312
The comment overstates what re-reading the env var can accomplish. Standard OS process semantics don't allow a parent process to update the environment of an already-running child process, so "Claude Desktop refreshed and updated its child environment" won't happen through normal means. The re-read is still worth doing (it's cheap and handles any in-process mutation of `process.env`), but the stated rationale will mislead future maintainers.

```suggestion
  // Env-var credentials have no refresh token and no CLI path.
  // Re-read the env var in case process.env was mutated in-process since the
  // last readAllClaudeAccounts() call. If the token has genuinely expired,
  // return null immediately rather than blocking for up to 60 s on a CLI
  // timeout that cannot help (the CLI would also see CLAUDE_CODE_OAUTH_TOKEN
  // and skip writing credentials to disk).
```

### Issue 2 of 2
src/credentials.ts:149-166
**Silent failure now applies to all platforms**

Removing `throw err` was the right call for the Windows multi-path case (a failure on the first path would otherwise abort subsequent writes), but the change also affects macOS and Linux where there is only one target path (XDG). Previously, a persistent filesystem error on those platforms surfaced to the caller; now it is silently swallowed and only visible in the debug log. If the XDG path is unwritable on Linux (e.g. a permission regression from a botched install), the plugin will appear to work while auth.json never gets updated, which can be hard to diagnose without debug logging enabled. Consider emitting a warning-level log entry or a console message when `syncToPath` fails on non-Windows so the silent-failure behaviour remains intentional and observable.

_{Reviews (1): Last reviewed commit: "Merge origin/main into fix/windows-env-t..." | Re-trigger Greptile}

[greptile-apps]

The comment overstates what re-reading the env var can accomplish. Standard OS process semantics don't allow a parent process to update the environment of an already-running child process, so "Claude Desktop refreshed and updated its child environment" won't happen through normal means. The re-read is still worth doing (it's cheap and handles any in-process mutation of process.env), but the stated rationale will mislead future maintainers.

Suggested change

	// Env-var credentials have no refresh token and no CLI path.
	// Re-read the env var in case it was rotated by the parent process (e.g.
	// Claude Desktop refreshed and updated its child environment). If it has
	// genuinely expired, return null immediately rather than blocking for up to
	// 60 s on a CLI timeout that cannot help.
	// Env-var credentials have no refresh token and no CLI path.
	// Re-read the env var in case process.env was mutated in-process since the
	// last readAllClaudeAccounts() call. If the token has genuinely expired,
	// return null immediately rather than blocking for up to 60 s on a CLI
	// timeout that cannot help (the CLI would also see CLAUDE_CODE_OAUTH_TOKEN
	// and skip writing credentials to disk).

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/credentials.ts
Line: 308-312

Comment:
The comment overstates what re-reading the env var can accomplish. Standard OS process semantics don't allow a parent process to update the environment of an already-running child process, so "Claude Desktop refreshed and updated its child environment" won't happen through normal means. The re-read is still worth doing (it's cheap and handles any in-process mutation of `process.env`), but the stated rationale will mislead future maintainers.

```suggestion
  // Env-var credentials have no refresh token and no CLI path.
  // Re-read the env var in case process.env was mutated in-process since the
  // last readAllClaudeAccounts() call. If the token has genuinely expired,
  // return null immediately rather than blocking for up to 60 s on a CLI
  // timeout that cannot help (the CLI would also see CLAUDE_CODE_OAUTH_TOKEN
  // and skip writing credentials to disk).
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Silent failure now applies to all platforms

Removing throw err was the right call for the Windows multi-path case (a failure on the first path would otherwise abort subsequent writes), but the change also affects macOS and Linux where there is only one target path (XDG). Previously, a persistent filesystem error on those platforms surfaced to the caller; now it is silently swallowed and only visible in the debug log. If the XDG path is unwritable on Linux (e.g. a permission regression from a botched install), the plugin will appear to work while auth.json never gets updated, which can be hard to diagnose without debug logging enabled. Consider emitting a warning-level log entry or a console message when syncToPath fails on non-Windows so the silent-failure behaviour remains intentional and observable.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/credentials.ts
Line: 149-166

Comment:
**Silent failure now applies to all platforms**

Removing `throw err` was the right call for the Windows multi-path case (a failure on the first path would otherwise abort subsequent writes), but the change also affects macOS and Linux where there is only one target path (XDG). Previously, a persistent filesystem error on those platforms surfaced to the caller; now it is silently swallowed and only visible in the debug log. If the XDG path is unwritable on Linux (e.g. a permission regression from a botched install), the plugin will appear to work while auth.json never gets updated, which can be hard to diagnose without debug logging enabled. Consider emitting a warning-level log entry or a console message when `syncToPath` fails on non-Windows so the silent-failure behaviour remains intentional and observable.

How can I resolve this? If you propose a fix, please make it concise.