Skip to main content

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.

Latest release PyPI KDE Plasma 6 License Support on Ko-fi

Download · Install · Report a bug · Português brasileiro

Compact panel widget showing separate usage indicators for Claude, Codex and Gemini

Expanded widget with current and weekly quotas, reset countdowns, alerts and token history for three AI providers

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

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)

Source distribution for plasma-ai-usage-collector 1.2.2
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)

Table of built distributions (wheels) for plasma-ai-usage-collector 1.2.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.2.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page