Plasma AI Usage Widget
Claude, Codex and Gemini usage limits, right in your KDE Plasma 6 desktop.
See your quota, reset times and active accounts without opening three separate tools.
Download · Install · Report a bug · Português brasileiro
Screenshots render the project's QML components with synthetic demo data. No real account details are shown.
Features
- Three providers in one view: Claude Code, OpenAI Codex and Gemini / Antigravity usage.
- Current and weekly quotas: used or remaining percentages, reset countdowns or dates, with missing data shown explicitly.
- Multiple accounts: capture, switch and rename accounts with isolated credential profiles.
- Early warning: consumption pace or fixed-threshold alerts, with optional desktop notifications.
- Your panel, your layout: rings, percentages, bars, a floating notch and optional session indicators for Claude Code and Codex.
- Token history: charts and CSV or JSON export where local usage data is available.
- English and Brazilian Portuguese, with support for more translations.
- Lightweight collector: no runtime Python package dependencies; optional Waybar JSON output.
Install
Requirements: KDE Plasma 6, Python 3.10+ with venv and ensurepip, and a login for the provider you want to monitor. Quota availability depends on the provider, account and authentication method. An API key alone may not expose subscription limits.
1. Install the widget
Download org.kde.plasma.aiusage.plasmoid from the latest release. In Plasma, open Add Widgets → Get New Widgets → Install Widget From Local File, select the package, then add AI Usage Monitor to your panel or desktop. Menu names can vary with the Plasma version and language.
Or install the downloaded file from a terminal:
kpackagetool6 --type Plasma/Applet --install ./org.kde.plasma.aiusage.plasmoid
For an existing installation, replace --install with --upgrade.
2. Install the collector
Open the widget, click Install collector and confirm. It installs the matching version from PyPI into its own virtual environment, without sudo or changes to system Python. The collector is required to display usage.
Prefer managing it yourself? Use pipx to install the same version as the widget. For release v1.2.2:
pipx install plasma-ai-usage-collector==1.2.2
3. Add your accounts
Sign in through your provider's CLI, then use the widget's account settings to capture the current account. Or capture it from a terminal:
ai-usage-collector --capture-current claude
ai-usage-collector --capture-current codex
ai-usage-collector --capture-current gemini
ai-usage-collector --refresh
Run only the capture commands for providers you use. See Gemini / Antigravity credential discovery for its supported local credential sources.
Read the rings
In the expanded view, the inner ring shows the current window and the outer ring shows the weekly limit. Window durations depend on provider data; they are not identical for every provider. The compact panel normally shows the current window.
Arcs show used quota by default; switch to Remaining to see the balance. A white marker indicates elapsed time when the duration is known. Alert colors reflect the configured pace or threshold mode. A dash means there is no reliable reading, rather than zero usage.
Privacy and connections
The widget and collector run on your machine. There is no project backend, telemetry or analytics. Credentials are stored locally; quota checks contact the relevant provider's endpoints.
Optional update checks contact GitHub and the npm registry. Installing the collector contacts PyPI after confirmation. Account capture, switching and renewal use local credentials. Automatic renewal of inactive Gemini accounts is off by default; see the details and limitations.
Provider endpoints can change or rate-limit requests. A missing window, expired session or failed refresh is shown as unavailable or stale data. Quota information is not available for every plan.
Documentation and development
- Technical guide in Portuguese: configuration, notifications, account renewal, history and translations.
- Waybar setup: feed Waybar from the collector's local cache with
ai-usage-collector --waybar. - Changelog and design decisions.
To work on the project:
git clone https://github.com/victorlcs87/plasma-ai-usage-widget.git
cd plasma-ai-usage-widget
python3 -m venv .venv
.venv/bin/pip install -e . pytest build setuptools wheel
scripts/install-plasmoid.sh
Set the collector path in the widget settings to the checkout's .venv/bin/ai-usage-collector. Read CONTRIBUTING.md for tests, translations and pull requests.
Help improve the project
Report a bug, suggest a feature, improve a translation or share the project with other Plasma users. Issues in English and Portuguese are welcome. Remove account details and credentials from anything you upload.
Support the project
If this widget makes your day easier, you can buy me a coffee on Ko-fi. Voluntary support helps me maintain and improve the project. The widget remains free and open source.
License
GPL-3.0-or-later. Independent community project, not affiliated with or endorsed by KDE, Anthropic, OpenAI or Google. Provider logos identify their services; see logo credits.
Metadata
Release files for plasma-ai-usage-collector 1.2.2
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 |
|---|---|---|---|---|
| plasma_ai_usage_collector-1.2.2.tar.gz | 299.8 kB | With provenance | Details for plasma_ai_usage_collector-1.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| plasma_ai_usage_collector-1.2.2-py3-none-any.whl | Python 3 | none | any | Details for plasma_ai_usage_collector-1.2.2-py3-none-any.whl |
Total release size: 435.2 kB
Release files / plasma_ai_usage_collector-1.2.2.tar.gz
| Download URL | plasma_ai_usage_collector-1.2.2.tar.gz |
|---|---|
| Size | 299.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9fa4702e54a3fe47dd11f0843b00ac7b09cfb36826e97ebc7d29e1f1550b2287
|
|
BLAKE2b-256 checksum How to use checksums |
234323eebafe00565229bba412971af1a316c162cd742a9c4899b3a8178ccf75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logRelease files / plasma_ai_usage_collector-1.2.2-py3-none-any.whl
| Download URL | plasma_ai_usage_collector-1.2.2-py3-none-any.whl |
|---|---|
| Size | 135.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
af5de00de362f2ff95756a9cbe1387b49538cd375f03fe49347c0606d9c5bd66
|
|
BLAKE2b-256 checksum How to use checksums |
0676fbd3d5f2f3bc5f31037c5482568ace5c83bec1fb58a82a89c1ac822e4aea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logSecurity for plasma-ai-usage-collector 1.2.2
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 plasma_ai_usage_collector-1.2.2.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 Oct 24, 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.