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
- Clone this repository.
- Run
./install.sh from the repository directory.
- Open the Plasma widget selector.
- 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.
- Enable Ollama Cloud in the widget settings.
- Create an API key at ollama.com/settings/keys.
- 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:
- The
OLLAMA_API_KEY environment variable. It takes priority over the wallet.
- 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.
