Claude Code Usage Bubble

A floating, draggable circular bubble that shows your Claude Code and/or Codex usage on Windows and Linux — 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.

Linux ARM64 and macOS are not supported yet; see ROADMAP.md.

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, 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, or use Controls → Make smaller / Make larger / Reset size from the right-click menu (140–360 logical pixels)
• Left-click the bubble for an expanded panel with both 5h and 7d bars plus reset countdowns
• Right-click for refresh, displayed providers, update frequency, startup, updates, exit
• A system tray icon per enabled provider, with a usage badge
• Desktop notifications when usage crosses a threshold, when a sign-in expires and after an update was applied
• 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 and Linux x86_64 users who already have Claude Code (CLI or App) installed and signed in on the same machine. Codex support is optional — install and sign in to the Codex CLI, then enable Codex from the right-click Providers menu.

Requirements

• Windows 10 or Windows 11, or Linux x86_64 (see below)
• Claude Code (CLI or App) installed and authenticated
• Optional: Codex CLI installed and authenticated, if you want Codex usage

Windows

The app draws its windows with the Microsoft Edge WebView2 runtime. Windows 11 ships it, and most up-to-date Windows 10 machines already have it. If it is missing, the app shows a message with the download link and exits; install the Evergreen WebView2 runtime and start the app again.

Linux

• Runtime libraries: WebKitGTK 4.1 (libwebkit2gtk-4.1-0 on Debian/Ubuntu) and, for the tray icons, libayatana-appindicator3-1. The .deb pulls these in. Without an AppIndicator library the app runs without tray icons.
• A compositing window manager. The bubble is a transparent window; without a compositor its corners are drawn opaque.
• X11 is the supported session. Under Wayland the app runs through Xwayland, where positioning, snapping and always-on-top work. Without Xwayland (or with GDK_BACKEND=wayland set) the bubbles still show, but they cannot be positioned, snapped, kept on top or saved where you drop them.
• Tray limits: Linux tray icons (AppIndicator) only open the menu. They show no tooltip, and a left click does not toggle the bubble; use the menu instead.

Install

Windows

Grab claude-code-usage-bubble.exe from the Releases page. Put it anywhere on disk (e.g. %LOCALAPPDATA%\ClaudeCodeUsageBubble\) and run it. The app self-updates from the same Releases feed.

First-run note: the binary is unsigned, so SmartScreen will show "Windows protected your PC". Click More info → Run anyway. Code signing is on the roadmap.

Linux x86_64

From the same Releases page, pick one:

• claude-code-usage-bubble_X.Y.Z_amd64.AppImage: make it executable (chmod +x) and run it. The AppImage self-updates in place.
• claude-code-usage-bubble_X.Y.Z_amd64.deb: install it with sudo apt install ./claude-code-usage-bubble_X.Y.Z_amd64.deb. The app still checks for updates, but installing one is left to you: download the new .deb and install it the same way.

Build from source

Prerequisites: the Rust toolchain and Node.js with npm. The Tauri CLI is a local dev dependency, so npm ci installs it.

On Windows:

git clone https://github.com/tiennm99/claude-code-usage-bubble
cd claude-code-usage-bubble
npm ci
npm run tauri build -- --no-bundle

The binary lands at target\release\claude-code-usage-bubble.exe.

On Linux x86_64, install the build dependencies first (Debian/Ubuntu):

sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
git clone https://github.com/tiennm99/claude-code-usage-bubble
cd claude-code-usage-bubble
npm ci
npm run tauri build -- --no-bundle

The binary lands at target/release/claude-code-usage-bubble. To build the .deb and AppImage instead, also install patchelf (the AppImage needs it) and run npm run tauri build -- --bundles deb,appimage; they land under target/release/bundle/.

Local builds carry no updater signature (createUpdaterArtifacts is off in tauri.conf.json), so they cannot be published as an update. Only the release workflow signs builds; see docs/release-process.md.

Use

Run the app. 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, providers, refresh frequency, "Start with Windows" ("Start at login" on Linux), controls, auto-update check (Disabled / Hourly / Daily / Weekly), manual "Check for updates", exit
• Drag anywhere — it floats on top of all other windows
• Ctrl + MouseWheel on the bubble, or Controls in the right-click menu, to resize it
• Tray icon: left-click toggles the bubble visibility, right-click opens the same menu (on Linux, any click opens the menu)

Providers

Use the right-click Providers menu to choose what is shown:

• Claude Code is enabled by default
• Codex can be enabled alongside Claude Code or shown by itself
• OpenCode Go is listed for future support; usage bars remain disabled until OpenCode exposes a stable quota source or console integration is explicitly enabled

When multiple providers are shown, each gets its own bubble that you can position independently.

Changes from the v0.5.0 Windows build

The app moved from a hand-written Win32 UI to Tauri. Most behaviour is the same; these differences are visible:

• The transparent corners around the round bubble no longer pass clicks through to the window below; they just ignore clicks.
• Alerts are Windows toast notifications instead of tray balloons, so they no longer use a warning or info icon.
• Proxy auto-configuration (PAC scripts and WPAD) is no longer used. A static system proxy, its bypass list and the HTTPS_PROXY-style environment variables still are.
• Only one copy runs per signed-in user session, instead of one per machine.

Diagnostics

claude-code-usage-bubble.exe --diagnose     # Windows
claude-code-usage-bubble --diagnose         # Linux .deb (pass the same flag to the AppImage)

This writes a log file, truncated on each start, to:

OS	Log file
Windows	%TEMP%\claude-code-usage-bubble.log
Linux	$TMPDIR/claude-code-usage-bubble.log, usually /tmp/claude-code-usage-bubble.log

Settings are saved to:

OS	Settings file
Windows	%APPDATA%\ClaudeCodeUsageBubble\settings.json
Linux	$XDG_CONFIG_HOME/ClaudeCodeUsageBubble/settings.json, usually ~/.config/ClaudeCodeUsageBubble/settings.json

Other files the app writes:

What	Windows	Linux
Update downloads and update-error.log	%LOCALAPPDATA%\ClaudeCodeUsageBubble\updates\	~/.local/share/ClaudeCodeUsageBubble/updates/
Web view profile (cache, storage)	%LOCALAPPDATA%\io.github.tiennm99.claudecodeusagebubble\ (WebView2)	~/.local/share/io.github.tiennm99.claudecodeusagebubble/ (WebKitGTK)

On Windows the app also writes its notification icon to %LOCALAPPDATA%\ClaudeCodeUsageBubble\icon.png and registers it under HKCU\Software\Classes\AppUserModelId\io.github.tiennm99.claudecodeusagebubble, which Windows needs to show toasts from a portable exe.

Privacy and security

What the app reads:

• Your local Claude Code OAuth credentials from ~/.claude/.credentials.json
• 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
• Last update check time
• Displayed provider 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.