Back to plugins
AI Usage
v2.16.1 felipeartur

About

AI Usage

Track AI plan usage, quota resets, and consumption pace in the Noctalia bar.

The numbers come from ai-usagebar, a Rust CLI that reads Claude, Codex, GitHub Copilot, Cursor, Antigravity, Kiro, Z.AI, Nous Research, OpenCode Go, Command Code, OpenRouter, DeepSeek, Kimi and Grok, among others. The selector also includes DeepInfra, Grok Bot, Ollama Cloud, OrcaRouter, Model Studio, Lyceum, Devin, Cline, Muse Code, Synthetic, Droid, DeepRelay and Mistral. The plugin runs ai-usagebar usage --json and displays the report. Diagnostics reads the provider catalog with ai-usagebar vendors --json on demand. It does not call provider APIs or read credential files.

Plugin

Field Value
ID felipeartur/ai-usagebar
Entries Bar widget: bar; panel: panel; service: poller

Requirements

Install ai-usagebar on PATH. The plugin runs it by name and has no separate path setting. It ships as ai-usagebar-bin on the AUR, and as release tarballs on the project's GitHub Releases page. Configure your providers once in ~/.config/ai-usagebar/config.toml; the CLI manages credentials and provider connections.

The plugin accepts the optional fields through ai-usagebar 1.52.0, including Antigravity model pools and Synthetic refill metadata. Older CLI reports remain supported; a provider appears only when the installed CLI can report it. Mistral budgets and Kimi monthly-only plans use only the windows supplied by the CLI; calendar budgets without a fixed duration do not get an elapsed-time gauge. Since 1.40.1, the CLI may run agy -p "/quota" --output-format json when agy is installed to read Antigravity quotas. The plugin does not start or configure agy itself.

The CLI sends quota notifications according to its own settings. The plugin adds no alerts or extra thresholds. To disable them, add this to ~/.config/ai-usagebar/config.toml:

[notifications]
enabled = false

When the CLI is missing, the panel displays its project address and can open it with xdg-open. The same command opens provider dashboards from the panel. Install xdg-open alongside ai-usagebar.

The plugin requires plugin API 43 for the current Noctalia palette roles, container tooltips and shared modules. It will not install on an older shell. Plugin version 1.1.0 remains available for API 9.

The main readings and provider icons follow the shell's typography and bar scale. Text also follows the configured font family, weight and font scale. Countdown and pace remain smaller secondary readings. Provider and model marks use a consistent 16px glyph in an 18px slot. On the bar, the reset clock and countdown appear only when a window is near 100% (>= 90%) or at its limit, keeping normal usage compact.

Usage

Add felipeartur/ai-usagebar:bar to a bar in Settings, Bar. The capsule shows one provider's headline reading beside its icon. Readings use the bar's text color, the theme's secondary color for high usage, and error for critical usage. Icons keep their normal color unless a read fails.

A provider that reports a balance instead of a quota (DeepSeek, Kilo, Novita, Moonshot, and Nous top-up credits) has no percentage to draw: the capsule prints that balance where a quota vendor prints its percentage. When the CLI selects a monetary value as the headline, the capsule keeps that amount even if a supporting percentage is available. Used/remaining changes quota readings, not money.

Automatic selects by headline severity, then usage. Raise provider_limit to show more providers; limits above one also show +N for providers that do not fit. Pin a provider or add another widget instance to keep particular plans visible.

Named accounts use the label from the CLI config. Pick the provider and put the label in account: vendor = "openai" with account = "work" follows the openai@work report entry. Leave it empty for the provider's default account.

Settings use the same names as the core sysmon widget. Set visualization to gauge for short-window usage above a thinner long-window usage bar, or none to hide the bars. A provider with one available window shows one bar. show_value, show_glyph and glyph_position control the percentage and icon placement, including Antigravity's individual model readings. A divider separates providers and models. Enable show_name to distinguish shared model groups. Names remain bounded so they do not take over the bar.

extras adds the reset countdown (3h 51m, shown on the bar when usage reaches 90% or is critical, and always shown in the tooltip), consumption pace (↑3 means three percentage points ahead of elapsed time; ↓3 means three behind), both, or neither. Countdowns show days and hours from 24 hours onward, and hours and minutes below that.

When editing config.toml by hand, create a named instance. A raw widget id in the bar list creates an anonymous instance with no settings of its own:

