mirror of
https://github.com/tiennm99/claude-code-usage-bubble.git
synced 2026-06-06 22:12:26 +00:00
tiennm99
aa6217d2cf
Every Rust module under src/ that previously contained upstream-derivative
code has been replaced by a from-scratch implementation:
diag/ log + simplelog file appender (was: diagnose.rs)
os/ color, dpi, registry, string, theme (was: theme.rs, native_interop.rs)
net/ WinHTTP-based HTTP client (was: ureq + native-tls)
i18n/ TOML-embedded locale tables (was: localization/*.rs)
usage/ trait UsageProvider + ClaudeProvider + ChatGptProvider + refresh
orchestrator + registry (was: poller.rs, models.rs)
creds/ trait CredentialSource + local/WSL/Codex impls (was: poller.rs)
tray/ stateless tray manager + tiny-skia anti-aliased badge renderer
(was: tray_icon.rs)
update/ release fetch + inline cmd /c handoff installer
(was: updater.rs's helper-exe pattern)
Application files (app.rs, bubble.rs, panel.rs, settings.rs) migrated to
the new modules. main.rs declares only the new modules.
NOTICE deleted; LICENSE is plain Apache-2.0; README updated to credit
inspiration rather than claim derivation. Cargo.toml drops ureq + native-tls
+ winres in favour of log + simplelog + thiserror + toml + tiny-skia +
embed-resource. Build script swapped to embed-resource via res/icon.rc.
External contracts preserved unchanged: Anthropic + ChatGPT endpoints and
headers, ~/.claude/.credentials.json + Codex auth.json paths, WSL bridging
via wsl.exe, CLI-driven token refresh, GitHub Releases JSON shape, Windows
registry path for startup, single-instance mutex name.
Phase docs: plans/260516-0707-cleanroom-rewrite/.
141 lines
4.7 KiB
Markdown
141 lines
4.7 KiB
Markdown
|
||
[](https://opensource.org/licenses/Apache-2.0)
|
||
|
||
# Claude Code Usage Bubble
|
||
|
||
A floating, draggable circular bubble that shows your Claude Code and/or
|
||
Codex usage on Windows — inspired by the floating "memory boost ball" UX
|
||
of 360 Security and IObit Advanced SystemCare.
|
||
|
||
Drop it anywhere on screen, drag it around, snap it to a monitor edge,
|
||
left-click for a panel with both your 5-hour and 7-day windows, right-click
|
||
for the menu.
|
||
|
||
## Acknowledgements
|
||
|
||
Inspired by [CodeZeno/Claude-Code-Usage-Monitor](https://github.com/CodeZeno/Claude-Code-Usage-Monitor),
|
||
which solves the same "how close am I to the Claude Code limit?" problem
|
||
with a horizontal taskbar widget. This project takes the UX in a different
|
||
direction — a floating, draggable circular bubble that the user can place
|
||
anywhere on screen — and is a clean-room implementation: the HTTP client,
|
||
provider polling, credential discovery, localisation, tray rendering, and
|
||
self-updater are all written from scratch against the same public APIs
|
||
(Anthropic, ChatGPT, GitHub Releases).
|
||
|
||
## What you get
|
||
|
||
- A circular floating bubble showing your current 5-hour Claude Code or
|
||
Codex usage as a percentage and a colored progress ring
|
||
- Drag anywhere — the bubble snaps to monitor work-area edges when
|
||
released
|
||
- Resize with `Ctrl + MouseWheel` on the bubble (32–128 pixels)
|
||
- Left-click the bubble for an expanded panel with both **5h** and **7d**
|
||
bars plus reset countdowns
|
||
- Right-click for refresh, displayed models, update frequency, language,
|
||
startup, updates, exit
|
||
- Optional system tray icons (one per enabled model)
|
||
- Auto-hide when a fullscreen app is in the foreground (games, video,
|
||
presentations) — reappears when you leave fullscreen
|
||
|
||
## Who this is for
|
||
|
||
Windows 10/11 users who already have **Claude Code (CLI or App) installed
|
||
and signed in**. Codex support is optional — install and sign in to the
|
||
Codex CLI, then enable Codex from the right-click **Models** menu.
|
||
|
||
If you use Claude Code through WSL, that is supported too. The monitor
|
||
can read your Claude Code credentials from Windows or from your WSL
|
||
environment.
|
||
|
||
## Requirements
|
||
|
||
- Windows 10 or Windows 11
|
||
- Claude Code (CLI or App) installed and authenticated
|
||
- Optional: Codex CLI installed and authenticated, if you want Codex usage
|
||
|
||
## Install
|
||
|
||
Until packaged binaries are published, build from source:
|
||
|
||
```powershell
|
||
git clone https://github.com/<your-fork>/claude-code-usage-bubble
|
||
cd claude-code-usage-bubble
|
||
cargo build --release
|
||
```
|
||
|
||
The binary lands at `target/release/claude-code-usage-bubble.exe`.
|
||
|
||
## Use
|
||
|
||
Run `claude-code-usage-bubble.exe`. The bubble appears near the bottom-right
|
||
corner of your primary monitor on first launch. Drag it where you want it,
|
||
release to snap to the nearest edge if you let go close to one.
|
||
|
||
- **Left-click** the bubble to open the expanded panel (5h + 7d + countdowns)
|
||
- **Right-click** for refresh, models, update frequency, language, "Start
|
||
with Windows", updates, exit
|
||
- **Drag** anywhere — it floats on top of all other windows
|
||
- **Ctrl + MouseWheel** on the bubble to resize it
|
||
- **Tray icon** (if enabled): left-click toggles the bubble visibility,
|
||
right-click opens the same menu
|
||
|
||
### Models
|
||
|
||
Use the right-click **Models** menu to choose what is shown:
|
||
|
||
- **Claude Code** is enabled by default
|
||
- **Codex** can be enabled alongside Claude Code or shown by itself
|
||
|
||
When both models are shown, each gets its own bubble that you can position
|
||
independently.
|
||
|
||
## Diagnostics
|
||
|
||
```powershell
|
||
claude-code-usage-bubble.exe --diagnose
|
||
```
|
||
|
||
This writes a log file to:
|
||
|
||
```text
|
||
%TEMP%\claude-code-usage-bubble.log
|
||
```
|
||
|
||
Settings are saved to:
|
||
|
||
```text
|
||
%APPDATA%\ClaudeCodeUsageBubble\settings.json
|
||
```
|
||
|
||
## Privacy and security
|
||
|
||
What the app reads:
|
||
|
||
- Your local Claude Code OAuth credentials from `~/.claude/.credentials.json`
|
||
- If needed, the same credentials file inside an installed WSL distro
|
||
- If Codex is enabled, your local Codex credentials from `$CODEX_HOME/auth.json`
|
||
or `~/.codex/auth.json`
|
||
|
||
What the app sends over the network:
|
||
|
||
- Requests to Anthropic's Claude endpoints to read your usage
|
||
- Requests to ChatGPT's Codex usage endpoint, if Codex is enabled
|
||
- Requests to GitHub only if you use the app's update-check feature
|
||
|
||
What the app stores locally:
|
||
|
||
- Bubble position(s) per model
|
||
- Bubble size
|
||
- Polling frequency
|
||
- Language preference
|
||
- Last update check time
|
||
- Displayed model preferences
|
||
|
||
What it does **not** do: send credentials to any third-party server, run a
|
||
backend service, collect analytics, upload your project files, or write to
|
||
your Codex `auth.json` directly.
|
||
|
||
## License
|
||
|
||
Apache License 2.0 — see [LICENSE](LICENSE).
|