Hydrogen Widgets shipped by adom-vscode: Claude usage and Codex usage

Two small live panels for Hydrogen Desktop's Title Bar, showing how much of your AI limits you have used. They are a facet of this repo: the same package that installs the Adom VS Code extension also installs their scripts, and the hydrogen-widget.json at the repo root tells Hydrogen they exist. Open them from the Hydrogen Widgets pulldown (the puzzle-piece icon left of the meter), or let your AI do it: POST /widgets/open {"id":"claude-usage"}.

Claude usage

Your session window (5h), your weekly window, and every weekly limit scoped to a model on your plan (Fable, Opus, ...), each as percent used, in the provider's own severity colour. In the full Title Bar the rows stack; in the compact Title Bar they sit in one row.

Where the numbers come from: the Claude Code sign-in in your workspace (~/.claude/.credentials.json), asked at api.anthropic.com/api/oauth/usage, the same endpoint Claude Code's /usage panel reads. The answer's limits list is what is drawn. That call runs a model for nothing and costs no quota.

Codex usage

Your plan's rate-limit window as percent used, plus the secondary window when your plan has one. From the Codex sign-in in your workspace (~/.codex/auth.json), asked at chatgpt.com/backend-api/wham/usage, what Codex's /status reads. With no Codex sign-in the slot says so.

Each widget opens on its weekly limit as one big number. Click it to change the look (all meters, one limit, a ring, a pair, all as numbers or rings); your choice is remembered.

Claude RC

Shows how many Claude sessions your phone can reach right now through Claude Code Remote Control (RC 2), with an amber dot when this PC has Claude threads your phone cannot see.

Hover it for the full picture, one block per machine:

• The machine's Remote Control host (the <machine>-rc session Hydrogen keeps): green when it is connected, so the machine is on your phone; amber with "last seen" when it dropped off.
• Every connected session on that machine, with Claude's own one-line status.
• Which Claude account each machine is signed into, asked over the Adom Bridge mesh. A machine on a different account is flagged in amber with the account to open in the Claude app to see it.
• Every machine's open Claude conversations (over the mesh) and whether Remote Control is on for each. A conversation reaches your phone only once Remote Control is on for it (/remote-control in that conversation). Threads whose tab has not loaded since Hydrogen started show as unknown.

Sessions the cloud still lists but has not heard from in 6 hours are counted at the bottom, not shown: they are not on your phone either.

It reads the same session list the Claude app and claude.ai/code read, with the Claude Code sign-in in this workspace, and asks each machine's Hydrogen over the Adom Bridge mesh at most every 5 minutes. No model runs.

Hover for when your limits reset

Rest the pointer on either widget and its hover card opens a bigger, live view of the same numbers (Hydrogen 1.0.429 and later; older builds keep the plain card):

At the top: how fresh the numbers are, your plan, and Signed in as with the account the numbers belong to (Claude: the email in ~/.claude.json; Codex: the email on the sign-in), so a second account is never a mystery.

For each limit:

• The ring is the time left until that limit resets. It drains as the window runs out and counts down on your own clock, to the second in the last hour, without asking the provider again.
• The bar is how much you have used. The small tick on it is where an even pace through the window would be: a bar past its tick is burning faster than the window.
• Resets in 30 min · 1:10 PM: the countdown and the reset time, in your time zone.
• One sentence on your pace: "On pace for about 90% by the reset", "Plenty of room", or, in amber, "At this pace you hit the limit around 3:01 PM, 6 days 17 h before it resets". A limit already used up says when you are back. The pace is the use so far divided by the share of the window gone by; in the first half hour of a window it says only that the window just started.

Below the limits: usage credits when your Claude account has them turned on, how fresh the numbers are, and the view the slot is showing. When the provider is not answering, the card says so in plain words over the last numbers, dimmed, with a Check now button. When a window rolls over, the view asks once for the fresh numbers instead of showing the old window's percent.

How it works: the widget page posts {hdWidget: {expand: {width: 380, height}}} with the height of its content, and Hydrogen moves the same frame into the card. The page switches layout on its own height (100 px and up is this view), so nothing reloads and nothing else in the slot changes. /preview?x=1 shows the view on its own, which is how the pictures above were made.

Views: click the widget to change what it shows

The rows are the default, and they are small. Click the slot and it moves to the next view; the widget asks the Title Bar for exactly the width that view needs, so a single number takes about a third of the space the rows did and its digits fill the slot's height. The choice is remembered per widget, across restarts. The hover view names the current one at its foot.

For Claude usage (three meters: 5h, week, Fable) the views, in click order:

Codex usage has the same set for its two windows (eight views). In the compact Title Bar the same views lay out in one line, label beside the number. The percent takes the provider's severity colour (teal, amber from 70, red from 90).

After a restart, and when the provider does not answer

The last good numbers are kept on disk, so after a reboot the widget shows them at once, dimmed, with "waiting for Anthropic, last numbers from 08:41" in its hover view, and replaces them the moment the provider answers. A provider error is said in plain words ("no answer from OpenAI (HTTP 404), retrying"), the numbers stay on screen dimmed, and the next try comes at 5, 15, 45 and 90 s, then minutes, capped at fifteen, back to normal on the first success. An expired token is different: the widget waits for Claude Code or Codex to refresh it and re-reads the sign-in file when it changes.

How often they ask

At most once every three minutes per provider, whatever the page polls. The page pauses while the Hydrogen window is hidden or minimized and reads once on return. An upstream error is retried at 5, 15, 45 and 90 s, then every few minutes (capped at fifteen), and the interval returns to normal on the next success. No model runs; asking for usage spends no quota.

Two widgets from one repo: how that works

A repo ships one hydrogen-widget.json. It is either a single widget object, or, as here, {"widgets": [ {...}, {...} ]} with several. Each entry has its own id, name, mark, launch command and port; they share the package (one install), the page you are reading (one docs), and the helper. The curated list on adom/hydrogen-bootstrap names a widget by wiki_repo plus id, so the two appear as separate rows in the pulldown and open and close independently. This repo does it because both widgets read an AI sign-in that already lives next to the editor extension; a repo with one thing to show ships one entry.

The files in this repo that make them widgets

hydrogen-widget.json                  the facet: two widgets, their ids, names, marks, widths, launch and health
widgets/bin/hydrogen-widget-lib.py    the shared helper: an http.server, the page, the interval cache
widgets/bin/hydrogen-widget-marks.py  the vendor marks, generated from the AI launch bar
widgets/bin/hydrogen-widget-claude-usage
widgets/bin/hydrogen-widget-codex-usage
widgets/README.md                     this page (linked from the pulldown row)
widgets/docs/*.png                    the pictures above, rendered from each widget's own /preview route

The package's install.sh symlinks bin/hydrogen-widget-* into ~/.local/bin, which is where launch.command finds them. That is the whole integration; nothing in Hydrogen knows these two widgets by name.

Pictures of a widget

Every widget built on the helper serves /preview?h=38 (full Title Bar), /preview?h=20 (compact) and /preview?x=1 (the hover view): its own page in a frame of that height, which follows the width the widget asks for, exactly as the slot does. A browser screenshot of the frame at a high device scale is a crisp picture for a page like this one; the pictures above were made that way with headless Chrome at three times scale. Pin the width with ?w= when you want a fixed frame.

Make your own

The hydrogen-widget skill has the manifest fields, the launch contract, the tall and compact layouts, private repos, and a fifty-line clock to copy. The overview with pictures is the Widgets page on the Hydrogen wiki.