Troubleshooting

The PLUGIN= path below matches a manual checkout or release-archive install (see installation), which uses the AiOverviewControl display-name casing. A DMS plugin-store install instead uses the manifest id and lands at ~/.config/DankMaterialShell/plugins/aiOverviewControl (lowercase leading a) — Linux paths are case-sensitive, so adjust the PLUGIN= line below to match whichever directory ls ~/.config/DankMaterialShell/plugins actually shows. The commands shown in the plugin's own Settings panel always use the correct path for your install automatically.

No cards appear

PLUGIN=~/.config/DankMaterialShell/plugins/AiOverviewControl
$PLUGIN/providers/get-provider-health "codex,claude,copilot" | jq .
$PLUGIN/providers/get-provider-usage "codex,claude,copilot" $PLUGIN/providers/get-copilot-usage | jq .

If terminal output is valid, run qmllint and restart DMS.

Codex

codex --version
codex login
$PLUGIN/providers/get-codex-usage | jq .

The adapter requires a Codex CLI version with app-server and account/rateLimits/read. It retries a transient rate-limit transport failure once and may reuse a successful snapshot for up to 15 minutes; the original updatedAt timestamp is preserved so the card can become visibly stale. Authentication failures never use this cache. Persistent app-server failures surface the underlying JSON-RPC message when one is available.

The app-server may temporarily return only a 10080-minute weekly window in rateLimits.primary with secondary: null. The plugin labels that window Weekly from its duration. OpenAI's current pricing documentation still describes a shared five-hour window plus possible weekly limits, so a missing five-hour row should be treated as a server/account response change or incident, not automatically as a formally announced quota-policy change.

Claude

If the local analytics are present but the 5-hour window shows an authentication error, renew the Claude subscription session:

claude auth login --claudeai

The plugin only reuses a successful quota response for two minutes. Expired credentials and older cache files are reported as errors instead of being displayed as 0% usage.

claude auth status
./providers/get-claude-usage

Claude analytics require readable JSONL files under ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects when CLAUDE_CONFIG_DIR is set). Quota windows are best-effort and may be absent when Claude Code changes its private OAuth behavior.

Copilot

gh auth status
gh api user --jq .login
./providers/get-copilot-usage | jq .

The adapter uses the GitHub-authenticated Copilot quota snapshot. If the regional api.github.com route fails before returning HTTP, it retries through another GitHub edge with normal TLS hostname verification. The last valid response may be reused for up to one hour and is labeled github-copilot-cache.

Environment variable is present in a terminal but missing in settings

DMS may have been started before the variable was exported. A shell-only export — including one in ~/.zshenv — is not inherited by an existing systemd-managed graphical session. Import it from a terminal where it is already set, restart DMS, and run the health helper again:

systemctl --user import-environment COMMAND_CODE_API_KEY
systemctl --user restart dms.service

For Command Code specifically, cmd login is usually preferable: the plugin reads the CLI's protected ~/.commandcode/auth.json credential when COMMAND_CODE_API_KEY is absent from DMS. The helper reports credential source names only, never secret values.

Provider shows zero percent

Zero can mean one of three things:

• the provider reports a real unused quota;
• the provider exposes balance/status but no total from which a percentage can be calculated;
• the card is informational because no public quota API exists.

Read the card's source and display value rather than assuming every provider has a percentage quota.

Antigravity quota or account layout

The normal Antigravity view deliberately groups known quotas as Gemini Models and Claude & OpenAI Models. These are family quotas, not placeholders: each reflects the model in that family with the least quota remaining. A real unrecognized model is isolated under Other Models, while internal placeholder entries are discarded. With multiple locally signed-in accounts, expand the card to see the family rows under each account email and install.

If the result looks inconsistent with the Antigravity Models screen, refresh the plugin and check the raw response without exposing credentials:

PLUGIN=~/.config/DankMaterialShell/plugins/AiOverviewControl
$PLUGIN/providers/get-provider-usage antigravity | jq .

For a temporary model-by-model diagnosis, enable Show individual Antigravity models in the plugin settings, then expand the Antigravity card. Turn it off again to return to the concise view. A Partial badge means at least one account succeeded and another failed; the expanded warning identifies the account, request stage, and cause. If every account fails, the card reports the actual OAuth, HTTP, rate-limit, or schema error. If the helper reports no session at all, open the affected Antigravity installation, sign in, and ensure sqlite3 is installed.

Hermes telemetry

Hermes reads $HERMES_HOME/state.db (default ~/.hermes/state.db) read-only, so the gateway can keep running while the card refreshes.

• Card reports "state database not found" — Hermes has not created its state database yet, or it lives elsewhere. Start Hermes once (hermes), or export HERMES_HOME for a custom install (native Windows installs live under %LOCALAPPDATA%\hermes).
• Card reports "sqlite3 is required" — install the sqlite3 command-line binary; the adapter uses it instead of linking a SQLite library.
• Cost shows $0 while tokens grow — expected. Hermes resolves pricing upstream, so estimated_cost_usd / actual_cost_usd are frequently 0 for routed providers. Tokens and API calls carry the real signal, which is why the 7-day chart plots tokens.
• "Top projects" is empty — only sessions that recorded a working directory appear there. Gateway sessions (Telegram, WhatsApp, Discord) have no cwd, so a week of chat-only usage legitimately shows no projects; the session-source badges still break the traffic down.
• Numbers look stale right after a conversation — the expanded telemetry is cached for 120s (matching the default refresh interval). Press Refresh twice, or wait one cycle.

Slow refresh or timeout

The widget has a 45-second total timeout. Each network adapter also has a shorter curl timeout. Reduce the selected provider count, increase the refresh interval, and test providers individually.

Notifications do not appear

Quota alerts require notify-send and flock in the environment that starts DMS:

command -v notify-send flock

The helper stores deduplication state under ${XDG_CACHE_HOME:-$HOME/.cache}/AiOverviewControl/notify-state.json. Test a notification without exposing provider credentials:

PLUGIN=~/.config/DankMaterialShell/plugins/AiOverviewControl
bash "$PLUGIN/providers/send-quota-alert" \
  manual-test 0 normal dialog-warning '#6750A4' \
  'AiOverviewControl test' 'Notification helper is working.'

Adjust PLUGIN for a plugin-store install as described at the top of this page.

A quota window never alerts

By default only the window the DankBar shows for that provider raises alerts (notifyWindowScope = displayed, which equals the primary window until a barWindowOverrides slot is set). To be alerted on Claude's 5 hour and 7 day windows, or Codex's weekly alongside its session window, set Windows that raise alerts to all in Settings.

If a per-provider threshold seems ignored, check the inline validation under Per-provider threshold overrides — entries with an unknown provider ID, a provider that is not tracked, or a percentage outside 1–100 are discarded at runtime and are now reported there as you type.

Exporting the usage history

The local store is trimmed to the configured retention, so keep a copy before it rotates:

PLUGIN=~/.config/DankMaterialShell/plugins/AiOverviewControl
"$PLUGIN/providers/export-usage-history" csv     # spreadsheet-friendly
"$PLUGIN/providers/export-usage-history" jsonl   # raw store

The script prints the file it wrote. Exit code 3 means no snapshot has been recorded yet (or none is readable), and 4 means the destination directory could not be written. Settings exposes the same two formats as buttons.

QML validation

qmllint AiOverviewControlWidget.qml AiOverviewControlSettings.qml AiOverviewControlI18n.qml ProviderLogo.qml
for file in i18n/*.json; do jq . "$file"; done