aium
AI usage monitor: a Python CLI core that polls your AI providers and a GNOME Shell extension that displays the results. Think of it as a system monitor, but for AI providers.
Features
- Panel indicator — robot icon with monthly spend and balance (stacked two-line label).
- Popover — per-provider: balance, monthly spend, rate-limit quota windows, sparklines (spend or quota trend), plan, and a peak/off-peak dot for providers with dynamic pricing (DeepSeek).
- Clickable providers — open the provider's usage/dashboard page.
- Provider abstraction — add a provider with one file + one registry entry.
- Secrets — API keys in the system keyring; OAuth providers reuse the CLI's own credential files (Codex, Claude Code, Antigravity); Cursor reuses the signed-in IDE session.
- History — SQLite time-series of balances, quota and usage.
- systemd timer — polls every 60 minutes, no resident daemon.
Screenshots
Installation
Quick install (CLI + timer + extension)
curl -fsSL https://raw.githubusercontent.com/jonykalavera/aium/main/install.sh | bash
Pin a specific release with AIUM_VERSION:
curl -fsSL https://raw.githubusercontent.com/jonykalavera/aium/main/install.sh | AIUM_VERSION=v0.1.1 bash
The script installs the aium CLI from PyPI (aium-cli), the systemd user
timer (polls every 60 min) and the GNOME Shell extension. Requires curl,
unzip, and one of uv / pipx / pip. Restart GNOME Shell (logout/login)
to load the extension.
CLI only
pipx install aium-cli # or: uv tool install aium-cli
aium init
The CLI reads its config from ~/.config/aium/ (YAML) and keeps history in
~/.local/share/aium/ (SQLite).
Extension only
Grab aium@jonykalavera.zip from the releases page, extract it
to ~/.local/share/gnome-shell/extensions/aium@jonykalavera/, compile the
schema (glib-compile-schemas schemas) and enable it with
gnome-extensions enable aium@jonykalavera.
From source (development)
./local-install.sh # installs the CLI (uv tool), the systemd timer and the extension from this repo
Quick start
aium providers add deepseek
aium keys set deepseek # prompts for the API key (keyring)
aium poll
aium status
Providers
| Kind | Auth | What it reports | Balance means |
|---|---|---|---|
deepseek |
API key | balance, peak/off-peak tariff | prepaid credit (balance) |
kimi |
API key | balance | prepaid credit (balance) |
openrouter |
API key | balance + monthly usage | prepaid credit (credits) |
openai |
OAuth (Codex) | rate-limit quota windows | none |
anthropic |
OAuth (Claude Code) | spend vs monthly limit + quota windows | monthly budget remaining (budget) |
google |
OAuth (Antigravity) | plan/tier + quota (paid tiers) | none |
cursor |
IDE session | included+on-demand spend; remaining included budget; quota windows | remaining included usage (budget) |
opencode-go |
Go subscription (auth.json) | quota windows (5h/weekly/monthly utilization) | none |
zai |
API key | quota windows + plan | none |
manual |
— | fixed subscription cost + renewal | — |
Balance semantics. "Balance" means different things per provider:
- Prepaid credit (
balance/credits) — real money on the account. OpenRouter reports it ascreditsbecause BYOK/free usage is billed elsewhere and does not decrement it. - Budget (
budget) — remaining monthly spending limit (Anthropic extra usage, Cursor included usage), not money you hold. Cursor'sspend_this_monthis included usage consumed plus on-demand overage; that spend is not subtracted from the included-budget row. - None — the provider exposes no balance (quota/plan only).
The aggregated Prepaid balance total sums only prepaid-credit balances; budget and quota-only providers are shown per-row but excluded from the total.
OAuth providers reuse the CLI's own credential files (~/.codex/auth.json,
~/.claude/.credentials.json, ~/.gemini/oauth_creds.json) — no API key
needed. Cursor reads the signed-in IDE session from
~/.config/Cursor/User/globalStorage/state.vscdb (or cursor-agent's
~/.config/cursor/auth.json). OpenCode Go reads
~/.local/share/opencode/auth.json (the opencode-go key). OpenCode's Zen
pay-as-you-go balance is not exposed by any API endpoint (only the Go quota
is), so it is not tracked. Their usage endpoints are private/undocumented
and may break.
Commands
aium providers add|list|show|update|remove
aium providers update deepseek --peak-window 00:30-16:30 # UTC high-tariff window
aium keys set|list|delete
aium poll # fetch every provider, persist history, refresh cache
aium status # show the last cached status
aium history <id> # balance history for a provider
aium stats # braille sparkline dashboard (live, Ctrl+C to stop)
aium stats --once # single frame
aium stats --provider deepseek --poll
aium report --group day|week|month [--periods N] [--provider ID] [--json] # consumption history
peak_window marks the UTC peak (high-tariff) hours as 'HH:MM-HH:MM'
(wrapping across midnight allowed); the provider row shows a peak/off-peak
indicator. DeepSeek defaults to 00:30-16:30.
Architecture
src/aium/ # Python core (config, secrets, history, polling, providers)
extension/ # GNOME Shell outlet (GJS) — reads ~/.cache/aium/status.json
lib/ # pure logic (unit-tested), no gi:// imports
tests/ # GJS unit tests (gjs -m extension/tests/run.js)
systemd/ # aium-poll timer/service (user units)
tests/ # pytest (core)
The extension is a passive outlet: no provider CRUD, no secrets. It renders
~/.cache/aium/status.json, whose schema (models.py::StatusFile) is the
contract between the core and the extension.
Development
uv sync --all-groups --locked # install dev deps
make uv.check # ruff lint + ty typecheck + format check
make uv.test # pytest --cov aium --blockage (network blocked)
make ext-test # GJS unit tests for the extension logic
Tools: ruff (lint/format), ty (type checker), pytest (coverage + network
blockage). Recipes use bare commands; prefix with uv. to run inside the uv
environment. To iterate on the extension on Wayland (no hot reload), use
./scripts/dev-nested.sh (requires mutter-devkit).
License
MIT — see LICENSE.
Metadata
Release files for aium-cli 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aium_cli-0.4.1.tar.gz | 125.7 kB | With provenance | Details for aium_cli-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aium_cli-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for aium_cli-0.4.1-py3-none-any.whl |
Total release size: 172.1 kB
Release files / aium_cli-0.4.1.tar.gz
| Download URL | aium_cli-0.4.1.tar.gz |
|---|---|
| Size | 125.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae33bc04f97c32909df9ea0ee571c8daf86b7091511c8986def5548790b0e4f9
|
|
BLAKE2b-256 checksum How to use checksums |
e9702f3597661779152e246d6a2949fa17f07b99e7631c3d2728811a78ccec83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / aium_cli-0.4.1-py3-none-any.whl
| Download URL | aium_cli-0.4.1-py3-none-any.whl |
|---|---|
| Size | 46.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d2e0cf74d30293e009f38dc2e4c6daa0f57713f76ce5187097fee69531ea86a8
|
|
BLAKE2b-256 checksum How to use checksums |
c0e3683bd41353f79f20a107ff4f146b7a7415f5f028290fdba49ed194796190
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logSecurity for aium-cli 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aium_cli-0.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.