Skip to main content

Plasma AI Usage Collector

Coletor de métricas de uso e cotas de agentes de IA (Claude, Codex e Gemini) para o widget nativo KDE Plasma 6.

Instalação

O widget (QML) só mostra dados que o Coletor (pacote Python plasma-ai-usage-collector, sem dependências) grava. O Coletor é obrigatório: sem ele o widget não exibe nada. Há três caminhos; escolha um.

a) Loja KDE e botão "Install collector" (recomendado)

  1. Instale o widget pela loja (Adicionar widgets > Obter novos widgets, busque "AI Usage").
  2. Abra o popup. Sem Coletor, aparece um card com o botão Install collector (ou Update collector, se o Coletor for mais antigo que o widget).
  3. Clique e confirme. A confirmação mostra o pacote, a versão e o destino.

O que o botão faz:

  • Baixa do PyPI o pacote plasma-ai-usage-collector na versão exata do widget (==X.Y.Z), nunca "a mais recente".
  • Cria o venv do widget em ~/.local/share/plasma-ai-usage/venv e instala nele.
  • Cria os atalhos ai-usage-collector e ai-usage-session-state em ~/.local/bin.
  • Não usa sudo e não mexe no Python do sistema.
  • Só roda com a sua confirmação. Nunca é automático: nem ao adicionar o widget, nem ao abrir o popup, nem por timer.
  • Nunca mexe num Coletor que você já tenha (pipx ou de desenvolvimento): se ~/.local/bin/ai-usage-collector existir e não for do widget, a instalação para sem alterar nada. Coletor mais novo que o widget só gera um aviso.
  • Sem python3 com venv e ensurepip, não instala nada: o card diz o que instalar (ex.: python3-venv no Debian/Ubuntu).
  • Ao terminar, verifica a versão instalada e atualiza os dados.

Em caso de falha o card mostra a causa (sem Python, rede, versão ausente no PyPI, permissão, conflito em ~/.local/bin, verificação) e o botão vira "Try again".

b) pipx

pipx install plasma-ai-usage-collector

Sem pipx, use um venv próprio e não instale no Python global:

python3 -m venv ~/.local/share/plasma-ai-usage/venv
~/.local/share/plasma-ai-usage/venv/bin/pip install plasma-ai-usage-collector==X.Y.Z   # a versão do Plasmoid
ln -s ~/.local/share/plasma-ai-usage/venv/bin/ai-usage-collector ~/.local/bin/

Para atualizar depois, use o botão "Update collector" do widget ou repita o pip install ...==X.Y.Z com a versão do Plasmoid (não use --upgrade sem versão: o widget exige a versão exata).

Depois instale só o widget pela loja. O widget acha o Coletor (ver "Onde o widget procura o coletor"). Mantenha as duas versões iguais.

c) A partir do código

python3 -m venv .venv && .venv/bin/pip install -e .
scripts/install-plasmoid.sh

Aponte o widget para .venv/bin/ai-usage-collector em Configuração > Geral > Caminho do coletor. scripts/package-release.sh gera o .plasmoid e a wheel em dist/.

Waybar

ai-usage-collector --waybar imprime uma linha JSON (text, tooltip, class, alt e, quando há nível, percentage) a partir do cache, sem consultar provedores nem a rede, sempre com exit code 0. Mantenha o cache atualizado com ai-usage-collector --refresh (ou pelo Plasmoid).

A classe é o pior nível de alerta entre as Contas Ativas no Sistema (contas inativas não contam): normal, warning ou critical. Sem nível confiável a classe é neutra: stale (dados desatualizados, erro ou pausa por HTTP 429) ou unknown (sem cache, cache inválido ou nenhuma conta ativa; texto —). Nunca é mostrado um 0% inventado. Rótulos de conta são escapados para o Pango markup do Waybar.

// ~/.config/waybar/config.jsonc
"custom/ai-usage": {
    "exec": "ai-usage-collector --waybar",
    "return-type": "json",
    "interval": 30,
    "tooltip": true
}
/* ~/.config/waybar/style.css */
#custom-ai-usage.warning { color: #f9e2af; }
#custom-ai-usage.critical { color: #f38ba8; }
#custom-ai-usage.stale, #custom-ai-usage.unknown { opacity: 0.6; }

Notas: text pode mostrar o % de uma janela com leitura local enquanto a classe fica unknown (leitura local não recebe nível); percentage considera só janelas com nível. Percentuais fora de 0..100 são limitados e NaN/Infinity são ignorados. A saída é JSON ASCII (acentos escapados como \uXXXX, válido para o Waybar), o tooltip mostra no máximo 20 linhas, e --waybar ignora as demais opções (só --cache-path vale).

Painel e popup

No painel cada item mostra o logo do provedor e o arco da Janela Nativa. Clique no item para abrir o popup com os dois arcos (nativa e semanal) daquele provedor no topo; passar o mouse abre o popup sem destacar ninguém.

Onde o widget procura o coletor

