UsageBeam 2.0.0 alpha 3

UsageBeam brings private, at-a-glance Codex and Claude Code usage monitoring to the GNOME top panel.

Highlights

• Introduces the permanent UsageBeam product identity and extension UUID.
• Shows the active provider's shortest quota and reset countdown in a compact, fixed-width panel indicator.
• Adds aligned account limits, a seven-day local activity chart, and per-model token totals.
• Supports left area, right area, left-of-calendar, and right-of-calendar placement.
• Adds milestone notifications at configured, warning, and exhausted usage levels without duplicate alerts.
• Improves caching, history recovery, provider discovery, privacy, and constrained-screen behavior.

Install

Download usagebeam@oo7kc.github.io-2.0.0-alpha.3.zip, then run:

gnome-extensions install ./usagebeam@oo7kc.github.io-2.0.0-alpha.3.zip
gnome-extensions enable usagebeam@oo7kc.github.io

Log out and back in after the first installation so GNOME Shell can discover the extension.

Upgrade

To replace an existing UsageBeam installation, install the ZIP with --force, then log out and back in:

gnome-extensions install --force ./usagebeam@oo7kc.github.io-2.0.0-alpha.3.zip

Recognized settings and derived data from older Freeby alpha builds migrate without copying credentials or overwriting existing UsageBeam data.

Verification

• GitHub CI passed for release commit 76db4fff4308e2e2ae0cbbb68d108f93cd3bb0c7.
• All 35 unit tests and the GJS integration suite passed.
• All 15 history, notification, subprocess, and RPC stress cases passed.
• The exact archive passed six isolated GNOME Shell environments, UI assertions, and 60 disable/re-enable cycles.
• SHA-256: 1996bd638936cc58f51390bcf5525106bbd941f61f8efec933a85e0ddc8a2c90.

Known limitations

• This prerelease supports GNOME Shell 50.
• Local activity covers the current device and is not billing data.
• Live limits require the corresponding installed provider CLI and a supported active sign-in.
• Mixed-monitor hotplug, fractional scaling, non-English or RTL desktops, and live upstream failure modes remain outside the verified matrix.

Downgrade

Disable and uninstall UsageBeam before installing an earlier build. Alpha.1 and alpha.2 use the legacy Freeby UUID and separate settings, so they install as a different extension and do not consume UsageBeam's new state automatically.

Freeby 2.0.0 alpha 2 — Claude Code usage

Alpha.2 adds Claude Code usage monitoring to the Codex foundation released in alpha.1.

Included

• Claude Code installation and saved OAuth sign-in detection.
• 5-hour, weekly, and model-scoped account quota windows.
• Seven-day local transcript activity and per-model input, output, cache-read, and cache-write totals.
• Duplicate-message protection and SHA-256 session identifiers in private XDG caches.
• Independent local-history results when authentication expires or Anthropic usage checks fail.
• Expired stale quota windows are removed after their reset.

Install or upgrade

gnome-extensions install --force freeby@kelvin.local-2.0.0-alpha.2.zip
gnome-extensions enable freeby@kelvin.local

Log out and back in if GNOME Shell has not discovered the updated extension.

Verification

• CI passed on the tagged dev commit with 20 unit tests, GJS Codex/Claude history integration tests, strict schema checks, an isolated Meson install, and deterministic packaging.
• The exact ZIP loaded, disabled, and re-enabled in a private GNOME Shell 50 session.
• Claude Code 2.1.218 detection and the missing-auth path were exercised locally.
• Quota shapes, expired auth, response errors, duplicate messages, and cache-token semantics were fixture-tested against the current upstream interface.

Known limitations

• No signed-in Claude account was available on the development machine, so the authenticated usage endpoint path is fixture/upstream-validated rather than live-account-validated.
• GNOME Shell 50 remains the only desktop version verified for this prerelease.
• Activity history is local to this device and separate from subscription quota usage.
• Cursor and Copilot remain opt-in previews until alpha.3 and alpha.4.
• Cost and billing features remain deferred.

Downgrade

Install the alpha.1 or v1.0.2 archive with gnome-extensions install --force, then restart the session. Freeby's derived XDG cache/state data can be removed independently; it never owns provider credentials or transcripts.

Freeby 2.0.0 alpha 1 — Codex usage

The first version 2 milestone replaces Freeby's legacy collector with a bounded,
native GNOME usage-monitoring foundation and completes the Codex path.

Included

• Codex account quota windows and reset times through the installed CLI's app-server.
• Seven days of local token activity with per-model input, output, and cache totals.
• Explicit ready, stale, unavailable, missing-auth, unsupported, unlimited, and exhausted states.
• Private incremental caches with hashed session identifiers and no prompt/response storage.
• Theme-aware GNOME panel UI, independent refreshes, backoff, wake handling, and deduplicated alerts.
• Deterministic packaging plus fixture, integration, schema, install, and GNOME lifecycle checks.

Install or upgrade

Download freeby@kelvin.local-2.0.0-alpha.1.zip, then run:

gnome-extensions install --force freeby@kelvin.local-2.0.0-alpha.1.zip
gnome-extensions enable freeby@kelvin.local

Log out and back in if GNOME Shell has not discovered the updated extension.

Verification

• CI passed on the tagged commit using Node 22, GJS, strict schema compilation, Meson install, and deterministic packaging.
• 13 unit tests and the GJS incremental-history/process integration suite passed.
• The exact release ZIP loaded, disabled, and re-enabled in a private GNOME Shell 50 session.
• A redacted live check with Codex CLI 0.145.0 confirmed account limits, daily activity, and model aggregates.

Known limitations

• GNOME Shell 50 is the only desktop version verified for this prerelease.
• Token history is local to this device and is intentionally separate from account quota usage.
• Cursor and Copilot are opt-in previews pending their dedicated alpha milestones; Claude Code arrives in alpha.2.
• This release monitors usage only. Cost estimates and billing features are deferred.

Downgrade

Install the v1.0.2 archive with gnome-extensions install --force, then restart the session. Freeby's derived XDG cache/state data may be removed independently if desired; credentials and provider transcripts are never owned by Freeby.

v1.0.2

What's Changed

• feat: v1.0.1 — accessibility, theme support, CI, tests by @kcnewman in #1
• fix: post-v1.0.1 fixes and docs polish by @kcnewman in #2
• feat: v1.0.1 remaining fixes and docs by @kcnewman in #3
• fix: add GNOME 50 support by @kcnewman in #4

New Contributors

• @kcnewman made their first contribution in #1

Full Changelog: v1.0.0...v1.0.2