🐱 ClaudeCat

A hand-drawn cat that lives on your desktop and shows your Claude Code usage in real time.

The cat sits transparent and frameless in the corner of your screen. The more of your budget you've burned, the more tired it looks — and when Claude Code is busy working, the cat starts typing along with it.

_{Meet November 🐈 — my own cat, and the model for every frame here.}

---

What it does

ClaudeCat reads your own Claude Code usage and turns it into a mood. There's no separate login — it uses whatever account Claude Code is already signed into. Under the cat sits a slim 5-hour fuel gauge with a live reset countdown; hover the cat to peek at your weekly budget as a row of little hearts.

The cat's pose tracks whichever budget is tighter — load = max(5h%, weekly%):

Cat	When	Mood
	Plenty of headroom — load < 90%	Relaxed. Sits and grooms itself on a lazy loop.
	Getting low — load ≥ 90%	Tired. Sitting up, droopy-eyed.
	Right at the edge — load ≥ 97%	Weary. Lying low, worn out.
	Rate-limited — load ≥ 99.5%	Asleep. Curled up, with a soft Reset in 02:40 breathing beside it.
	A task is running (any budget)	Typing. Paws at the keyboard while Claude Code works, then settles back.

The typing pose is an overlay: while a task is in progress ClaudeCat plays the working animation (unless the cat is fully rate-limited — an asleep cat stays asleep). Detection is exact — Claude Code UserPromptSubmit / Stop hooks (installed alongside the statusline hook) flip a flag on when a turn starts and off when it ends, so the cat keeps typing through long generations and multi-minute tool runs. Without those hooks it falls back to a coarser transcript-activity heuristic.

Interacting with the cat

Action	What happens
Hover	Reveals the weekly hearts; they slip away when your pointer leaves.
Drag	Moves the cat anywhere — it stays put where you drop it.
Right-click	Opens the pet menu: animation speed, cat size (zoom), reset position, hide, quit.
Tray icon	Show/hide, install statusline hook, reset position, toggle click-through, start on login, quit.

"Click-through" lets mouse clicks pass through the widget to the desktop behind it. All settings (size, animation speed) persist across restarts, and the app can start on login.

Install

ClaudeCat ships for Windows. It needs the WebView2 runtime, which is preinstalled on Windows 11 and current Windows 10.

Easiest — one line in PowerShell (recommended)

Downloads the portable app to %LOCALAPPDATA%\ClaudeCat and launches it. No admin rights, and no SmartScreen prompt — files fetched by PowerShell aren't tagged "downloaded from the internet", so Windows doesn't gate them:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12   # Windows PowerShell 5.1
$exe = "$env:LOCALAPPDATA\ClaudeCat\claudecat.exe"
New-Item -Force -ItemType Directory (Split-Path $exe) | Out-Null
Invoke-WebRequest https://github.com/QiyuZ/ClaudeCat/releases/latest/download/claudecat.exe -OutFile $exe
Start-Process $exe

Or — the installer

Download claudecat_x.y.z_x64-setup.exe (or the .msi) from Releases and run it.

Seeing "Windows protected your PC"? That's SmartScreen flagging an unsigned app — expected for an open-source project without a (paid) code-signing certificate. It is not a sign the app is unsafe; the entire source is in this repo and you can build it yourself. Click More info → Run anyway. The PowerShell method above sidesteps this notice entirely.

Or — build it yourself

Don't trust a prebuilt binary? Clone and build from source — see Build from source. The standalone claudecat.exe lands in src-tauri/target/release/.

After it starts:

1. The cat appears top-right and wakes up on its own within a minute — as long as you've signed into Claude Code (see Where the numbers come from).
2. (Optional) Click Connect ClaudeCat — or tray → Install statusline hook — to add the statusline source and the exact typing detection. ClaudeCat won't overwrite a custom statusLine you already keep.

Launching it later

• Start on login (recommended): right-click the tray icon → Start on login. The cat then appears automatically every time you sign in — no need to launch it by hand.

• claudecat command: if you installed via PowerShell above, add this to your profile (notepad $PROFILE), then run claudecat from any terminal:

  function claudecat { Start-Process "$env:LOCALAPPDATA\ClaudeCat\claudecat.exe" }

Right-click the cat for per-pet options; use the tray icon for the rest.

Where the numbers come from

ClaudeCat never asks you to log in and never scrapes the web. It reads your usage from up to two local sources, preferring whichever has fresh, real data:

1. The statusline hook (preferred). Claude Code renders a statusline on each turn and hands the script an official rate_limits payload — exact 5-hour and weekly percentages with reset times. ClaudeCat installs a tiny hook (scripts/statusline.js) that caches this to ~/.claude/cc-pet-usage.json. This payload only appears for Pro/Max accounts and only after the first API response in a session, so the hook carries forward the last-known values between responses (up to 3 hours, after which stale data is dropped rather than shown).

2. The OAuth usage endpoint (fallback). Some Claude Code versions don't emit rate_limits to the statusline at all. When the hook isn't delivering fresh data, ClaudeCat falls back to the same endpoint Claude Code's own /usage command uses — see Privacy & security for exactly what this reads and sends.

Either way, the numbers are exactly what Claude Code itself reports, for whatever account it's signed into.

You don't need to run claude to see your usage. As long as you've signed into Claude Code at least once (so its credentials exist), the OAuth fallback fetches your usage on its own the moment the widget launches. Running a Claude Code session only refreshes the statusline path and drives the cat's typing pose.

Privacy & security

ClaudeCat is a local desktop widget. Here is everything it touches — all of it auditable in this repo:

