Claude Usage Widget reads one local file on your machine: ~/.claude/.credentials.json (created and maintained by Claude Code). It uses the claudeAiOauth.accessToken field from that file to make HTTP requests to only one endpoint:
https://api.anthropic.com/api/oauth/usage— Anthropic's official rate-limit usage endpoint.
That is the entire network surface. No telemetry. No analytics. No third-party hosts. No keys, tokens, or usage data ever leave your machine outside this single call.
- We do not scrape
claude.aicookies or use Cloudflare-protected session tokens. - We do not call any third-party API or CDN at runtime.
- We do not log, write to disk, or send the OAuth token anywhere except the
Authorization: Bearer ...header on the request above. - We do not ship binaries that auto-update from any source other than GitHub Releases over HTTPS (and only if you opt in to a future auto-update channel).
| Path | Contents |
|---|---|
%APPDATA%\claude-usage-widget\config.json |
Your UI preferences (theme, opacity, thresholds, layout choices, reset-hook commands you set yourself). No tokens. |
%APPDATA%\claude-usage-widget\history.json |
A rolling 7-day series of utilization percentages and reset timestamps. No tokens, no message contents. |
The Settings panel lets you configure shell commands that run when a quota resets. Those commands are stored verbatim in config.json and executed as spawn(command, { shell: true, detached: true, stdio: 'ignore' }) with these extra environment variables:
CLAUDE_RESET_ID
CLAUDE_RESET_LABEL
CLAUDE_RESET_AT
CLAUDE_RESET_PREVIOUS_UTIL
Only you can set these commands. They run with your user's privileges. Treat them as you would any other shell snippet you write.
If you find a security issue:
- Do not open a public GitHub issue.
- Open a private security advisory on this repository, or
- Email the maintainer (see package.json
authorfield).
We aim to acknowledge reports within 72 hours and ship a fix or mitigation within 14 days for confirmed issues.
This project depends on Electron, electron-builder, gifenc, and Node's standard library. We pin major versions in package.json and commit package-lock.json for reproducible installs. We do not use any package that downloads or executes remote code at install time beyond Electron's own postinstall (which fetches the Electron binary from the official https://github.com/electron/electron releases).