Skip to content

Refresh a lapsed Claude Code access token by running its CLI - #16616

Open
isc wants to merge 4 commits into
omacom:quattrofrom
isc:agent-usage-claude-refresh
Open

isc wants to merge 4 commits into
omacom:quattrofrom
isc:agent-usage-claude-refresh

Conversation

@isc

@isc isc commented Oct 25, 2026 •

Copy link
Copy Markdown

Omarchy offers the Claude desktop app in Install > AI (#10755), but for anyone who uses Claude Code only through it, the agents panel's Claude limits stay paused for good. This is the bug #12470 reports, in the one setup where using Claude Code never clears it.

The Claude collector reads the access token the Claude Code CLI keeps in .credentials.json. That token lives about eight hours, and only the CLI renews it, when it runs. #14049 made a lapsed access token with a live refresh token read "Limits paused" rather than "Sign-in expired" (#8092, #12470), but the panel still waits for someone to start the CLI.

The desktop app never starts it: the app keeps a sign-in of its own, so ~/.claude/.credentials.json is never renewed. On one such machine (Omarchy quattro, omarchy-dev 4.0.0.r7294.gb72863a) the access token had lapsed since October 18. Until #14040 the panel kept showing that day's claude-limits.json, zeroed by the weekly reset; since #14040 keys the cache by account, it has nothing left to show.

When the access token has lapsed and the refresh token still holds, the collector now runs claude auth status in the home it is reading, reads the credentials again, and probes as usual if they now hold a live token. Otherwise the "Limits paused" behaviour stays exactly as it is. auth status asks the model nothing, so it costs no quota. This is the "refresh instead of reporting" option from #12470, with the CLI doing the refresh:

  • The CLI is the only writer. The collector never writes .credentials.json and does not implement the OAuth exchange: the refresh token changes with every use, so a second refresher would race the CLI for it (the sharp edge Agents panel reports SIGN-IN EXPIRED when only the 8-hour access token lapsed #12470 describes), and it would be acting as Claude Code's OAuth client.
  • It runs at most once every half hour per sign-in, stamped in the agent-usage cache; --force (pressing refresh) skips the wait. Runs take turns under a lock beside the stamp, and one that waited on another finds the token renewed and runs nothing, so two collectors at once never race each other for the refresh token. It never runs when the refresh token has lapsed or there is no token.
  • It runs the installed binary, never a mise shim, account wrapper or lazy launcher that would install or update it first. The lookup the Codex collector already used for this moves into collectors.py as find_installed_command(), so both collectors share it.
  • It runs in the home being read (CLAUDE_CONFIG_DIR set for any home but ~/.claude, whose profile is ~/.claude.json), with a 20-second timeout, and without the CLAUDECODE, CLAUDE_CODE_* or ANTHROPIC_* it would inherit: inside a Claude Code session, or with an Anthropic key, token or base URL, the CLI takes that credential and never touches the file. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 keeps telemetry and update checks out of a run nobody asked for.

Minimum version: 2.1.301. The collector asks claude --version first and leaves older CLIs alone. A comment on #12470 found that auth status on 2.1.278 did not refresh at all (doctor did, and a doctor loop once wiped both tokens), and the 2.1.301 changelog reads: "Fixed sign-in refresh timeouts and unexpected sign-outs after a short command such as claude auth status or claude plugin list exited in the middle of a token refresh". Below 2.1.301 the run does nothing or risks signing the home out, which is worse than paused limits. Omarchy installs claude through mise with auto_update = "4h", so nearly every machine is past it.

On the desktop-app machine above, with Claude Code 2.1.310, env -i HOME=$HOME PATH=$PATH claude auth status moved expiresAt eight hours ahead without any inference, and omarchy agent usage-update --limits-only claude then brought back the real limits (session 63%, weekly 11%).

Tests: agent-usage-claude-limits-test.sh puts a stand-in claude on an otherwise bare PATH and checks that a CLI that renews the token unpauses the limits, probed with the new token; that one renewing nothing leaves them paused; that the CLI runs once per half hour per sign-in, and again on --force; that two collectors started at once run it once; that a CLI older than 2.1.301 is only asked its version; that a lapsed refresh token runs nothing and reads "Sign-in expired"; that the CLI's environment carries no CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, ANTHROPIC_BASE_URL or, for ~/.claude, CLAUDE_CONFIG_DIR; and that a registered account's home is refreshed in place. The new checks fail on quattro. The Claude and Codex collector tests, agent-usage-accounts, -partition, -shared and -update pass. ./test/all ran on a Linux box that isn't an Omarchy desktop (no Hyprland, lua or ImageMagick): the same 50 of 452 shell test files and the same CLI checks fail with and without this change.

No visible change: the agents panel draws nothing new; Claude's limits come back live instead of staying paused.

🤖 Generated with Claude Code

@greptile-apps

greptile-apps Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new blocking issues were found.

Summary

The Claude collector now asks the installed CLI to renew a lapsed access token before checking usage limits.

  • Claude limit checks can renew an expired access token through the CLI.
  • Claude and Codex collectors share the same installed-command lookup.

Tests were reviewed but not run.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Read saved credentials] --> B{Access token lapsed and refresh token live?}
  B -- No --> G[Keep existing limits behavior]
  B -- Yes --> C[Lock and reread credentials]
  C --> D{Still lapsed and retry allowed?}
  D -- No --> F[Reread credentials]
  D -- Yes --> E[Check CLI version and run auth status]
  E --> F
  F --> G
Loading

Reviews (3) · Last reviewed commit: "Run one Claude sign-in refresh at a time" · Reviewed by Greptile

Comment thread bin/omarchy-agent-usage-claude Resolved
@omarchybot omarchybot added the enhancement New feature or request label Nov 2, 2026
isc and others added 4 commits November 8, 2026 08:39
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@isc
isc force-pushed the agent-usage-claude-refresh branch from 412d07a to df59f2e Compare November 8, 2026 08:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants