KDE Plasma AI Quota HUD: My Arch Linux Setup
git rebase. To solve this, I built a HUD for the KDE panel that tracks remaining room and reset times for each agent via four circular indicators.The "Token-Week" Problem
The industry has created a bizarre new unit of measurement: the token-hour or token-week. Every provider does it differently:
- Claude: Uses rolling hour/day windows.
- Codex: Reports specific plan windows.
- Gemini: Requires local request estimation.
- DeepSeek: Operates on a monetary balance.
I've essentially turned my panel into a dashboard of "donuts." A full ring means the agent is ready; an empty one means it's time to switch models. Hovering provides the exact reset time, so I don't have to leave my terminal to check if I've exhausted my limits.
Technical Pivot: Data over Position
My initial deployment failed because I relied on the position of data in the API response. For Codex, I assumed the first window returned was the 5-hour limit and the second was the weekly limit.
When Codex changed their schema and stopped reporting the short window, my logic broke. The widget started labeling a 7-day window as "5h" because it was the first item in the list. To fix this for a more robust AI workflow, I implemented two changes:
1. Duration-based Identification: The system now identifies windows by their actual length. Short durations are flagged as sessions; long durations are flagged as weekly limits.
2. State Validation: I decoupled "failed queries" from "missing data." If a query fails, the HUD preserves the last cached value. If a query succeeds but a window is missing, the HUD removes that window from the state entirely.
This prevents the "ghost value" bug where a depleted quota appears active just because the API call timed out. For anyone building a custom LLM agent monitor, avoid positional indexing at all costs—API schemas shift too often.