Claude Usage Monitor

🟫 Clauddy

A pixel-art desktop pet that keeps an eye on your Claude Code usage: the real session and weekly % from your account, the tokens from your local logs, and a pet that works, sleeps and catches fire along with it. It can follow Codex and Cursor too, and you can dress it as a pumpkin, a ghost or Santa.

  📚 Get started ·
  ✨ Features ·
  🏗️ Architecture ·
  ⚙️ Setup ·
  🧭 Decisions

https://github.com/user-attachments/assets/be8d339c-ac69-4980-96a7-8e286f8b080f

Stack

An Electron widget in vanilla JS, with Bun for the scripts and the tests, and Biome for format and lint.

More details, with every tool and version, in docs/design/01-architecture.md.

Requirements

- macOS on Apple Silicon (the first-class build), Windows x64 or Linux x64
- Claude Code, whose logs in ~/.claude/projects give the token counts; a Claude login, done once in Settings, gives the real %
- Bun, or Node 24 for npx, only to run it without installing or to work on the code
- Optional: Codex or the Cursor app on the same machine, to follow them too

Running

On macOS, as an app that opens at login:

Anywhere, without installing:

docs/design/03-setup.md has Windows and Linux, updating, running from the code and every setting in config.json.

Test

Never run bare bun test: the groups under test/ must each run in their own process (ADR-002). bun install turns on a pre-commit hook that formats the staged files and blocks on lint errors. CI runs the coverage gate on every pull request.

Releases

Every merge to main can be a release: semantic-release reads the Conventional Commit titles since the last tag (a feat bumps the minor, a fix or perf the patch, docs and chore nothing), builds the app on macOS, Windows and Linux runners, publishes the GitHub release and clauddy on npm. The whole…