[widget.ai_usage]
type = "felipeartur/ai-usagebar:bar"
visualization = "gauge"
provider_limit = 2
quota_window = "weekly"
auto_providers = [ "openai", "antigravity" ]

[bar.default]
start = [ "clock", "ai_usage" ]
  • Hover shows a compact summary of at most ten rows, with each quota window and its reset countdown on its own line. Open the panel for all windows, models and diagnostics.
  • When a window is exhausted, the capsule shows its reset countdown without a redundant percentage. If the countdown is unavailable or disabled, the percentage remains visible. If several windows are exhausted, it uses the latest reset. A critical warning below 100% does not count as exhaustion.
  • Click a provider or model to select its account. Open panel in chooses whether the click opens All accounts or the selected provider's details. In provider detail mode, clicking a model also highlights its card. All accounts is available when more than one account is configured.
  • Right click requests a refresh. One poller serves every capsule and keeps at most one pending refresh when requests arrive during a read.
  • Middle click opens the widget's settings, as everywhere else in the shell.

Scroll over an automatic capsule to cycle through providers in its filter. A pinned provider does not cycle.

The script handles left click; the shell opens settings on middle click. Right click is a gesture binding in the widget settings, where you can assign another action or choose none.

With multiple accounts, a direct panel open starts with All accounts: a scrolling overview with up to four named account cards per page. Previous/next controls and the visible range keep every account reachable. Each card previews up to three reported quota windows (or all reported windows and model pools for Antigravity), or its balance, and shows reading age and stale status. Extra windows are identified rather than silently dropped.

Click a card to see its windows, models, credits and optional priorities. All accounts returns to the overview without changing the CLI's active account. With one account, the panel opens directly in its details.

The detail tabs identify the selected account. Up to five account tabs remain visible; previous/next controls handle longer lists. Compact tabs reveal full names on hover. Session and weekly limits share a card; Antigravity has a separate card for each model. Each window shows its quota bar, a short reset countdown and consumption pace. For Antigravity, pace is estimated from usage, window duration and reset time; it is hidden if those values are unavailable or the reset has passed. Hover the countdown for the local reset time. A thinner bar compares quota with reported window time: elapsed in used mode, time left in remaining mode. Hover the window label for its time percentage. The thin bar stays hidden when the CLI supplies no window time. The shared Claude & GPT OSS quota keeps the name supplied by the CLI.

The footer shows the update time and up to two quota warnings above 50% usage, with the most restrictive window per model. A +N indicates additional warnings. Hover a pill for its full status. Exhausted quotas also show their reset countdown. Read failures show the last known state. The panel displays quota readings, not agent process health.

The header stays fixed while reports scroll. The reading viewport adapts to the amount of data within a 640px panel maximum; scrolling keeps long reports accessible. Cards reserve space for the scrollbar so their width stays the same between providers.

Opening the panel requests fresh data. The header keeps refresh and close within reach, alongside diagnostics and settings. The account footer offers Copy summary and the provider dashboard. Both Antigravity model groups share the same service link. Click outside, click the widget again or press Escape to close the panel. Press R to refresh usage, or both usage and the catalog while Diagnostics is open. Arrow keys select accounts outside Diagnostics. In the overview they reveal the selected card; Enter opens its detail. Press O to return to All accounts.

The list contains providers with usable readings and parser failures. A default provider reporting no API key is hidden because the CLI does not distinguish a missing credential from a provider that was never configured. A configured provider with its own refresh failure also leaves the bar and panel, then returns automatically after a healthy read. If the CLI instead supplies a dated, ready cache, its last quota or balance stays visible as stale, including after a rejected API-key request. Diagnostics retains the reported failure and recovery guidance.

An empty report shows a message and a direct Diagnostics action. A failed refresh without a visible reading shows the error and retry action instead of a stale-data notice.

Model-specific Gemini pools, such as Gemini 4 Argon, appear inside the Gemini card with their own name, reset and usage. They do not add a separate bar reading. A full Gemini 4 Argon pool does not mark Antigravity as exhausted while its shared windows remain available. The panel sorts providers by headline severity, then usage; equal readings keep the CLI's order. Automatic bar selection uses the same priorities, then the configured primary provider and account id.

Antigravity is the exception when its local server briefly disappears: the last reading stays visible with a stale indicator and its original update time until the server returns. Without an earlier reading, it stays unavailable.

