# Claude Code was missing an always-visible usage meter, so I had Claude build one — retained record

> Retained reddit record from reddit:ClaudeAI.

Canonical: https://highsignal.app/data/records/c2bcce18d85e5dc3

[← sources](https://highsignal.app/data)


source: [reddit](https://highsignal.app/data/reddit) (reddit:ClaudeAI)  published 2026-11-05 18:26 ingested 2026-11-06 02:35

[original source ↗](https://www.reddit.com/r/ClaudeAI/comments/1xoq7l1/claude_code_was_missing_an_alwaysvisible_usage/)

## retained text



```
I hate that the only way I could find  to see how much of my usage I've burned was by opening Settings > Usage every time. The hotlink icon on the bottom doesn't give me the exact info I wanted or has to much. So I had Claude Code build me a little floating widget. It's a small, semi-transparent card that sits on top of your windows and shows:

\- \*\*5-hour session\*\*: percent used, tokens used/left, and when it resets

\- \*\*7-day\*\*: percent used and tokens used/left

\- Color-coded bars (green, amber, red), auto-refresh every 5 seconds

\- Drag it anywhere (it remembers the spot), right-click for corner, \*\*opacity\*\* and limit settings

Here is claude's breakdown of the app:

\- It reads only Claude Code's \*local\* session logs (\`\~/.claude/projects\`). No network calls, no credentials, nothing leaves your machine.

\- Anthropic doesn't publish plan limits, so the percentages are \*\*estimates\*\* against limits you set. Calibrate once: check Settings > Usage, then set the widget's limits so they match. It can drift over time, so you may need to re-calibrate occasionally.

\- It only counts Claude Code usage on that machine, not [claude.ai](http://claude.ai) chat or other devices.

Now I could share the actual app but it builds a vbs on my system and I really don't want someone getting it and inserting a virus so I am just sharing the prompt here. Paste the prompt into Claude Code and it will ask where to put the folder, build the app, write a README, generate icons, and ask whether you want a desktop shortcut.

It should work on all operating systems but I have not tested it. Feedback is always welcome and I will post any improvements here as well!

\-- start prompt --

Build me a small always-on-top, semi-transparent desktop widget that shows my Claude Code token usage (percent used and tokens remaining), so I don't have to open Settings > Usage.

\*\*First, ask me:\*\*

1. Where to create the project folder (suggest \`\~/claude-usage-widget\`).
2. At the end, whether I want a desktop shortcut / launcher (don't create one unless I say yes).

\*\*Detect my OS and pick the simplest dependency-free approach.\*\* Strongly prefer Python 3 with the standard-library \`tkinter\` (one codebase for Windows, macOS and Linux). Do NOT use VBScript, and don't install anything with pip or npm. If Python/tkinter isn't available, tell me and propose the best native alternative for my OS (e.g. PowerShell + WPF on Windows) and wait for my OK.

\*\*Data source (important, privacy):\*\* read ONLY Claude Code's local session logs, \`\~/.claude/projects/\*\*/\*.jsonl\` (on Windows \`%USERPROFILE%\\.claude\\projects\`). Do not read credentials files, do not make any network calls, do not hard-code any usernames, emails or absolute paths. Resolve all paths at runtime.

\*\*Parsing rules:\*\*

\- Only look at files modified in the last 7 days. Cache parsed results per file (keyed on mtime + size) so refreshes are cheap.

\- Take lines that contain \`"output\_tokens"\`. Extract with regex: \`"timestamp":"..."\`, message \`"id":"msg\_..."\`, and the first \`"input\_tokens"\`, \`"cache\_creation\_input\_tokens"\` and \`"output\_tokens"\` values. Tokens for a message = input + cache\_creation + output (exclude cache reads).

\- Streamed messages repeat the same message id; dedupe by id keeping the largest total.

\- \*\*5-hour session:\*\* sort messages by time; a block starts at the first message's timestamp floored to the hour and lasts 5 hours; a message at/after the block end starts a new block. The current block's sum is the session usage; if no block is active now, session usage is 0 and the widget says "no active session". Show the reset time (block start + 5h, local time).

\- \*\*7-day:\*\* sum of all messages in the last 7 days.

\- Open files read-only with shared access (Claude may be writing to them) and skip any file that can't be read.

\*\*UI:\*\*

\- Borderless, always on top, semi-transparent (about 82% opacity), dark rounded card, no taskbar/dock entry.

\- Title "Claude usage" with the reset time on the right. Two rows: "5-hour session" and "7-day". Each shows percent, a progress bar (green under 70%, amber 70-89%, red 90%+), and "X used | Y left of Z".

\- Auto-refresh every 5 seconds without freezing the window.

\- Drag anywhere to move; save the position when dropped and restore it on launch.

\- Right-click menu: Refresh now, Set 5-hour limit, Set 7-day limit, Corner (TopLeft/TopRight/BottomLeft/BottomRight; choosing one clears the saved drag position), Opacity (submenu with 40%, 55%, 70%, 82% (default), 92%, 100%; applies instantly and is saved to config), Exit.

\- Single instance only (a second launch should do nothing).

\- Settings live in a \`config.json\` next to the script. Defaults: 5-hour limit 5,000,000, 7-day limit 50,000,000, bottom-right corner, opacity 0.82.

\- Include a \`--test\` flag that prints the computed numbers and exits without opening a window.

\*\*Important honesty point:\*\* plan limits aren't published and this only counts Claude Code usage on this machine, so percent/remaining are estimates against user-set limits. The README must explain how to calibrate: open Settings > Usage, note the real percentages, then set limit = tokens used (shown in the widget) / (real percent / 100) for each bar. Mention it can drift and may need re-calibrating.

\*\*Files to create in the folder:\*\*

\- The app script.

\- \`README.md\`: what it is, requirements, how to run it, how to close it (right-click > Exit), how to calibrate the limits, the privacy statement (reads only local logs, no network, no credentials), and how to share it.

\- Icons: generate a simple app icon yourself (an orange ring gauge on a dark rounded tile, plus a red variant for a "close" launcher), in the right format for my OS (.ico on Windows, .png/.icns on macOS, .png on Linux), using only built-in tools or the standard library.

\- A \`.gitignore\` listing \`config.json\`.

\*\*Launcher (only if I said yes):\*\* create a desktop shortcut that starts the widget with no console window and uses the icon, using the OS-native mechanism (a .lnk made via PowerShell on Windows, a \`.command\`/app wrapper on macOS, a \`.desktop\` file on Linux). Also offer a second shortcut that closes the widget. Never add anything to startup/login items unless I ask separately.

\*\*When done:\*\* run the \`--test\` flag and show me the output, launch the widget, and summarize what was created and where. Then explain, briefly, how to calibrate the limits.

\`\`\
```



document fetched 2026-11-06 00:21 · canonical https://reddit.com/r/ClaudeAI/comments/1xoq7l1/claude_code_was_missing_an_alwaysvisible_usage
