feat: zero-config Claude quota discovery

[giuliastro]

Summary

Adds zero-config Claude quota discovery, reusing authentication that already exists on the machine.

What it supports

• Claude Code OAuth credentials when already present
• Claude Desktop OAuth on Windows, read-only
  • standard %APPDATA%\Claude
  • Microsoft Store/MSIX profile under %LOCALAPPDATA%\Packages\...\LocalCache\Roaming\Claude
  • Electron safeStorage decrypted locally with Windows DPAPI + BCrypt, using Python stdlib only
• Claude Code's own ~/.claude.json -> cachedUsageUtilization as a no-auth fallback

Safety / behavior

• no login flow is initiated
• Claude Desktop refresh tokens are never read, refreshed, or written back
• only the current access token is borrowed to query Anthropic's official usage endpoint
• provider data stays local
• cached usage is marked stale when appropriate

Validation

Manual Windows validation passed on a machine where:

• Claude Desktop was already installed and authenticated
• Claude Code was not authenticated and had no credentials/cache
• running cclimits --claude discovered the existing Desktop OAuth session automatically and returned live 5-hour / 7-day quota data
• output reported Source: Claude Desktop OAuth (read-only)

Focused tests cover source precedence, cache parsing/staleness, Desktop token-cache parsing, expired-token rejection, and Windows/MSIX profile discovery.

The Windows safeStorage implementation is adapted from the MIT-licensed huanchong-99/claude-usage-assistant project, with attribution in code.

[cruzanstx]

First: we genuinely love seeing cclimits being used on Windows. The real Windows/MSIX validation and read-only DPAPI approach are exactly the kind of cross-platform contribution we hoped for. Thank you for building and testing this.

The implementation is thoughtful, and the PR suite passes locally (271 passed). I found two issues that should be fixed before merge:

1. Stale local usage is rendered as healthy in compact output (lib/cclimits.py:769-807, lib/cclimits.py:2557-2560).

   A two-hour-old cachedUsageUtilization snapshot produces:

   Claude: 10.0% (5h) ✅
   

   Detailed/JSON output carries source_stale, but --oneline ignores it. A snapshot with no valid fetchedAtMs is also returned as status: "ok" with no age or stale marker at all. That makes old/undated data indistinguishable from live quota in the format most likely to be embedded in status lines.

   Please either reject stale/undated local snapshots as the automatic fallback, or propagate an explicit stale/unknown marker into --oneline. Add coverage for both an old timestamp and a missing timestamp.

2. The copied MIT implementation needs its upstream license notice preserved (lib/cclimits.py:394-395, _win_dpapi_unprotect, and _win_gcm_decrypt).

   The attribution comment is good, but the upstream MIT license requires its copyright and permission notice to accompany copies or substantial portions. Please add the Copyright (c) 2026 claude-usage-assistant contributors MIT notice to the distributed license/third-party notices. If using a separate notice file, include it in package.json.files so it is present in the npm tarball.

Two non-blocking cleanups worth including:

• source_path exposes and caches the full Windows profile path, including the username (lib/cclimits.py:695, :772, :856). The source label is sufficient for normal JSON; reserve paths for explicit debug output.
• TestGetClaudeUsage.test_no_credentials only patches get_claude_credentials, so it fails on machines that actually have a Claude Desktop session or cachedUsageUtilization. Patch the new Desktop/cache discovery functions so the test remains hermetic.

Also, the PR title currently ends with the duplicated text Feature/claude zero config.

[cruzanstx]

One additional cross-platform issue from the final review pass:

macOS Desktop detection currently promises a recovery path that cannot work (lib/cclimits.py:441-444, :624-632, :715-720, :831-835).

On macOS, _claude_desktop_dir_candidates() and _claude_desktop_detected() recognize ~/Library/Application Support/Claude, but _claude_desktop_tokens() immediately returns [] for every non-Windows platform. With a Desktop profile present and no Claude Code credentials, the CLI therefore says:

Keep Claude Desktop signed in and retry; no Claude CLI login is required.

Retrying cannot succeed because Desktop OAuth extraction is implemented only for Windows. Please either implement the macOS safeStorage/Keychain path or restrict Desktop detection and that hint to Windows. The help text should also state explicitly that Desktop OAuth discovery is currently Windows-only.

This does not diminish the Windows work—we’re especially glad to see cclimits being used and validated there—but the other-platform guidance needs to remain accurate.

[cruzanstx]

Re-reviewed at 26a7c035dfe5080020d854c70ce516dabe0d51df. All requested code changes are resolved:

• stale and undated Claude Code snapshots now fail closed instead of appearing live in compact output;
• Windows profile paths are no longer returned or cached;
• macOS/Linux guidance now accurately states that Claude Desktop OAuth discovery is Windows-only;
• the no-credentials test is isolated from real local Claude state;
• the upstream MIT notice is preserved and verified in the npm tarball.

Local verification passed: 274 passed, focused Claude tests 17 passed, stale-cache reproduction now reports Claude: 🔑, and npm pack --dry-run includes THIRD_PARTY_NOTICES.md.

Approved. Thank you again for the careful Windows implementation and quick follow-up.

One non-blocking housekeeping item remains: please clean the duplicated Feature/claude zero config suffix from the PR title before merge.