AI Usage

A Noctalia plugin that tracks API balance and rate-limit usage across multiple AI coding providers and surfaces it in your bar, with a detail panel for the breakdown.

It watches your usage windows (session / 5-hour / weekly / monthly) and reset timers so you can see at a glance how close you are to a limit — without leaving your desktop.

Supported providers

Provider	What it shows	Auth method	Setup
Claude Code	Session + weekly usage %, reset countdown	Local OAuth session	None — just run claude login
Codex	Primary + secondary usage windows, credits, plan type	Local OAuth session	None — just run codex login
DeepSeek	Total / topped-up balance (USD)	API key	Paste your DeepSeek API key
OpenCode Go	5h / weekly / monthly usage %	Browser auth cookie	Copy auth cookie from opencode.ai
Ollama Cloud	Session + weekly usage %, per-model request counts	Browser session cookie	Copy __Secure-session cookie from ollama.com
Kimi Code	Weekly + 5-hour limits, remaining, usage %	OAuth token	None — reads ~/.kimi/credentials/kimi-code.json
MiniMax Token Plan	Rolling + weekly limit / used / remaining	Session ID + token	Copy _sid and _token cookies (disabled by default)

Each provider can be toggled on or off independently in settings; disabled providers are skipped during refresh and hidden from the panel.

Requirements

• Noctalia >= 3.6.0
• Qt 6 / QuickShell
• python3 on PATH (used for the Claude, Codex, and Kimi OAuth fetch helpers)
• curl (used for the DeepSeek, OpenCode Go, Ollama Cloud, and MiniMax fetches)

Installation

Copy the plugin into your Noctalia plugins directory:

cp -r ai-usage ~/.config/noctalia/plugins/

Then register it in ~/.config/noctalia/plugins.json and add the widget to your bar via settings.json. See the Noctalia plugin docs for the exact registration format.

After installing, reload the shell for the plugin to be picked up.

Configuration

Open the plugin's settings (right-click the bar widget → Settings, or via Noctalia's settings dialog). For each provider you want to track:

1. Toggle Enable on.
2. Fill in the credential the provider needs (see the table above).
3. Set the shared Refresh Interval (default 30 minutes; 0 falls back to 30 min).
4. Click Save — this triggers an immediate refresh.

Where credentials come from

• Claude Code / Codex / Kimi Code — fully automatic. The plugin reads the local OAuth session each provider already wrote during claude login / codex login / Kimi sign-in, refreshing access tokens when expired. Nothing to paste.
• DeepSeek — an API key from platform.deepseek.com.
• OpenCode Go / Ollama Cloud / MiniMax — these providers have no public usage API, so the plugin scrapes your authenticated session. Open the provider's site in a browser, log in, then copy the listed cookie value from DevTools → Application → Cookies. The exact cookie name is shown as the field hint in settings.

How it works

Four QML entry points (declared in manifest.json):

• Main.qml — headless logic component. Owns all data fetching via Quickshell Process calls (curl for JSON/HTML providers, python3 for OAuth providers), parses each provider's response format, and writes results back into pluginSettings. A Timer calls refreshAll() on the configured interval.
• BarWidget.qml — the compact bar icon. Purely presentational. Left-click opens the panel; right-click opens a context menu (refresh / open panel / settings).
• Panel.qml — the detail popup. One section per enabled provider, with progress bars (UsageBar, ModelUsageBar) and per-model segments with hover tooltips (Ollama Cloud).
• Settings.qml — the config form. Edits are staged locally and only committed on Save, which also forces an immediate refresh.

Three Python helpers handle OAuth token refresh logic too complex for inline QML Process commands:

• fetch-claude.py — reads ~/.claude/.credentials.json, refreshes the access token if expired, calls the Claude usage endpoint.
• fetch-codex.py — reads ~/.codex/auth.json, refreshes the access token if needed, calls the Codex usage endpoint.
• fetch-kimi.py — reads/writes ~/.kimi/credentials/kimi-code.json, auto-refreshes the Kimi access token, then calls the Kimi usage API.

Each script prints a single JSON object to stdout that Main.qml parses like any other provider response.

Privacy & security

All credentials (API keys, cookies, tokens) are stored in plaintext in Noctalia's pluginSettings, consistent with how other Noctalia plugins handle secrets. None of your credentials are sent anywhere except to the provider's own API to fetch usage data. If you'd rather not store a cookie-based provider's session, simply leave it disabled.

Troubleshooting

• A provider section shows "Failed to fetch data" — the per-provider fetchError is surfaced in the panel. Common causes: an expired cookie (re-copy it), a revoked OAuth session (re-login), or a provider that changed their page markup (OpenCode Go / Ollama Cloud scrape HTML and can break if the provider redesigns their site).
• Bar widget shows "Set API Key" — no DeepSeek key is configured. This is the only provider that requires manual key entry; the others read local sessions.
• Values don't update — check the refresh interval in settings, or trigger a manual refresh from the right-click menu. The panel also shows a "Last updated" timestamp per refresh.
• Cookie-based providers are fragile — OpenCode Go and Ollama Cloud have no public usage API, so usage is regex-parsed out of their authenticated HTML. If a provider redesigns their page, the parser in Main.qml (parseOcGoWindow, parseUsageSection, parseModelSegments) may need updating.

License

MIT