tiennm99
5df75c901e
Implements every recommendation from the UI/UX review of the two-bar
bubble: readability bump, faster glanceability, per-provider identity,
smarter resize curve, and a richer snap behavior set.
Readability + sizing:
- Default width 180 → 200, min 120 → 140 (Windows shell minimum legible
status-text floor is 12 px; previous breakpoint produced 11 px text)
- Discrete breakpoint table replaces the linear bar_h = h/4 formula —
140/200/280/360 widths map to (bar_h, font, row_gap) of
(12,11,4)/(16,13,6)/(20,15,8)/(24,17,10)
- Aspect tapers 3:1 → 2.8:1 → 2.6:1 as width grows so bars stay
proportionally chunky at large sizes
- Right-column width now derived from GetTextExtentPoint32W of
"100% · 23h" against the real font instead of the bar_h * 6 heuristic
Glanceability:
- ring_color_for_percent rewritten as a 4-band cliff: orange < 60,
amber 60-80, red 80-95, deep red ≥ 95 — gradient hid the 75 vs 85
difference at narrow bar widths
- Percent moved inside the bar (right-aligned with auto-contrast picked
from luminance of the underlying fill or track)
- Right column now shows only the countdown ("2h 14m"), not the
combined "X% · 2h 14m" string. i18n::format_countdown is now pub so
the bubble can request countdown-only; the panel still renders the
combined string via format_window
- "5h" / "7d" muted labels added in a new left column
- Rows whose bar is ≥ 95 % get a 15 %-red blush behind the entire row;
fill color also brightens via a slow triangle wave (TIMER_PULSE,
80 ms, only armed when at least one bar is in the alarm band)
Per-provider identity:
- 4-px vertical accent stripe at the left edge — Claude orange
(#D97757), Codex green (#10A37F) — disambiguates the two bubbles
when both are enabled. Mirrored into the expanded panel so the
identity carries across surfaces
Snap behavior:
- Corner snap: release within 32 px of a work-area corner slams the
bubble into the corner with a 12-px inset
- Taskbar-adjacency: SHAppBarMessage(ABM_GETTASKBARPOS) supplies the
taskbar rect/edge; bubble docks against the inner face with a
4-px gap on the docked edge
- Peer-Y alignment: when a second bubble exists within ±8 px on Y
at release time, the dragged bubble snaps to share its top edge
- WM_SETTINGCHANGE handler re-clamps bubbles into the new work area
when taskbar moves / auto-hides / DPI changes
Color packing:
- Direct DIB writes use rgb_to_dib (B,G,R,X memory order) instead of
into_colorref (R,G,B,X COLORREF order). Already corrected in the
previous redesign for the bar fills, but the accent stripe and blush
go through the same path now
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, 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 + MouseWheelon 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:
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
claude-code-usage-bubble.exe --diagnose
This writes a log file to:
%TEMP%\claude-code-usage-bubble.log
Settings are saved to:
%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.jsonor~/.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.