See it in action

🎬 Prefer higher quality? Watch the MP4 demo.

The pill lives in your DankBar and shows live usage at a glance. Providers with multiple quota windows (Claude's 5 hour and 7 day, for example) can show any window in the bar — pick it per provider, or let highest follow the most-constrained one. Hover the pill to see which window the number came from and when it resets:

Why AiOverviewControl?

You pay for Claude, Codex, Copilot, OpenRouter — and each one hides its quota in a different dashboard, CLI, or API. AiOverviewControl collects every provider independently and locally, normalizes the result, and renders one honest overview without any external aggregation service.

Honest is the key word: it reports measured data when a supported source exists, and clearly labels authentication-only or informational providers when it does not. No dashboard scraping. No fabricated percentages. Ever.

Highlights

Screenshots

Dashboard overview	Expanded provider card

Coverage Model

Provider cards use one of these honest coverage levels:

Notable integrations:

The full matrix, credentials, and upstream references are documented in Providers and Provider verification.

Requirements

• DankMaterialShell running on Quickshell.
• bash, jq, and curl.
• Provider-specific CLIs or credentials only for providers you enable. Antigravity needs secret-tool for keyring sessions or sqlite3 for IDE state databases; Hermes and 9Router need sqlite3 for their local usage databases.
• Quota notifications additionally need notify-send and flock.

Recommended baseline for the default provider set:

command -v bash jq curl codex claude gh
codex login
claude auth status
gh auth status

Installation

Release Archive

Download the .tar.gz or .zip from the latest release, extract it as AiOverviewControl, and place it in the DMS plugin directory:

~/.config/DankMaterialShell/plugins/AiOverviewControl

Then restore executable bits and restart DMS:

chmod +x ~/.config/DankMaterialShell/plugins/AiOverviewControl/providers/get-*
dms restart

Git Checkout

git clone https://github.com/bernardopg/AiOverviewControl.git \
  ~/.config/DankMaterialShell/plugins/AiOverviewControl
chmod +x ~/.config/DankMaterialShell/plugins/AiOverviewControl/providers/get-*
dms restart

Enable AiOverviewControl in DMS settings and add it to a DankBar section. Detailed installation and upgrade guidance is available in docs/installation.md.

Configuration

Settings are stored by DMS and survive plugin upgrades.

Settings also offers Export usage history (CSV or JSONL) and a two-step Reset plugin settings, which restores every option above without touching the recorded history.

The default provider selection is:

codex,claude,copilot

API-backed providers read credentials from the DMS process environment. An export available only in an interactive shell may not reach a graphical DMS session. See Configuration for the environment variable matrix and health-check behavior.

Dashboard Behavior

• The hero shows a fleet overview when two or more providers resolve: the average load across measurable quota windows, the hottest provider, how many sit at or above 80%, and the soonest reset across the fleet. Balance, analytics, local-runtime, and informational cards are intentionally excluded from the average denominator so their truthful 0% placeholders do not dilute real quota pressure. Peak, at-risk count, and reset still scan all live cards.
• The overview is navigable: click the fleet rollup's peak provider, or the hero usage bars, to expand and scroll straight to that provider's card.
• Cards are sorted with pinned providers first, then by highest measurable usage, with failed providers last.
• Cards support keyboard focus plus Enter/Space (expand), Delete (remove), P (pin), and R (retry) actions.
• Data becomes stale after twice the configured refresh interval.
• Failed cards expose a provider-specific retry action.
• Expanded cards show available windows, credits, source, identity, and update time without inventing unavailable fields.
• Usage snapshots are stored locally in ~/.cache/AiOverviewControl/usage-history.jsonl and trimmed according to the configured retention. The history writer records only real non-zero quota/spend pressure; informational, local-runtime, balance-only, and analytics-only 0% placeholders are skipped so sparklines remain meaningful. Because the store is trimmed, providers/export-usage-history csv|jsonl (also a button in Settings) is the way to keep long-term data.
• Claude analytics run separately so local history or OAuth failures cannot block the main provider collection.

Privacy and Resilience

• Credentials are read from provider CLIs, local provider-owned data, or environment variables; the UI never displays secret values.
• The plugin does not scrape authenticated web dashboards.
• It does not call paid inference endpoints merely to test a key.
• Temporary files are isolated per run and removed when collection finishes.
• Provider errors are returned as structured data instead of terminating the complete refresh.
• Informational cards use explicit text and official links rather than synthetic percentages.

Validation

jq -e . plugin.json >/dev/null
for file in i18n/*.json; do jq -e . "$file" >/dev/null; done
find providers -maxdepth 1 -type f -print0 | xargs -0 bash -n
for test in tests/*.sh; do bash -n "$test"; done
bash -n scripts/package-release
for test in tests/*.sh; do bash "$test"; done
shellcheck -S warning providers/* tests/*.sh scripts/package-release
qmllint \
  AiOverviewControlWidget.qml \
  AiOverviewControlSettings.qml \
  AiOverviewControlI18n.qml \
  ProviderLogo.qml
./providers/get-provider-health "codex,claude,copilot,pi" | jq .
./providers/get-provider-usage \
  "codex,claude,copilot,pi" \
  ./providers/get-copilot-usage | jq .
./providers/get-usage-history | jq .
./providers/export-usage-history csv /tmp

Architecture

AiOverviewControlWidget.qml       Runtime orchestration and dashboard
AiOverviewControlSettings.qml     Settings, provider selection, and health UI
AiOverviewControlI18n.qml         Locale loading and interpolation
ProviderLogo.qml                  Local provider-logo resolution and fallback icons
providers/get-provider-usage      Multi-provider dispatcher and history writer
providers/get-provider-health     Local prerequisite checks
providers/export-usage-history    Usage-history export to CSV or JSONL
providers/get-codex-usage         Codex app-server protocol bridge
providers/get-claude-usage        Claude quota and local analytics bridge
providers/get-copilot-usage       GitHub Copilot quota bridge
providers/get-antigravity-usage   Antigravity Cloud Code Assist quota bridge
providers/get-9router-analytics   9Router local telemetry blob
providers/get-pi-analytics        pi local session telemetry blob
providers/get-hermes-analytics    Hermes local state telemetry blob
providers/get-*-usage             Canonical single-provider entrypoints
scripts/package-release           Release archive build and validation

See Architecture for the runtime flow and normalized provider contract.

Documentation

Contributors

Thanks to everyone who has improved the plugin:

• @emmsixx — fixed the Settings diagnostic commands hardcoding the display-name casing (AiOverviewControl) instead of the DMS plugin-store manifest id (aiOverviewControl), so copied commands resolve correctly on case-sensitive filesystems (#13).

Contributions welcome — see CONTRIBUTING.md.