99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# Claude Usage Widget
|
||
|
||
A small always-on-top Windows desktop widget that shows your live Claude
|
||
subscription usage — the same percentages Claude Code's `/usage` command
|
||
displays, refreshed every 5 minutes.
|
||
|
||
## Themes
|
||
|
||
Pick one in Settings; it applies live. Each is its own typographic + chromatic system.
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Anthropic** — warm cream-on-charcoal, Newsreader serif + DM Sans, sunset-orange ring, soft radial halo. The default. | **Instrument** — modular-synth panel, JetBrains Mono, chartreuse on slate, tick marks at 12/3/6/9, faint scanlines, bracket corners on the title bar. |
|
||
|  |  |
|
||
| **Editorial** — magazine artifact, Fraunces variable serif (optical-size axis), saffron on warm charcoal, italic labels, hairline rules. | **Retro CRT** — 1980s home computer, IBM Plex Mono, phosphor green on near-black, scanlines + vignette, bracketed `[ Claude Usage ]` header, blink cursor in the corner. |
|
||
|  |  |
|
||
|
||
## Install
|
||
|
||
1. **Download** the latest `Claude.Usage.Widget_<version>_x64-setup.exe`
|
||
from the Forgejo releases page.
|
||
2. **Run the installer.** Windows SmartScreen will warn "unrecognized publisher"
|
||
(it's not code-signed). Click **More info → Run anyway**.
|
||
3. The widget pops up in the upper-left corner. Drag it where you want.
|
||
|
||
## Requirements
|
||
|
||
- **Windows 10/11** with [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||
(preinstalled on Windows 11; downloadable on Windows 10).
|
||
- **[Claude Code](https://docs.claude.com/en/docs/claude-code)** installed and signed in.
|
||
- Native Windows install (`claude.exe` on PATH) → works automatically.
|
||
- Or installed inside WSL → also works automatically; the widget probes each
|
||
distro to find one with `claude`.
|
||
|
||
## Using it
|
||
|
||
- The big ring shows your **current 5-hour session** percentage with a reset countdown.
|
||
- The bars below show the **rolling weekly** limits (all models + Sonnet only).
|
||
- Per-model breakdown (Opus / Sonnet / Haiku) shows how much of *your local
|
||
current 5-hour block* came from each — derived from your local Claude Code
|
||
transcripts. (Anthropic's `/usage` doesn't break this out, so we compute it
|
||
ourselves.)
|
||
- **↻** button (title bar) — force-refresh `/usage` right now.
|
||
- **⚙** — Settings (custom claude command, refresh interval, autostart, distro override).
|
||
- **×** — quit.
|
||
- The window is **resizable** — drag any edge.
|
||
- **System tray** — there's a tray icon next to the Windows clock while the
|
||
widget is running. Left-click to bring the window back if you lose it
|
||
off-screen; right-click for Show / Hide / Refresh / Quit.
|
||
|
||
## Troubleshooting
|
||
|
||
**"Claude Code not found"** — the widget couldn't find a `claude` to run. Make sure
|
||
`claude --version` works in either PowerShell or a WSL shell. If it works in
|
||
a non-default WSL distro, open Settings and set **claude command** to e.g.
|
||
`wsl.exe -d Debian bash -lc claude`.
|
||
|
||
**Ring shows "no /usage data"** — the spawn worked but Anthropic's output didn't
|
||
match the parser. Open Settings → Test /usage now → expand the *raw output*
|
||
disclosure and file an issue with what's there.
|
||
|
||
**SmartScreen blocks the installer** — expected; the binary isn't code-signed.
|
||
"More info → Run anyway".
|
||
|
||
**Autostart toggle doesn't survive reboot** — that's the dev build limitation.
|
||
The released installer registers a stable path so autostart works correctly there.
|
||
|
||
## Privacy
|
||
|
||
Everything stays on your machine. The widget:
|
||
|
||
- Reads your local Claude Code config (`~/.claude/projects/`) for the per-model breakdown.
|
||
- Spawns `claude /usage` to read live percentages — that command Anthropic
|
||
serves from their backend over your existing Claude Code session, exactly
|
||
the same as when you type `/usage` interactively. The widget never sees
|
||
your OAuth token.
|
||
- Stores its own settings at `%APPDATA%\claude-widget\config.json`.
|
||
- Makes no other network calls.
|
||
|
||
## Building from source
|
||
|
||
You need a **Windows host** with:
|
||
|
||
```powershell
|
||
winget install Rustlang.Rustup OpenJS.NodeJS.LTS Microsoft.VisualStudio.2022.BuildTools
|
||
rustup default stable-x86_64-pc-windows-msvc
|
||
corepack enable
|
||
corepack prepare pnpm@latest --activate
|
||
```
|
||
|
||
Then in this repo:
|
||
|
||
```powershell
|
||
pnpm install
|
||
pnpm tauri dev # iterate
|
||
pnpm tauri build # produces NSIS installer in src-tauri\target\release\bundle\nsis\
|
||
```
|
||
|
||
Filing issues / pull requests on the Forgejo repo is welcome.
|