# ๐Ÿพ claude-cat

claude-cat

> **The offline-only Claude Code status line.** A cute cat tells you how much usage is left โ€” without touching a single network endpoint. [ํ•œ๊ตญ์–ด README โ†’](./README.ko.md) [![npm version](https://img.shields.io/npm/v/claude-cat)](https://www.npmjs.com/package/claude-cat) [![npm downloads](https://img.shields.io/npm/dm/claude-cat)](https://www.npmjs.com/package/claude-cat) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org) [![install size](https://packagephobia.com/badge?p=claude-cat)](https://packagephobia.com/result?p=claude-cat) [![zero network](https://img.shields.io/badge/network-0%20calls-brightgreen)](#why-claude-cat) [![zero credentials](https://img.shields.io/badge/credentials-never%20read-brightgreen)](#why-claude-cat) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/thingineeer/claude-cat/graphs/commit-activity)

kawaii cat + usage bars in a terminal
3-row kawaii card โ€” --full --kawaii

## ๐Ÿ›ก๏ธ Why claude-cat claude-cat only renders the JSON that Claude Code **already pipes to statusLine scripts via stdin**. Nothing else. That's the whole design โ€” and the whole safety story: - **๐Ÿšซ Zero network calls.** No `api.anthropic.com`. No `claude.ai`. No `/api/oauth/usage`. Run it behind a firewall; it works the same. `tcpdump` stays empty. - **๐Ÿšซ Zero credential reads.** Never touches `~/.claude/.credentials.json`, the macOS Keychain, or any OAuth token. If your npm account is ever compromised, the worst case is a funny-looking status line โ€” not a leaked Anthropic account. - **๐Ÿšซ Zero outbound writes.** Only writes to `~/.claude/claude-cat/` (a local sync cache + optional debug dumps). Nothing leaves your machine. - **โœ… Stdin-only**, by policy. Documented in [`SECURITY.md`](./SECURITY.md) and enforced by the project's threat model โ€” not a side effect. ### Compared to other Claude Code status-line / usage tools | Feature | **claude-cat** | ccstatusline | claude-dashboard | ccusage | | --- | :---: | :---: | :---: | :---: | | Runs on every statusLine render | โœ… | โœ… | โœ… | โŒ (CLI) | | **No network calls** | **โœ…** | โŒ (Anthropic API) | โŒ (Anthropic API) | ๐ŸŸก (pricing fetch, `--offline` ok) | | **No OAuth / credential reads** | **โœ…** | โŒ | โŒ | โœ… | | Kawaii cat moods ๐Ÿ˜บ | โœ… | โŒ | โŒ | โŒ | | Cross-terminal sync | โœ… | โŒ | โŒ | n/a | | Historical / cost reports | โŒ | ๐ŸŸก | โœ… | โœ… | **Pick claude-cat when** you want a friendly always-on status line and you care that your toolchain isn't quietly talking to Anthropic behind your back. **Pair with [`ccusage`](https://github.com/ryoppippi/ccusage)** if you also want on-demand cost reports โ€” the two are complementary (claude-cat for live render, ccusage for analysis). > "Just a cat" isn't a cute tagline โ€” it's the threat model. ## Install ### Quick setup (recommended) Run the interactive wizard โ€” it walks you through layout, cat theme, refresh interval, and plan in 30 seconds: ```bash npx -y claude-cat@latest configure ```

configure wizard demo

It writes `~/.claude/settings.json` for you (with a diff preview first, leaving every other setting untouched). Restart Claude Code and the line shows up on the next turn. ### Manual setup (paste a prompt) Pick a mode, paste the prompt into Claude Code, and it edits `~/.claude/settings.json` for you. ### A) โญ Default โ€” compact, one line *(recommended)* You get a single line: usage bars + `$` cost + `ctx %`. No cat. Wraps on narrow terminals. ```text 5h โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 47% (1h 19m) | week โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 31% (Fri 1pm) | $37.37 | ctx 20% ``` ```text Install claude-cat (https://github.com/thingineeer/claude-cat) into my ~/.claude/settings.json as the statusLine. - type: "command" - command: "npx -y claude-cat@latest" - padding: 0 - refreshInterval: 300 Don't touch any other key. Show me the diff first. ``` ### B) 3-row kawaii cat You get a 3-row card: ASCII cat on the left, data rows on the right. The cat's face and prop change with your usage. ```text /\_/\ Opus 4.6 ยท $38.52 ยท ctx 23% used (77% left) ( ^ฯ‰^ ) Current session โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 51% ยท 1h 15m / >๐Ÿฃ Current week (all models) โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 31% ยท Resets Apr 17, 1pm ``` ```text Install claude-cat (https://github.com/thingineeer/claude-cat) into my ~/.claude/settings.json as the statusLine. - type: "command" - command: "npx -y claude-cat@latest --full --kawaii" - padding: 0 - refreshInterval: 300 Don't touch any other key. Show me the diff first. ```
All modes at a glance Same install pattern โ€” just swap the `command` value.
flagcommandpreview
โญ (default) npx -y claude-cat@latest 
5h โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10% (3h 21m) | week โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 18% (Fri 1pm) | $0.123
--full --kawaii npx -y claude-cat@latest --full --kawaii 
 /\_/\   Opus 4.6 ยท $0.123
( ^ฯ‰^ )  session  โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10% ยท 3h 21m
 / >๐Ÿฃ   week     โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 18% ยท Resets Apr 17, 1pm
--full npx -y claude-cat@latest --full 
/แ  ^แดฅ^ แŸ\  Opus 4.6 ยท $0.123
session  โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10% ยท 3h 21m
week     โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 18% ยท Resets Apr 17, 1pm
--wide npx -y claude-cat@latest --wide 
5h โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10% (3h 21m) | week โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 18% (Fri 1pm) | $0.123
--full --no-cat npx -y claude-cat@latest --full --no-cat 
Opus 4.6 ยท $0.123
session  โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10% ยท 3h 21m
week     โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 18% ยท Resets Apr 17, 1pm
Power-user flags: `--stack=auto|always|never`, `--max-cols=`, `--no-debug-chip`, `--icons=none|emoji|nerd`. Env vars: `CLAUDE_CAT_COLUMNS`, `CLAUDE_CAT_DEBUG=1`, `CLAUDE_CAT_PLAN=pro|max|auto` (Pro users: set `pro` to hide weekly bars โ€” the wizard sets this automatically).
## Reading the output ```text 5h โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 47% (1h 19m) | week โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 31% (Fri 1pm) | $37.37 | ctx 20% ``` | chip | meaning | | ---- | ------- | | `5h` / `week` / `sonnet` | rate-limit window (5-hour session / weekly / per-model weekly) | | `โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘` | 10-cell progress bar โ€” green โ†’ yellow โ†’ red as it climbs | | `47%` | exact percentage | | `(1h 19m)` / `(Fri 1pm)` | time until that window resets โ€” relative for session, absolute for weekly | | `$37.37` | **this Claude Code session's running cost in USD** โ€” see below | | `ctx 20%` | how full the current conversation's token budget is | ### What `$37.37` is โ€” and isn't It's **this single Claude Code session's running cost**, computed by Claude Code itself (`cost.total_cost_usd` from stdin JSON). - โŒ NOT "Extra usage" plan-overage fees โ€” that's a different `/usage` popup bar and isn't piped to statusLine scripts. - โŒ NOT your monthly subscription bill. - โŒ NOT money leaving your account right now if you're on Pro/Max (those are flat-rate โ€” the number is informational). - โœ… On an **API key** it's the real cost. On **Bedrock / Vertex** it stays `$0.00` (Claude Code can't compute cost there). ## Cat moods The cat only shows up in `--full` modes. Six moods โ€” five driven by usage, one state-driven (resting). | trigger | `--full` (1-line face) | `--full --kawaii` prop | | ------- | ---------------------- | ---------------------- | | no rate limits yet (*resting*) | `/แ  -แดฅ- แŸ\` | ๐Ÿšฌ smoke | | 0โ€“30 % (*chill*) | `/แ  ^แดฅ^ แŸ\` | ๐Ÿฃ sushi | | 30โ€“60 % (*curious*) | `/แ  โ€ขแดฅโ€ข แŸ\` | โŒจ๏ธ keyboard | | 60โ€“85 % (*alert*) | `/แ  โ—‰แดฅโ—‰ แŸ\` | โ˜• coffee | | 85โ€“95 % (*nervous*) | `/แ  โŠ™แดฅโŠ™ แŸ\` | ๐Ÿ’ค break | | 95 %+ (*critical*) | `/แ  โœ–แดฅโœ– แŸ\` | ๐Ÿ›Œ sleeping | Mood policy: `weekly โ‰ฅ 60 %` or `session โ‰ฅ 75 %` โ†’ alert; any window โ‰ฅ 85 โ†’ nervous; any โ‰ฅ 95 โ†’ critical. Weekly drives the mood because it's the bar that actually constrains your week.
Full 3-row ASCII gallery for every mood **resting** ``` /\_/\ ( -.-) / >๐Ÿšฌ~ ``` **chill** (0โ€“30 %) ``` /\_/\ ( ^ฯ‰^ ) / >๐Ÿฃ ``` **curious** (30โ€“60 %) ``` /\_/\ ( โ€ขใ……โ€ข) / >โŒจ๏ธ ``` **alert** (60โ€“85 %) ``` /\_/\ ( -ใ……-) / ใฅโ˜• ``` **nervous** (85โ€“95 %) ``` /\_/\ ( xใ……x) / ใฅ๐Ÿ’ค ``` **critical** (95 %+) ``` /\_/| ( -.-)zzZ / \ ```
## Plan compatibility | Plan | Shows | Notes | | ---- | ----- | ----- | | Claude Pro / Max | rate-limit bars, reset countdown, cat mood, session cost | `rate_limits` appears after first reply | | Anthropic API key | session cost in USD + cat mood | no rate_limits in stdin JSON | | Bedrock / Vertex | cost stays at `$0.00` | upstream limitation | ## What's *not* in stdin JSON (yet) Two things `/usage` popup shows but Claude Code doesn't pipe to statusLine scripts, so claude-cat can't render them today: - **Current week (Sonnet only)** โ€” server includes `rate_limits.seven_day_sonnet` only sometimes (condition undocumented). - **Extra usage** (e.g. `$14 / $20 spent`) โ€” comes from `/api/oauth/usage` (private endpoint). A future opt-in daemon could proxy that endpoint locally and cache values. Tracked in [issues](https://github.com/thingineeer/claude-cat/issues). ## Security claude-cat is deliberately small and network-free so it fits Claude Code's per-message hot path safely. **What it does** โ€” reads the stdin JSON Claude Code already pipes to statusLine scripts, prints a colored line. **What it doesn't do** โ€” no network requests, no credential reads, no keychain access, no writes outside `~/.claude/claude-cat/`. The invariants are listed in [SECURITY.md](./SECURITY.md). ### npm supply-chain considerations `npx -y claude-cat@latest` downloads and runs the latest published version every time. This is standard for npm but worth knowing: - **Pin if you want reproducibility** โ€” `npx -y claude-cat@1.2.5` instead of `@latest`. Upgrade when an advisory is published. - **Review the package** โ€” the published tarball only ships `bin/`, `src/`, `examples/`, and README/LICENSE (`files` in `package.json`). You can audit it before install: `npm pack claude-cat && tar -tf claude-cat-*.tgz`. - **Local install alternative** โ€” clone the repo and point your statusLine at `node /path/to/claude-cat/bin/cli.js`. No npm fetch at all. ### Reporting a vulnerability Private advisory only: **https://github.com/thingineeer/claude-cat/security/advisories/new** Don't open a public issue. See [SECURITY.md](./SECURITY.md). ## Development ```bash git clone https://github.com/thingineeer/claude-cat.git cd claude-cat git config core.hooksPath .githooks npm run test:sample # try a fixture npm run test:full ``` Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md). For Claude-Code sessions: [CLAUDE.md](./CLAUDE.md). ## License MIT ยฉ thingineeer