O plasmoide chama ai-usage-collector pelo shell, nesta ordem: o PATH, ~/.local/bin/ai-usage-collector, o venv do pipx (~/.local/share/pipx/venvs/plasma-ai-usage-collector/bin/) e, só por último, o caminho da opção Caminho do coletor (Configuração > Geral; collectorPath em main.xml, vazio por padrão; aceita ~/). Se nada for achado, cai em python3 -m ai_usage_collector. Para um venv de desenvolvimento, preencha o campo com ~/caminho/do/repo/.venv/bin/ai-usage-collector; nenhum caminho pessoal vai no código.

Histórico de Tokens, órfãos e configuração pela CLI

  • Exportar o histórico: ai-usage-collector --export-history csv|json imprime o Histórico de Tokens diário (até 400 dias, por provedor, Conta e modelo) na saída padrão. Identidades sem Conta cadastrada saem mascaradas.
  • Perfis Órfãos (Perfis Isolados sem Conta): --list-orphans lista em JSON, --reimport-orphan PROVEDOR PERFIL reimporta como Conta (funde se a identidade já existir) e --delete-orphan PROVEDOR PERFIL --confirm exclui do disco. Nada é apagado sem --confirm.
  • Opções --set-* (as mesmas que a tela de configuração aplica): --set-provider-config PROVEDOR (--credential-path, e no Claude --api-base-url, --api-key-stdin, --clear-api-key), --set-alert-config (--alert-mode pace|threshold, --alert-warning, --alert-critical), --set-notify-config (--notify-warning, --notify-critical, --notify-early, --notify-reset, --notify-mute), --set-update-config (--update-check on|off), --set-renew-config (--renew-gemini on|off, padrão off) e --set-visibility-config (--hide-when-not-running off|widget|provider).

Renovação automática das Contas inativas

A cada Intervalo de Atualização o coletor renova, antes de consultar o uso, as Contas inativas com login vencido. Só mexe no Perfil Isolado da Conta (profiles/); a Conta Ativa no Sistema nunca é renovada pelo coletor. No máximo uma tentativa por Conta por intervalo.

  • Claude: claude auth status com o perfil da Conta.
  • Codex: codex app-server (account/read com renovação do token), sem gastar tokens de modelo.
  • Gemini (opt-in, desligada por padrão): renovação do token no Google. Usa o app OAuth da Antigravity e lê o segredo do binário agy instalado (nunca vem no repositório), o que pode contrariar os termos do Google. Ligue em Configuração > Geral ("Renovar Contas Gemini inativas automaticamente") ou com ai-usage-collector --set-renew-config --renew-gemini on (off desliga). Desligada, o coletor nunca lê o agy nem chama o endpoint de token do Google, e a Conta Gemini vencida só avisa para você entrar de novo no provedor.

Requisitos: Plasma aberto, claude e codex no PATH e agy instalado e a opção ligada para o Gemini. Limites: o refresh token vale cerca de 30 dias; a Conta Ativa depende do uso da própria CLI. Tokens e saída das CLIs não vão para log nem para o status.json; só a classe do erro.

O card da Conta explica o estado: renovação pendente (nova tentativa na próxima consulta), login revogado, CLI ou agy não encontrado, tempo esgotado, rede indisponível ou falha genérica. Nos casos sem solução automática, faça login no provedor com a Conta. Riscos e decisões: docs/adr/0013-renovacao-de-conta-inativa.md.

Credencial do Gemini

A captura (--capture-current gemini) procura a sessão ativa nesta ordem: chaveiro (secret-tool, serviço gemini, usuário antigravity), ~/.gemini/oauth_creds.json e ~/.gemini/antigravity-cli/antigravity-oauth-token (CLI Antigravity, formato aninhado em token). GEMINI_CONFIG_DIR troca ~/.gemini. Esses arquivos e o chaveiro são só lidos na captura; a cópia fica isolada em profiles/ com permissão 0600.

Notificações de limite (opt-in)

O coletor avisa quando uma janela passa dos limiares, esgotará antes da liberação ou, se ativado, foi liberada. Configure em Configuração > Notificações ou com --set-notify-config. O envio usa o binário notify-send (libnotify) numa sessão gráfica com serviço de notificações; não fala D-Bus diretamente. Sem o notify-send (ou sem barramento de sessão) o aviso falha em silêncio: o coletor segue normalmente, registra uma única mensagem em stderr, tenta de novo no próximo ciclo sem repetir a mensagem e a marca some quando um envio funciona (notify_failed ao lado do status.json).

Estado da Sessão (Claude Code e Codex, opt-in)

ai-usage-collector --install-hooks registra hooks no settings.json do Claude Code (CLAUDE_CONFIG_DIR absoluto ou ~/.claude); --uninstall-hooks remove só os do widget (pode reindentar o arquivo). Perfil isolado: rode com o CLAUDE_CONFIG_DIR de cada perfil. Para o Codex, o estado "ocupada" vem dos logs de sessão sem instalar nada; ai-usage-collector --install-hooks codex (opcional) grava uma linha notify no config.toml (CODEX_HOME), nunca sobrescreve um notify seu, encerra o estado ocupado ao fim de cada turno e é o que habilita o som e o Notch no Codex (sem ele o Codex só mostra o estado). Ative "Mostrar o estado da sessão" na configuração do plasmoide. O caminho leve de consulta (ai-usage-session-state) exige reinstalar o pacote (pip install -e .); ele lê session-accounts.json, atualizado a cada refresh. Detalhes e limitações no ADR-0009.

