🟫 Clauddy

A cute pixel-art desktop pet for macOS that tracks your Claude Code usage — mirroring the official Settings → Usage panel (current session + weekly limits, in tokens & %), with animations.

What it shows

• Current session — real % used + "resets in Xh Ym" + session tokens
• Weekly · all models — real % used + tokens over the last 7 days
• Status line under the pet: ● working · 1.6M tok/min (or today's tokens when idle)
• By model · 7 days — Opus / Sonnet / Haiku / Fable, in tokens
• 30-day map — colored squares by daily tokens (green = light → red = heavy), with the monthly total

The percentages are real, pulled from your account (you log in once — see below). The token counts, by-model breakdown, activity status, and 30-day map come from your local logs (~/.claude/projects/**/*.jsonl). Everything is token-based — no dollars.

Account & live usage

The session/weekly % comes straight from your Anthropic account, so it matches the official panel exactly. You connect once via a browser login:

1. Open ⚙ Settings → "Log in with browser" — your browser opens an Anthropic auth page.
2. Log in, copy the authentication code shown, and paste it back into the app → Connect.

The token is saved locally (see Data & privacy) and refreshed automatically. Until you connect, the limits area shows a "Connect your account" prompt instead of percentages.

The pet's states

Plus a welcome wave on launch. You can poke the pet from the terminal too.

Install

macOS (Apple Silicon). Two ways, depending on what you want:

1. Install as an app — opens at login (recommended)

One command — it downloads the latest release and drops it in /Applications:

curl -fsSL https://raw.githubusercontent.com/renatoaug/claude-usage-monitor/main/install.sh | bash

Clauddy is free and open source — the command above just downloads the latest release from this repo and drops it in /Applications, nothing else (you can read install.sh first if you'd like).

Why not a normal download? macOS blocks unsigned apps downloaded through a browser with a scary "damaged, move to Trash" warning — even when they're perfectly safe. It's a false alarm: the only way to silence it is to pay Apple $99/year to sign + notarize, which a free hobby app skips. Files fetched with curl aren't flagged, so this method simply lets your Mac open the app without the block. It then registers in Login Items and starts with your Mac — set it and forget it.

2. Run it via bunx (no install)

Needs Bun (or use npx with Node 24):

bunx clauddy

The first run downloads Electron, so give it a moment. Handy for a quick run, but it stays up only while that command is open and won't start on its own. Quit it with the × button.

The app keeps its data in ~/.claude-usage-monitor, regardless of how you run it.

Controls

• Drag the widget anywhere on screen
• – minimizes to just the pet's face (showing the live session %); the ⤢ button or a double-click on the pet expands it back
• ⚙ opens settings (log in, toggle alerts, set thresholds)
• ↗ opens the official Usage page
• × quits

Alerts

Optional macOS notifications when your session or weekly usage crosses the thresholds you set (default 80% and 95%) — e.g. "Your session is over 80% — now at 82%". They re-arm automatically once usage drops back below a threshold (after a reset). Toggle them and edit the thresholds in ⚙ Settings.

Configure (config.json)

Settings saved from the UI live in ~/.claude-usage-monitor/config.json, so you can tweak them without rebuilding:

{
  "alerts": true, // macOS notifications on/off
  "alertThresholds": [80, 95], // notify when session/week cross these %
  "pollIntervalMs": 4000, // how often local logs are re-read
  "activeThresholdMs": 8000, // "working" if Claude was active within this window
  "sleepThresholdMs": 300000, // "sleeping" after this much idle time (5 min)
}

Play with the pet

With the widget running, poke it from the terminal — just for fun:

bunx clauddy poke        # 💕 squish + hearts
bunx clauddy celebrate   # 🎉 jump + confetti
bunx clauddy fire        # 🔥 on fire
bunx clauddy sleeping    # 😴 blue zzz
bunx clauddy working     # 🍴 eats token coins
bunx clauddy tired       # 🥵 maxed out
bunx clauddy idle        # 🙂 calm
bunx clauddy auto        # ↩️ back to your real usage

Each state is written to the data dir the running widget watches, so it reacts live. (Installed globally? Drop the bunx: clauddy poke. Working on the repo? ./pet <state> does the same.)

How it works

• main.js — Electron main process: frameless, transparent, always-on-top window; polls usage; fires macOS notifications; watches config.json and debug.json.
• usage.js — reads ~/.claude/projects/**/*.jsonl, sums tokens per model/day, detects the rolling 5-hour session window, and the working/sleeping activity status.
• auth.js — OAuth login (PKCE, same public client as Claude Code) that fetches the authoritative usage %. Token stored locally, never committed.
• renderer/ — the pet itself: an SVG pixel sprite, CSS animations, and the Web Animations API for particles.
• make-icon.js — generates the app icon from the pixel sprite (build/icon.icns).

Data & privacy

Everything lives on your machine, in ~/.claude-usage-monitor/:

• auth.json — your OAuth token (file mode 600, never committed)
• config.json — your alert settings
• debug.json — scratch file for the ./pet simulator

Nothing leaves your machine except the OAuth calls to Anthropic's own login and usage endpoints.

Dev tooling

• Bun for install/scripts, Node 24 pinned in .nvmrc
• Biome for format + lint (bun run check); a versioned pre-commit hook (.githooks/pre-commit) auto-formats staged files and blocks on errors. It's wired up automatically on bun install (via the prepare script).

Releasing

Releases are fully automated. Every push to main runs semantic-release (.github/workflows/release.yml): it reads the Conventional Commits and, when there's something to ship, computes the version, builds the macOS app, publishes clauddy to npm, and cuts a GitHub Release with the .app zip. Nothing to do by hand — just merge your PRs.

• feat: → minor, fix: → patch, feat!:/BREAKING CHANGE → major.
• docs:/chore:/ci: etc. don't trigger a release.