# 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. |
| ![Anthropic theme](docs/screenshots/anthropic.png) | ![Instrument theme](docs/screenshots/instrument.png) |
| **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. |
| ![Editorial theme](docs/screenshots/editorial.png) | ![Retro CRT theme](docs/screenshots/retro.png) |

## 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.