KDE Plasma 6 AI Agent Usage and Quota Monitor

Agents Usage is an open-source KDE Plasma 6 widget for AI coding-agent quotas and reset times.

The plasmoid monitors Claude Code, OpenAI Codex CLI, and OpenCode from your Linux desktop. It has no telemetry or analytics.

Website: serjor.github.io/kde-agents-usage

Features

• Show the remaining percentage for each available quota window.
• Show a countdown and the reset day and time (24-hour clock) for each quota reset.
• Select the agents that appear in the widget.
• Set warning and critical quota levels.
• Refresh automatically at a configurable interval.
• Keep local quota data in private cache files.

The panel view shows all available quota windows. Open the widget to see reset countdowns, plans, and data sources.

Supported agents

Agent	Data source	Quota result
Claude Code	Local status-line collector	Five-hour, weekly, Sonnet, and Opus windows when available
Claude Code	Optional Anthropic usage API	Five-hour, weekly, Sonnet, and Opus windows when available
OpenAI Codex CLI	Recent local session events	Last observed five-hour and weekly windows
OpenAI Codex CLI	Optional account query through the installed CLI	Current five-hour and weekly windows
OpenCode	Optional local provider export	Windows from the selected provider
Ollama Cloud	Optional ollama.com balance API	Session and weekly windows, or included credit

OpenCode connects to different model providers. Thus, OpenCode does not have one universal quota.

The widget does not estimate missing percentages. It shows an unavailable state when an agent does not supply quota data.

Requirements

• KDE Plasma 6.
• Python 3.10 or a newer version.
• kpackagetool6.
• Optional, to save the Ollama Cloud API key in the system wallet: secret-tool (libsecret) and kdialog.

The widget has no external Python package dependencies.

Install

1. Clone this repository.
2. Run ./install.sh from the repository directory.
3. Open the Plasma widget selector.
4. Add Agents Usage to a panel or the desktop.

If Plasma does not list the widget, restart Plasma Shell:

systemctl --user restart plasma-plasmashell.service

Run ./install.sh again to install an update.

Install from a release file

Download the .plasmoid file from GitHub releases and install it:

kpackagetool6 --type Plasma/Applet --upgrade <file>.plasmoid

Configure Claude Code

The local status-line collector is the most private Claude source. It does not make network requests.

Add this object to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "python3 ~/.local/share/plasma/plasmoids/io.github.kde-agents-usage/contents/code/claude-statusline-collector"
  }
}

If you already have a status-line command, connect the collector through that script. Do not replace your existing command.

You can use the Anthropic usage API instead. Enable Allow requests to the Anthropic usage API in the widget configuration.

This option is off by default. It reads the Claude OAuth token and sends it only to https://api.anthropic.com/api/oauth/usage. The endpoint rate-limits clients that do not identify as Claude Code, so the request uses the claude-code/<version> user agent of the installed CLI. The cached API values are used only while this option is on.

Claude Code renews its short-lived access token only while it runs, so the stored token has usually expired after the computer was off. When that happens, the helper renews it with the stored refresh token at https://platform.claude.com/v1/oauth/token, as Claude Code does, and writes the new tokens back to ~/.claude/.credentials.json so Claude Code keeps working with them. It takes the same lock files as Claude Code and skips the renewal while Claude Code is renewing the token itself.

Configure Codex

By default, the widget reads quota events from local Codex session files. A reset made outside an active Codex session does not update those files until Codex produces its next rate-limit event.

Enable Fetch current Codex limits through the Codex CLI to reflect external resets immediately. The helper sends account/rateLimits/read to the installed Codex app server. Codex handles authentication. The widget does not read or store the Codex access token. If the live query is unavailable, the widget uses the latest local session event.

Configure an OpenCode provider

Create ~/.config/kde-agents-usage/opencode.json when an OpenCode provider supplies rate limits.

Use this format:

{
  "plan": "provider plan",
  "rate_limits": {
    "primary": {
      "used_percent": 30,
      "resets_at": 1788543614
    },
    "secondary": {
      "used_percent": 45,
      "resets_at": 1788773266
    }
  }
}

used_percent is the consumed quota. The widget converts this value to the available percentage.

Configure Ollama Cloud

The widget reads your Ollama Cloud quota from the ollama.com balance API. Legacy plans show the session and weekly limits with their reset times. Current plans show how much of the included credit is used and when the billing period ends. This option is off by default.

1. Enable Ollama Cloud in the widget settings.
2. Create an API key at ollama.com/settings/keys.
3. Click Add API key… under the option and paste the key.

The widget saves the key in the system wallet (KWallet or another Secret Service provider) through secret-tool, so the key never appears in a command line or a configuration file.

If secret-tool is not available, provide the key through one of these places instead:

1. The OLLAMA_API_KEY environment variable. It takes priority over the wallet.
2. A single-line file at ~/.config/kde-agents-usage/ollama-key that contains only the key. The wallet takes priority over this file.

The key is sent only to https://ollama.com/api/balance. The helper caches the quota values for one hour in ~/.cache/kde-agents-usage/ollama-usage.json and never stores the key.

Privacy and security

The default configuration makes no network requests. Codex data and OpenCode provider exports stay on your computer.

The helper reads recent Codex session files. It extracts only rate-limit values, reset times, and the plan name.

The Claude status-line collector stores only quota values, reset times, and the plan name. It does not store the full input.

The optional Anthropic request keeps the OAuth token in memory. It does not cache the token or follow HTTP redirects. A renewed token is written only to the Claude Code credentials file, with user-only permissions.

The optional Ollama request keeps the API key in memory. It does not cache the key or follow HTTP redirects.

The optional Codex account query delegates the authenticated request to the installed Codex CLI. The widget receives only the quota snapshot and does not read Codex credentials.

Cache files use user-only permissions. The cache directory is ~/.cache/kde-agents-usage.

The project does not collect prompts, responses, source code, account identifiers, or usage analytics.

Read SECURITY.md before you report a security problem. Use GitHub private vulnerability reporting for sensitive details.

Development

Run the automated tests:

python3 -m unittest discover -s tests -v
python3 -m py_compile package/contents/code/agent-usage-json package/contents/code/claude-statusline-collector

If qmllint is installed, examine the QML files:

qmllint package/contents/ui/main.qml package/contents/ui/configGeneral.qml

Inspect the normalized output:

python3 package/contents/code/agent-usage-json | python3 -m json.tool

Read CONTRIBUTING.md before you submit a change.

Project credits are available in CONTRIBUTORS.md.

Related projects

The package uses the KDE Plasma 6 widget structure.

The provider design took inspiration from PlasmaWidgetAiUsage, an MIT-licensed project.

License

KDE Agents Usage is available under the MIT License.