fix(usage): consumo do Claude é lazy — evita o 429 do limite agregado

[aronpc]

Problema

"Parou de contar créditos" de novo: a barra de % do Claude some quando a API /api/oauth/usage retorna 429. Essa API divide um limite agregado com o /status do próprio Claude Code — o loop de fundo de 60 s consultando o endpoint alimentava o rate limit (e cada 429 estende o cooldown por backoff exponencial).

Investigação confirmou que nenhuma fonte passiva do Claude Code em disco carrega o utilization das janelas 5h/7d (transcript, .claude.json, stats-cache.json, .session-stats.json, policy-limits.json) — o % só existe na chamada ativa. Não dá pra "ler do hook/arquivo deles"; a saída é reduzir a pegada na API.

Solução — coleta lazy do Claude

O loop de fundo não bate mais na API do Claude. A chamada só dispara quando o usuário vai olhar o uso:

Gatilho	Busca %
Loop de fundo (60 s)	❌
Boot	✅ (1×)
Expandir overlay (set-expanded)	✅
Revelar janela — tray/atalho (toggleWin)	✅
Botão ⟳ (force)	✅

Entre gatilhos mostra o último % conhecido (ou o plano-só honesto). O cache de 5 min evita gastar chamada a cada abrir/fechar. GLM/Codex/Antigravity seguem no loop normal (não sofrem esse limite).

Detalhes

• usage.js: readClaudeUsage ganha allowFetch (default true); guard devolve cache/plano-só sem tocar a rede quando false. collectUsage propaga via claudeAllowFetch. A ordem dos guards (cooldown antes de lazy) mantém o boot-fetch seguro mesmo durante um 429 já ativo.
• main.js: collectAndSendUsage({claudeFetch}); loop false, boot/expand/reveal/force true.

Verificação

• Sintaxe OK (node --check)
• 190/190 testes (188 → 190; +2: lazy não bate / segura o último valor bom)
• Probe end-to-end: collectUsage com claudeAllowFetch=false → 0 chamadas (plano-só); =true → 1 chamada (% real)

Summary by CodeRabbit

• Melhorias
  • O uso do Claude agora é atualizado sob demanda, quando o usuário abre ou expande o painel, solicita uma atualização ou inicia o aplicativo.
  • O carregamento periódico em segundo plano deixou de consultar o uso do Claude continuamente.
  • O último percentual conhecido permanece visível mesmo após limites de requisição; quando indisponível, o painel exibe apenas o plano.
  • O cache de 5 minutos reduz consultas repetidas.
  • GLM, Codex e Antigravity continuam com atualizações periódicas normais.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 55624c13-e285-44b3-b609-b5a2cbb0470a

📥 Commits

Reviewing files that changed from the base of the PR and between d12866c and 498c8a3.

📒 Files selected for processing (4)

• CHANGELOG.md
• main.js
• src/usage.js
• test/usage.test.js

---

Walkthrough

A coleta do uso do Claude foi alterada para o modo lazy. O app busca dados no boot e quando o uso é visualizado ou atualizado, enquanto coletas periódicas em segundo plano preservam o cache sem acessar a API.

Changes

Uso lazy do Claude

Layer / File(s)	Summary
Controle de busca e cache src/usage.js, test/usage.test.js	readClaudeUsage pode bloquear chamadas à API, retornando o último valor armazenado ou o fallback de plano; testes validam ambos os comportamentos.
Gatilhos de coleta na interface main.js, CHANGELOG.md	O boot e os eventos de visualização/atualização permitem buscar o uso do Claude, enquanto o intervalo de 60 segundos usa o cache sem nova busca; o changelog registra a alteração.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Interface
  participant MainProcess
  participant UsageCollector
  participant ClaudeAPI
  Interface->>MainProcess: abrir, expandir ou forçar atualização
  MainProcess->>UsageCollector: collectUsage com claudeAllowFetch=true
  UsageCollector->>ClaudeAPI: consultar /api/oauth/usage
  ClaudeAPI-->>UsageCollector: percentual de uso
  UsageCollector-->>MainProcess: dados de uso

Loading

Poem

Sou coelho ligeiro, no cache vou saltar,
Só busco o Claude quando alguém quer olhar.
No boot dou um pulo, depois fico tranquilo,
Menos chamadas, mais uso no brilho.
🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	O título resume bem a mudança principal: tornar o consumo do Claude lazy para evitar 429 do limite agregado.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/claude-usage-lazy-fetch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}