Parser errors are an exception: the provider remains visible with missing usage and the CLI error, because a response-format failure does not establish that the account is unavailable.

Details include the account name, reading age, stale status, window labels, percentages, elapsed time, reset countdowns and local reset times, pace, and high or critical severity labels. Raw values appear when they add information to the percentage. Credit blocks and free text are also shown; zero credit balances are hidden. Codex reset credits show the reset type and expiry on separate lines, with wrapping for longer descriptions.

Cursor On-Demand spending has its own meter when the CLI reports a positive cap and percentage. Its currency amount stays visible; used/remaining does not invert spending. An uncapped amount stays text. Synthetic shows the subscription quota and request count supplied by the CLI, without assuming a reset window. A metric with reading = "left" always shows its remaining quota, even in used mode. Printed figures honor percent_precise (up to two decimal places); meters and severity retain the integer percent. When regen is present, the panel and bar tooltip describe the next partial refill, such as "Regenerates 2% in 2h", instead of a full reset. Countdown values tick locally from reset_at. Droid and DeepRelay use the same report contract; selecting them does not enable or authenticate them in the CLI.

A whole-report failure is different: it cannot identify one broken provider, so it keeps the last list and marks those readings as old instead of blanking the panel during a network interruption.

To open the panel from a terminal:

noctalia msg panel-toggle felipeartur/ai-usagebar:panel

Priorities

Model quota card with account priorities, using example data

Turn on Show priorities in the plugin settings to show the estimates inside each existing model card, alongside its quota windows. The service then runs ai-usagebar usage --json --priorities. This requires ai-usagebar 1.46 or newer and is off by default.

The details follow the selected account: reported status, projected unused quota, remaining quota and reset countdown when available. The CLI's suggestion is marked separately. For providers that group several models in one account, the section is labelled Account priorities because the CLI supplies an account estimate. It does not calculate a separate projection for each model.

The ordinary provider tabs, refresh action and keyboard navigation remain in place. Old or expired suggestions are labelled and need a fresh report before an account can be suggested again. The bar keeps its selection by severity and usage.

While enabled, the CLI records a small local history of quota percentages and timestamps. Turning the option off hides the embedded details and stops requesting this mode. Existing CLI history stays in place. The plugin keeps no separate history. If the CLI rejects the flag, polling falls back to the ordinary command and the embedded section explains the missing support.

Settings

Plugin-level, shared by the poller, every capsule and the panel:

Setting Type Default Description
show_priorities bool false Show priority estimates inside the model cards. Records quota history locally while enabled.
refresh_minutes int 5 Minutes between quota calls, from 1 to 120. Countdowns tick locally in between.
usage_display select used Show used or remaining quota in every capsule and the panel. Numbers and gauges change together; colors and priority still follow consumption. Balances are unchanged.

Per widget instance, so two capsules can follow two providers. Turn on the native settings editor's Advanced switch to edit account, auto_providers, glyph_position and color_by_usage; existing values remain active either way.

Setting Type Default Description
vendor select auto Which plan this capsule tracks. auto follows the busiest provider, with the CLI's own [ui] primary breaking ties.
account string empty Optional named account label from the CLI config. Ignored on auto.
quota_window select auto Keep the default windows, or choose session, weekly or monthly. An exhausted window takes priority. A window the provider does not report shows no percentage.
auto_providers string_list [] Limit automatic selection, scroll and +N to these provider or account IDs. A provider ID includes all its accounts; provider@account selects that account. Empty includes all. Ignored for a pinned provider.
visualization select gauge gauge or none, as described above.
show_exhausted_value bool false Keep the exhausted percentage visible alongside the reset countdown when show_value is enabled.
show_value bool true Show the reported percentage or amount as text.
show_glyph bool true Show the provider's icon.
glyph_position select before before or after the reading.
panel_view select overview Open All accounts or the selected provider's details. An empty capsule opens All accounts.
provider_limit int 1 How many providers one capsule carries, busiest first, from 1 to 4. Only applies on auto.
extras select countdown Information beside the percentage: countdown, pace, both or none.
show_name bool false Show the provider name, or each model name for Antigravity. Long names are shortened; tooltips keep the full label.
color_by_usage bool true Color readings by quota severity. Turning it off does not hide error indicators.

Diagnostics