• No separate login, no telemetry, no analytics. ClaudeCat has no backend of its own and phones no home.
• Files it reads:
  • ~/.claude/cc-pet-usage.json — the cache written by its own statusline hook.
  • ~/.claude/.credentials.json — only for the OAuth fallback, to read the access token Claude Code already maintains. ClaudeCat never copies, logs, or transmits this token anywhere except the request below.
  • modification timestamps (not contents) of transcript files under ~/.claude/projects — this is how it knows a task is in progress and plays the typing animation.
• What it writes (opt-in, when you click Connect): a statusline hook and two activity hooks (UserPromptSubmit / Stop) in ~/.claude/settings.json, plus their small scripts in ~/.claude/cc-pet/. It backs up your settings.json first, refuses to replace a custom statusLine, and merges the activity hooks alongside any hooks you already have.
• The one network call it makes: a GET to https://api.anthropic.com/api/oauth/usage (Anthropic's official server) with your token, to read your own usage — the same call Claude Code makes internally. The response is normalized to percentages + reset times and cached to ~/.claude/cc-pet-usage-oauth.json; no token is stored on disk.
• Undocumented-endpoint caveat: /api/oauth/usage is not a documented public API and could change without notice. If it does, ClaudeCat simply falls back to the statusline path.
• Debugging is opt-in: the hook only writes a raw-payload dump (~/.claude/cc-pet-debug.json) when you set CC_PET_DEBUG=1.

If you'd rather not use the OAuth fallback at all, you can run statusline-only — open an issue and it's a small change to gate it off.

Build from source

Requires Node and the Rust MSVC toolchain (Rust + Visual Studio C++ Build Tools) for Tauri v2.

git clone https://github.com/QiyuZ/ClaudeCat.git
cd ClaudeCat
npm install
npm run tauri dev     # dev run with hot reload (first compile takes a few minutes)
npm run tauri build   # -> installer (bundle/) + standalone claudecat.exe in src-tauri/target/release/

The standalone src-tauri/target/release/claudecat.exe is the same portable binary the one-line installer downloads — you can run it directly once it's built.

Manual statusline setup

If you keep your own statusline, chain ClaudeCat as a pass-through — the hook prints a short 🐱 5h .. · wk .. left line — or point settings.json directly at the bundled script:

// ~/.claude/settings.json
{
  "statusLine": { "type": "command", "command": "node \"C:\\Users\\<you>\\.claude\\cc-pet\\statusline.js\"" }
}

How it works

Claude Code ──▶ statusline hook ──▶ cc-pet-usage.json ─┐
                                                       ├─▶ Rust core (merge + poll 3s) ──▶ React UI
OAuth /usage ──────────────────▶ cc-pet-usage-oauth.json ┘        │
transcript mtimes ───────────────────────────────────────────────┘  (task-active → typing)

File	Responsibility
src/pet/stateMachine.ts	Turns usage % into a mood (load = max(5h, weekly)) and the reset-countdown helpers.
src/characters/cat.tsx	The only file that knows what the animal looks like: maps each mood to sprite frames (relaxed grooming loop, endless typing loop). Swap it to add a dog.
src/components/QuotaGauge.tsx	The 5-hour fuel gauge (paw + glossy pill) and reset countdown.
src/components/WeeklyHearts.tsx	The weekly budget as a hover-revealed heart health-bar.
src/components/PetMenu.tsx	The right-click menu (animation, size, actions).
src/pet/useUsage.ts	Subscribes to the Rust core; distinguishes "no data" from a real 0%.
src/App.tsx	Composition, onboarding, drag / hover / menu, and window sizing.
scripts/statusline.js	The Claude Code statusline hook that caches rate_limits.
src-tauri/src/lib.rs	The transparent always-on-top window, tray, autostart, the two data sources (cache merge + OAuth fallback), task-activity detection, and the hook installer.

Sprite pipeline

The art is sliced from four hand-drawn strips in src/pic/ into transparent per-frame PNGs:

pip install Pillow numpy scipy
python scripts/process_sprites.py    # src/pic/*.png -> src/assets/cat/*.png
python scripts/make_state_gifs.py    # src/assets/cat/*.png -> docs/*.gif (README art)

Roadmap

Shipped

• Transparent sprite cat with real 5h / weekly data and robust reset countdowns.
• OAuth /usage fallback for Claude Code versions that don't emit rate_limits.
• Hover-reveal weekly hearts; exact typing pose from UserPromptSubmit / Stop hooks.
• One-click hook install, start-on-login, CI-built releases.

More characters (next) — the character layer is deliberately isolated to a single file (cat.tsx, a Mood → frames table), so adding a dog or other animal is mostly art plus a character picker in the tray menu. The cheapest delight, and it proves the swap-the-character design.

Bring-your-own-pet (the big one) — a simple pet-pack format: a folder/zip of per-mood PNG frames plus a small pet.json mapping moods → frames and timings, dropped into a pets/ directory or imported from the menu. Ship a couple of official packs and let the community make the rest — this turns ClaudeCat from a toy into a little platform. The existing process_sprites.py (background knock-out + framing) becomes the authoring tool.

Richer data & signals — a small data-source badge (official / oauth) so you can see where a number comes from; a weekly usage sparkline or mini heat-map from cached snapshots; optional token & cost stats parsed from local JSONL (ccusage-style); a gentle notification when you cross 90% or when a window resets.

Reach — macOS / Linux builds (Tauri already supports them; needs platform window code and build targets) and code signing so the installer stops tripping SmartScreen.

Credits & license

The character is November 🐈 — my own cat — hand-drawn frame by frame for this project. Hope you like him.

Built with Tauri v2 + React + TypeScript. Data-layer inspiration from ohugonnot/claude-code-statusline and ccusage.

Released under the MIT License © 2026 QiyuZ.