Cores: acento e alerta

Os acentos "red" e "orange" do Notch podem coincidir com a cor de alerta (crítico/atenção). O nível nunca depende só da cor: ele aparece também pela forma (normal ●, atenção ▲, crítico ■, sem nível ○) e pela palavra.

Traduções (i18n)

O Plasmoid segue o idioma do sistema: inglês (texto-fonte, convenção KDE) e português do Brasil, ambos completos.

  • Mecanismo único: plasmoid/contents/ui/I18n.js (tr, trc, trp), que chama i18n/i18nc/i18np do KDE e, sem eles (harness qml6, testes), devolve o texto em inglês com os %N substituídos. Os modelos JS recebem I18n.tr como parâmetro tr. Só literais de string entram como msgid; nome de conta, mensagem do coletor etc. vão como argumento %N, nunca como msgid. Use frases inteiras com %N (nada de montar frase por pedaços) e trp para plurais.
  • Catálogos: po/plasma_applet_org.kde.plasma.aiusage.pot (domínio = plasma_applet_ + KPlugin.Id do metadata.json), po/pt_BR.po e po/en.po (en.po é gerado: msgstr = msgid).
  • Regenerar o .pot e sincronizar os .po (só Python, determinístico): python3 tools/i18n.py extract && python3 tools/i18n.py update. python3 tools/i18n.py check acusa msgid não literal e texto visível fora de i18n.
  • Novo idioma: crie po/<codigo>.po copiando o .pot (ex.: cp po/*.pot po/es.po), rode update, traduza todas as entradas (sem fuzzy, sem vazias, mesmos %N) e, se o idioma tiver regra de plural diferente, ajuste PLURALS em tools/i18n.py. O teste tests/test_i18n.py valida o novo arquivo sozinho (adicione o código em LANGS).
  • .mo: scripts/install-plasmoid.sh compila po/*.po (tools/i18n.py compile) para contents/locale/<idioma>/LC_MESSAGES/plasma_applet_org.kde.plasma.aiusage.mo numa cópia temporária e instala essa cópia; os .mo não são versionados.
  • Limites conhecidos: health.message (diagnóstico do coletor, em português) é mostrado como veio; o erro de consulta (fetch_error) é traduzido pelo kind. Data/hora usam o formato fixo dd/MM HH:mm e as unidades abreviadas da contagem regressiva (d h m s) não variam por idioma.

Smoke no runtime real do Plasma

scripts/plasmoidviewer-smoke.sh [diretório-de-PNGs] instala o plasmoide num HOME temporário, gera um status.json de fixture (tools/smoke_status.py), roda o plasmoidviewer sob xvfb-run em pt_BR e en_US, horizontal e vertical, clica na pílula (xdotool) e salva PNGs (import). Sai com código != 0 se o log tiver erro de QML do plasmoide (recursive rearrange, TypeError, ReferenceError, Unable to assign, is not defined, Binding loop). Não usa a sessão nem dados reais. Requer plasmoidviewer (plasma-sdk), xvfb-run, xdotool e ImageMagick; tests/test_plasmoidviewer_smoke.py o roda se existirem.

Licença e marcas

GPL-3.0-or-later (ver LICENSE). Claude e Anthropic são marcas da Anthropic PBC; OpenAI e Codex, da OpenAI, Inc.; Gemini e Google, da Google LLC. Este projeto é independente e não tem afiliação nem endosso dessas empresas; os logos só identificam o provedor.

Metadata

Release files for plasma-ai-usage-collector 1.2.1

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.1
File Size Uploaded Provenance Actions
plasma_ai_usage_collector-1.2.1.tar.gz 301.3 kB Without provenance Details for plasma_ai_usage_collector-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for plasma-ai-usage-collector 1.2.1
File Interpreter ABI Platform Actions
plasma_ai_usage_collector-1.2.1-py3-none-any.whl Python 3 none any Details for plasma_ai_usage_collector-1.2.1-py3-none-any.whl

Total release size: 437.8 kB

Release files / plasma_ai_usage_collector-1.2.1.tar.gz

Download URL plasma_ai_usage_collector-1.2.1.tar.gz
Size 301.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7cb379108499a8c472aca4ce17804f2162b9c80fc9f5272fdf5048dc0532067a
BLAKE2b-256 checksum
How to use checksums
1aa99fc3f8078bc3412f5d30e025d22e2de563e18b0842aa0b66e7d7c5e1555e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / plasma_ai_usage_collector-1.2.1-py3-none-any.whl

Download URL plasma_ai_usage_collector-1.2.1-py3-none-any.whl
Size 136.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d36e9fbb48a6b4769b9e94144db45323a77101d2560afc681acb243c24c96d93
BLAKE2b-256 checksum
How to use checksums
84cb46bb3634a9b4c81a9361d66008e63ab52655601aeb6ab6ca0fd5e2f962ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for plasma-ai-usage-collector 1.2.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.1 This release

2 release files No 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