Open Diagnostics from the panel header when a configured provider is missing or shows an old reading. Each problem shows a status and a suggested next step. Named account failures retain the account label. Open Details to see a technical cause. Provider lists are omitted from this view.

Opening Diagnostics reads the local provider catalog. Refresh requests both the catalog and usage through the shared poller. The view never signs in, changes configuration or executes commands from the response. If the CLI does not support vendors --json (available since 1.13.0), the catalog remains unavailable; known failures from the usage report can still appear.

The existing IPC context opens Diagnostics directly:

noctalia msg panel-open felipeartur/ai-usagebar:panel setup

Antigravity disappears with HTTP 401/403

First check the official CLI with agy -p /quota. A rejected local Antigravity RPC does not establish that the Google login or quota is unavailable. For example, AGY 1.5.7 can answer its quota command successfully while its local RPC answers plain-text 401 Unauthorized; ai-usagebar 1.51.0 recognizes a narrower JSON missing-CSRF response before using its fallback.

If the quota command works, investigate the collector's local-server integration. If it also fails, check the Antigravity login. The plugin does not rewrite credentials or turn a rejected report into a zero or a fresh cached quota. An unavailable provider remains documented in Diagnostics.

IPC

Open the multi-account overview explicitly. With only one available account, the panel opens its details instead:

noctalia msg panel-open felipeartur/ai-usagebar:panel overview

Force a refresh without waiting for the interval:

noctalia msg plugin felipeartur/ai-usagebar:poller all refresh

Point the panel at a provider, by the id ai-usagebar uses for it:

noctalia msg plugin felipeartur/ai-usagebar:poller all select anthropic

Request a provider catalog read without polling quotas:

noctalia msg plugin felipeartur/ai-usagebar:poller all catalog

Notes

Tooltips use the shell's native appearance, timing and position. They do not capture pointer clicks or keyboard focus. Panel tips stay on small controls and labels; long technical details require an explicit click inside Diagnostics.

  • One process, ai-usagebar usage --json, spawned by a single headless service on the configured interval, plus on demand from a right click, from opening the panel, or from the IPC event above. Capsules and the panel are subscribers of plugin state, so a second monitor or a second capsule costs no extra process. Enabling priorities adds --priorities to that same process.
  • Diagnostics adds a separate ai-usagebar vendors --json process on demand, with a five-second timeout and one query in flight. It contacts no provider endpoint. The CLI may enforce restrictive permissions on its own configuration file when loading it, as it does for quota reads.
  • Custom providers can use a known brand icon supplied by the CLI. Unknown brands use the provider fallback. Brand metadata never chooses a dashboard URL.
  • The plugin makes no network calls and writes no files of its own. Everything it knows arrives on those commands' stdout. Catalog state retains only provider names, IDs and configuration flags, without login commands or environment fields.
  • A failed whole-report read keeps the previous report and marks it as stale. Without a previous report, the panel shows the failure and its scrubbed diagnostic. Raw HTTP details stay out of the reading cards.
  • CLI documents are limited to 1 MiB, 32 structural levels and 20,000 value nodes before scrubbing or publication. Usage reports support up to 128 accounts. The byte limit applies before JSON decoding; structural limits apply after decoding. Rejected reports retain the previous reading and allow another refresh. Diagnostics applies the same limits to its catalog and retains the previous catalog on failure.
  • Report text is scrubbed for common credential patterns before publication to plugin state. This is a precaution, not a guarantee that arbitrary CLI output contains no sensitive data. Review account labels and diagnostics before sharing screenshots.

Tests

Run the tests from the ai-usagebar directory:

lua tests/scrub_test.lua
lua tests/refresh_test.lua
lua tests/bar_test.lua
lua tests/panel_test.lua
TZ=America/New_York lua tests/shared_test.lua
lua tests/catalog_test.lua

The suites cover secret redaction and its callback CPU budget, refresh scheduling, account selection, bar and panel rendering, optional priorities, timestamps and on-demand diagnostics, multi-account overview navigation and excessive reports. They use synthetic reports; they do not read credentials or call provider APIs. UI trees are checked in a test host, without rendering the native shell.

Versions

VersionPlugin APIUpdated
v2.16.1 latest43Nov 17, 2026
v2.11.1 32Oct 17, 2026
v2.4.0 22Oct 5, 2026
v1.1.0 9Aug 17, 2026

Older versions stay installable on a Noctalia release whose plugin API is below the latest version's.