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

```
┌─────── Claude Usage ────────────╳ ─┐
│                                     │
│         ╭───────╮                   │
│        ╱   72%   ╲                  │
│       │  session  │                 │
│        ╲ resets  ╱                  │
│         ╰ 2:50am ╯                  │
│                                     │
│   Models (current block)            │
│   ▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱                  │
│   ● Opus 42M   ● Haiku 3M           │
│                                     │
│   Weekly limits     resets May 9    │
│   All models    ▆░░░░░     8%       │
│   Sonnet        ▃░░░░░     5%       │
└─────────────────────────────────────┘
```

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

## 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\
```

Project layout, architecture decisions, and known follow-ups live in
[`memory.md`](./memory.md).