claude-code-usage-bubble/README.md

![Windows](https://img.shields.io/badge/platform-Windows-blue)
![Linux x86_64](https://img.shields.io/badge/platform-Linux_x86__64-blue)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](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 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](ROADMAP.md).

## 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, 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](https://developer.microsoft.com/microsoft-edge/webview2/)
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](https://github.com/tiennm99/claude-code-usage-bubble/releases/latest).
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](https://github.com/tiennm99/claude-code-usage-bubble/releases/latest),
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](https://www.rust-lang.org/tools/install)
and [Node.js](https://nodejs.org/) with npm. The Tauri CLI is a local dev
dependency, so `npm ci` installs it.

On Windows:

```powershell
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):

```bash
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](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

```text
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](LICENSE).