agentleFS
edilsonvilarinhoedilsonvilarinho/usage-monitor/CLAUDE.md

usage-monitor

CLAUDE.md19 starsChanged 50 days agoMITView on GitHub

Servidor de time (server/, opcional — só quem usa a integração com time): KMP Desktop (JVM único alvo). Código organizado em três camadas com dependências unidirecionais: presentation → domain ← data. Núcleo puro — zero imports de Ktor, Compose ou bibliotecas externas. Decisões e histórico por fornecedor em docs/integrations.md, seção "Decisões de implementação". Leia a seção da fonte antes de mexer nela. Regras que não podem ser esquecidas: - DTOs com @Serializable + @SerialName; repositórios usam suspendRunCatching { }, que…

  • Reads credentials
  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use cases usam operator fun invoke() — chamados como useCase().

    line 72

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Rodar a aplicação Desktop
gradlew.bat run

# Compilar sem rodar
gradlew.bat desktopJar

# Todos os testes (domain + data + ViewModel + UI)
# A task raiz `test` não existe neste projeto KMP — use `allTests`.
gradlew.bat allTests

# Apenas testes do commonTest (domain, mappers, ViewModel)
gradlew.bat desktopTest --tests "com.usagemonitor.domain.*"
gradlew.bat desktopTest --tests "com.usagemonitor.data.*"
gradlew.bat desktopTest --tests "com.usagemonitor.presentation.*"

# Apenas testes de componente UI (desktopTest)
gradlew.bat desktopTest --tests "com.usagemonitor.ui.*"

# Forks paralelos: o default e 1. So ligue numa maquina com `~/.skiko` ja
# populado -- num cache frio os forks se atropelam extraindo a nativa do Skiko.
gradlew.bat allTests -PtestForks=4

# Cobertura: a instrumentacao do Kover e opt-in, senao custa 6-7s por passada
# para produzir um numero que ninguem le. No CI ela liga em todo run que executa a suite.
gradlew.bat allTests -Pcoverage
gradlew.bat koverHtmlReport -Pcoverage

# Relatorio de testes e cobertura (Kotlin + servidor) em HTML no design system:
# skill `usage-monitor-test-report`; saida em build/test-report/index.html
node .claude/skills/usage-monitor-test-report/scripts/build-test-report.mjs

# Limpar build cache
gradlew.bat clean

Servidor de time (server/, opcional — só quem usa a integração com time):

cd server
npm install
npm test        # vitest + supertest
npm run test:coverage  # + cobertura v8 em coverage/ (lida pelo relatorio de testes)
npm run dev     # http://localhost:3000

Arquitetura

KMP Desktop (JVM único alvo). Código organizado em três camadas com dependências unidirecionais: presentation → domain ← data.

Source sets

Source setConteúdo
commonMaindomain + data (exceto leitura de ficheiros) + presentation/UI
desktopMainLocalCredentialDataSource (usa java.io.File) + Main.kt (arranque e composição dos hosts) + AppGraph.kt (DI) + hosts de janela
commonTestTestes unitários de domain, mappers e ViewModel
desktopTestTestes de componente Compose (runDesktopComposeUiTest)

Camada domain (commonMain/domain/)

Núcleo puro — zero imports de Ktor, Compose ou bibliotecas externas.

  • QuotaInfo: entidade com percentageUsed e remaining calculados. UsageUnit diferencia TOKENS, REQUESTS (MiniMax), PERCENTAGE (Anthropic/Codex) e CURRENCY_USD (saldo DeepSeek). currencyCode (default "USD") diz em que moeda os valores monetários estão. Não crie valores novos em UsageUnit: os when exaustivos do card, do histórico e do gráfico quebram; campo novo com default é retrocompatível, valor de enum novo não é.
  • ApiUsageStats: agrega lista de QuotaInfo por API.
  • Interfaces AnthropicRepository / MiniMaxRepository: o domain define o contrato; data implementa.
  • Use cases usam operator fun invoke() — chamados como useCase().

Camada data (commonMain/data/ + desktopMain/data/)

Decisões e histórico por fornecedor em docs/integrations.md, seção "Decisões de implementação". Leia a seção da fonte antes de mexer nela. Regras que não podem ser esquecidas:

  • DTOs com @Serializable + @SerialName; repositórios usam suspendRunCatching { }, que relança CancellationException (runCatching o engolia; #598).
  • Leitura de ficheiro só em desktopMain (LocalCredentialDataSource, LocalApiKeyDataSource). Chaves de MiniMax/DeepSeek/OpenCode Go só de ~/.usage-monitor/api-keys.json, nunca hardcode nem variável de ambiente. Fontes com chave: API_KEY_DEPENDENT_SOURCES, não literal repetido.
  • Renovação OAuth: o corpo precisa de client_id e scope (sem eles, 400 Invalid request format); checar status HTTP antes de desserializar; regravar o ficheiro por patch de JsonObject, nunca pelo DTO (apagaria mcpOAuth/refreshTokenExpiresAt).
  • User-Agent: claude-code/1.0.0 no /api/oauth/usage é obrigatório.
  • Créditos Anthropic: extra_usage primário, spend secundário; moeda nem sempre USD; expoente ≠ 2 não vira cota; AnthropicQuotaLabels.EXTRA_CREDITS é chave de série — não renomear.
  • Última leitura mantida em falha para toda fonte (statsRetainedAfterFailure, teto 7 dias); 429 tipado com backoff persistido (RateLimitedException, RefreshSchedule.kt).
  • Endpoint não documentado degrada por campo ausente e falha com resposta vazia (preserva o cache). Número que a API não informa não é derivado.
  • Proxy: só vale após reiniciar; falha de conectividade é classificada por tipo de exceção.
  • TLS: cacerts + repositório do SO (SystemTrustStore.kt); jdk.crypto.mscapi entra no modules(...) só no build Windows (jlink de outro SO falharia).
  • Tipo com credencial nunca usa o toString gerado: data class sobrescreve com redactedSecret, ou é classe comum (CursorSessionCredentials). ArchitectureRulesTest cobra pelo nome do campo.
  • Antigravity: argumento por lista, nunca por shell; disjuntor e TTL de 5 min obrigatórios.
  • Codex: uma janela ao vivo basta; limite por modelo vem do rollout local, soma depois das janelas ao vivo e nunca derruba a fonte. CodexQuotaLabels é chave de série — não renomear.
  • Contas Codex extras (CodexProfileRegistry): a padrão segue sem profileId; id das extras começa com codex-. Cor/emoji por conta leem anthropicProfileId, nunca profileId cru.
  • Índice CLI (#381): message.id repetido funde por MAX (a saída cresce entre linhas); vazão é ponta a ponta (request_ts → last_line_ts), soma de tokens e de tempo, nunca média de razões. Codex versiona em codex_cli_index_meta.
  • Acesso web local (#388) e bot Telegram (#387): opt-in, segredo em ~/.usage-monitor/{web-access,telegram}.json, tipos sem data class. Servidor só GET, token em toda rota (MessageDigest.isEqual); bot começa do agora e só atende conversa pareada. Saem do UsageSnapshot — nunca prompt, resposta ou caminho.

Camada presentation (commonMain/presentation/)

Decisões e histórico de cada funcionalidade em docs/presentation.md. Leia a seção da funcionalidade antes de mexer nela. Regras transversais:

  • UiState: sealed interface Loading/Success(data)/Error(message); falha parcial emite Success com dados parciais. onDestroy() ao fechar janela; escopos com SupervisorJob.
  • DashboardViewModel: coleta adaptativa por alvo (60 s com sessão ativa, 5 min sem, backoff em 429), publicação incremental por alvo sob stateMutex, histórico sequencial (historyMutex). refresh(target) mexe só no alvo pedido.
  • Componentes UI stateless; só DashboardScreen é stateful.
  • Timezone de reset: sempre TimeZone.of("America/Sao_Paulo"), label BRT. Agrupamento por hora sai do SQL em UTC e é traduzido no domain.
  • Ordem total e determinística em toda lista publicada por StateFlow: duas leituras iguais têm de dar listas iguais, senão a tela recompõe a cada tique.
  • Leitura que falha mantém os números anteriores e publica só a mensagem.
  • Uso detectado pela cota (QuotaActivityTracker, #385) acende o arco da HUD e, desde a #478, põe só o próprio alvo a 60 s (DashboardCadence); nunca entra no cliBusy, que é global e aceleraria todas as fontes.
  • Nunca valor novo em CliSessionRange para cortes de tempo; use parâmetro (sinceEpochMillis).
  • Custo é recalculado dos tokens com ModelPricingTable, nunca rateado. Modelo sem tarifa não vira custo zero (unpricedTurnCount, + no valor). Ferramenta não entra em custo. Faixa de prompt (#525) é por turno: soma usa groupCostMicros com a parte longa, nunca costMicros; sufixo depois do prefixo é só data de 8 dígitos.
  • null é "não medido", zero é "medido e sem valor" — não colapsar.
  • INDEX_SCHEMA_VERSION vive em cli_index_meta, não em PRAGMA user_version; coluna nova em cli_sessions precisa de quem a preencha num arquivo que nunca mais muda.
  • Alertas da bandeja: decisão é função pura; UsageAlertState é a dedup; limiar é piso (trunca); silêncio adia, não consome. UserPreferences (domain) é código morto.
  • Só metadados de uso saem do app (exportação, relatório, time) — nunca prompt ou resposta.
  • Animação infinita só atrás de AppMotionPolicy.continuous (trava o waitForIdle).

Empacotamento, atualização automática, novidades e ajuda

Decisões e histórico em docs/build-and-release.md, seção "Decisões de empacotamento e atualização". Regras:

  • Formatos: Exe (NSIS), Deb/Rpm, Dmg. Sem Msi; o upgradeUuid fica para remover instalações MSI antigas. jpackage não faz cross-compile.
  • Auto-start: entrada com --autostart; o nome do valor Run não muda. Agendador de Tarefas foi medido e recusado.
  • Segunda instância nunca sai calada: pedido em ~/.usage-monitor/focus.request, atendido por focusHud (a janela da HUD). activateWindow alterna alwaysOnTop false → true → anterior.
  • Atualização automática: SHA-256 contra o digest da API do GitHub; flags de build e piso de versão por plataforma; Windows só NSIS per-user; Linux só árvore XDG gerenciada. Texto de reinício diz o que reinicia. Progresso é texto, não animação.
  • Novidades: gatilho é CURRENT_APP_VERSION ≠ releaseNotesSeenVersion, nunca o recibo. Ordenação de versões só em AppVersionComparison.kt (SemVer: X.Y.Z-beta.N < X.Y.Z).
  • Canal beta (#355): tag vX.Y.Z-beta.N publicada como prerelease e nunca latest — é isso que protege quem não optou. Opt-in receiveBetaUpdates; desligar não faz downgrade; só o sufixo -beta.N é aceito (workflow e updater do Linux). Exe/Dmg levam só o número; Deb/Rpm ~beta.N. Publicação pela skill usage-monitor-release-beta.
  • Vídeo de lançamento (#503): skill usage-monitor-release-video — vertical, PT e EN, voz Piper, legenda; ritmo é regra (≤ 15 caracteres/s, ≤ 90 s): corta-se texto, nunca acelera a voz. Ferramentas fora de build/.
  • Diagnóstico (#416): app.log recebe falha não tratada (registro no CrashHandler, nunca handler por escopo), recordFailure, stderr e EDT parado; --diagnostics empacota por lista fechada, sem janela.
  • Linha de comando (#418): parseCommandLine é o dono do argv; opção desconhecida avisa e não impede a abertura; saída no idioma do app, sem acento em console que não é UTF-8 (#439; erro de uso continua em inglês).
  • Modo terminal (#439, #440, #441; seções "Modo terminal" do build-and-release.md): só lê, em somente leitura, sem requisição nem trava segura; status --json é contrato. Com coletor vivo, configurar é pedido ao ConfigApplier (um escritor só); segredo só pela entrada. TUI desenha por função pura (TuiScreen), nunca pelo view model.
  • Raiz de dados (#419): caminho em ~/.usage-monitor só pelo AppDataDirectory (file = dados/instância, installationFile = o que NSIS/updater leem em caminho fixo); configurada uma vez no main(). Fora da raiz padrão: atualização e autostart desligados.
  • Ajuda: passos citam o rótulo real do controle; GIF animado pelo Codec do Skia com cópia imutável dos bytes; laço de quadros em desktopMain; gradlew.bat generateHelpMedia regenera.

Injeção de dependências

Manual, sem framework. AppGraph.kt monta data sources, repositórios e use cases (sequência HttpClient(OkHttp) → datasources → repos → use cases); AppViewModels.kt monta os view models e é o dono único do encerramento (shutdown(), idempotente), chamado pela saída do app, pelo onDispose da composição e pelo shutdown hook — nunca uma segunda cópia (histórico no plano #298). Main.kt só faz o arranque e compõe os hosts (HudWindowHost, ModalWindowsHost, BugReportWindow, SettingsWindowHost, AppTrayHost). Não há janela principal: a HUD é a única de visualização e a âncora do app (anchorAppWindow: graph.mainWindow, registro de arranque e ACK de atualização); estado de shell e de modais mora em AppShellState/AppModalState. Os arquivos ficaram no pacote com.usagemonitor, e não num subpacote, para não abrir a visibilidade dos helpers internal/private que eles usam.

-Xmx3g no gradle.properties não é paliativo — sem ele o build cai em OOM; motivo no próprio arquivo e no M7 do main-refatoracao-298-execucao.md.

Regras de arquitetura e tamanho

Impostas por ArchitectureRulesTest (src/desktopTest/.../architecture/), que roda no allTests — a regra não depende de revisão lembrar dela.

  • Comportamento nativo medido numa plataforma só nasce restrito a ela (issue #340): chamada ao sistema de janelas medida só no Windows entra atrás de função pura com teste da lista de plataformas (precedente: hudHitRegionMode); liberar outra plataforma é decisão com medição, e o estado novo restringe, nunca abre no escuro (#426: o Linux recorta só sem alfa). window.shape/setShape só em HudWindow.kt e DesktopWindowFrame.kt — outro arquivo falha.
  • Direção das camadas por import: domain não importa Ktor, Compose, kotlinx.serialization, java.io, data nem presentation; data não importa presentation nem Compose; presentation não importa data. Quando a apresentação precisa de algo de data, o contrato sobe para o domain como porta e data o implementa (precedente: UsageExportEncoder).
  • Arquivo de produção ≤ 800 linhas; função ≤ 300, medida por varredura de chaves que ignora comentário e string. Nada de arquivo-deus nem composable-deus: estado, efeitos e ações de uma janela moram em arquivos próprios, e um host compõe.
  • Texto PT/EN não cresce inline: INLINE_LANGUAGE_CHECKS_CEILING é catraca de == AppLanguage.PT em produção — texto novo vai por localized(language, pt, en) ou objeto de rótulos (CommonLabels, CliSessionsLabels…); migrar um arquivo baixa o teto. Classificação de fonte é predicado do domain com when exaustivo (ApiSourceClassification.kt), nunca conjunto literal repetido.
  • Sem exceções: FILE_CEILINGS/FUNCTION_CEILINGS estão vazias e exceção nova não entra — divida o arquivo (histórico em docs/planos/divisao-arquivos-grandes-302-309-execucao.md). Entre 750 e 800 linhas, a próxima mudança começa extraindo, não crescendo.

Integração com time (server/)

Recurso opcional, servidor Node.js self-hosted (Express 4 + TypeScript + SQLite). Contrato da API e deploy em server/README.md; decisões e histórico em docs/team-integration.md. Leia antes de mexer em cliente ou servidor do time. Regras:

  • Chave de agrupamento é o accountUuid, sem organizationUuid.
  • Chave de time é por pessoa; se amarra a conta por POST /v1/claim ou ingest. Nenhum GET reivindica. label com e-mail é portão (TEAM_KEY_LABEL_MATCH, nasce strict).
  • TEAM_ADMIN_TOKEN lê e é o portão único dos DELETE (requireAdminToken não se toca); TEAM_REPORT_TOKEN é leitura global sem poder destrutivo; nenhum dos dois escreve no ingest.
  • Apagar conta: ordem dados → vínculo → bloqueio; bloqueio checado antes da credencial na escrita.
  • Configuração do cliente em ~/.usage-monitor/team.json (segredo), nunca em PreferencesSettings.
  • Vários times (#547): agregado TeamIntegrations, uma conta em no máximo um time, enabled só no agregado; team.json v2 espelha o 1º time nos campos planos (downgrade); time sem id é LEGACY_TEAM_ID, nunca vazio; repositório e offset por time.
  • Envio pelo TeamSyncService (30 s), indexa antes de enviar, conexão SQLite compartilhada; apelido viaja no ingest. Renomear nunca duplica: chave (account_key, device_id).
  • Servidor não precifica (exceto /metrics); o cliente aplica ModelPricingTable. tools/ci/check-pricing-parity.mjs compara as duas tabelas — o formato das listas é contrato.
  • Rota nova contra servidor antigo: 404 lembrado por URL, só o 404 cai no fallback. Campo novo em rota existente: sem gate.
  • Relógio: presença usa o offset medido do servidor, nunca Clock.System.now() cru.
  • until é semiaberto. Métricas: BigInt, gauges de janela, sem session_id/cwd como rótulo.
  • Ordem das listas do time: total, determinística, sem carimbo de tempo no comparador.
  • Nunca trafega conteúdo de prompt ou resposta.
  • Falha com o servidor de time aparece pela etapa (teamConnectionFailureOf, #494), classificada por tipo; nunca a exceção crua, nunca "confiar mesmo assim" no certificado.

Sistema visual

Histórico: docs/planos/refatoracao-visual-opencode-execucao.md.

Design system — precedência

A fonte de verdade visual é docs/design-system/ (tokens, contratos components/**/*.prompt.md, regras do readme.md); o protótipo prototipo-visual-opencode.html é o mockup obrigatório de cada tela (layout, colunas, estados), não de token, primitiva ou copy.

DivergênciaQuem venceO que fazer
Compose × design systemdesign systemcorrigir o Compose
Compose × protótipo (layout de tela)protótipocorrigir o Compose
Design system × protótipodesign systemcorrigir o protótipo, no mesmo commit
Design system tecnicamente erradoo Kotlincorrigir docs/design-system/, com a decisão registrada

Nenhuma tela reimplementa uma primitiva. Antes de escrever Surface, Card, Modifier.border, .background com cor de superfície ou RoundedCornerShape, procure em presentation/ui/components/ — AppStructure.kt, AppControls.kt, AppStates.kt e os vizinhos AppTabs.kt, AppSettingsNav.kt, AppSurfaceDepth.kt, AppChips.kt, AppMenu.kt, AppTooltip.kt e AppStatusPill.kt. Se a primitiva não existir, o commit que a cria e o commit que a consome são o mesmo: primitiva sem adoção não conserta nada (histórico em compose-implementation.md).

Cor de acento sai de AppAccents.current e de AppTone, nunca de darkAppAccents/lightAppAccents nem de val de topo de arquivo (congela o tema; AppAccentsContrastTest guarda).

Toda alteração de tela é registrada no protótipo e no design system, no mesmo commit da mudança — janela, diálogo, faixa, bandeja e PDF; desatualizados, a precedência acima aponta para documentos que não descrevem o produto. Como registrar: skill usage-monitor-design, "Ao terminar".

Tokens, profundidade, motion, modais, tipografia e primitivas: decisões e histórico em docs/design-system/compose-implementation.md. Regras:

  • Tokens em AppTheme.kt: superfícies (AppSurfaces), raios 4/6/8/10 com teto 10, AppDepth (5 patamares), AppSpacing, AppMotion. AppSurfaceLadder é derivado, nunca retocado.
  • Motion: tween para cor/opacidade, mola para posição/tamanho; só GENTLE/SNAPPY/EXPRESSIVE; sem overshoot em dado. AppMotionPolicy nasce Static; só o Main passa a preferência, e a todas as janelas.
  • Modais: todas por AppDialogWindow; a janela nasce na primeira abertura (ou no pré-aquecimento opt-in, só Windows) e depois só se esconde; já aberta e escondida há 60 s, sai da composição (#562: ~200 MB nativos por janela); pedido por StateFlow; nome na trilha é fixo (diagnosticName). Diálogo interno é AppDialog, nunca AlertDialog.
  • Tipografia: Plex Mono em label*/title*/headline*/display*, Plex Sans em body*; carga do classpath, nunca composeResources. Número é label*.
  • Primitivas são stateless. Aba × segmentado × chip têm papéis distintos. Cor nunca informa sozinha. Acento é identidade de fonte. AppSwitch ligado é verde.

Antes de escrever teste de tela, leia "Armadilhas de teste de tela" em compose-implementation.md — seis defeitos (FlowRow+weight, semântica de ícone, placeholder, altura da cena, modifier do campo, borda) que já custaram uma suíte vermelha cada.

Janelas, cards e tooltips: regras e histórico em docs/presentation.md, seção "Sistema visual — janelas, cards e tooltips" — leia antes de mexer. Inegociáveis: escala da interface troca só a densidade, nunca fontScale, e cada janela recebe o valor; monitor por workAreaForPosition, nunca defaultScreenDevice; a barra HUD é o único modo de visualização — não reintroduzir seletor de modo nem segunda moldura (DashboardScreen só existe para testes e capturas).

Barra HUD — notch (Hud*.kt): regras e histórico em docs/hud-notch.md — leia antes de mexer. Inegociáveis: tamanho da geometria (hudNotchSizes), janela de origem e tamanho fixos, nenhum redimensionamento AWT por quadro; Window.shape pelo hudHitRegionMode; no Linux a janela nasce com o alfa certo e renasce quando o monitor muda ou o alfa cai (HudWindowFrame.kt) — remendar a aberta congela o desenho; no COSMIC é POPUP (hudWindowType); o notch não cresce — balão de uma conta ou da engrenagem, conteúdo da janela e nunca Popup; botões do card com dona única (cardActionsFor).

Regras que continuam valendo: nenhuma composable nova em runUsageMonitor — ele só compõe os hosts; nenhum Column + verticalScroll vira LazyColumn; nenhum valor novo em enum existente.

Modo terminal (CLI/TUI): design system próprio em docs/design-system/cli/ (tokens em tokens/terminal.css), mockup de cada tela em docs/planos/prototipo-modo-cli.html, com a mesma precedência e a mesma regra de registrar toda tela nos dois. Inegociáveis: fundo do terminal nunca pintado, estado sempre escrito, quatro paletas (truecolor escuro/claro, 16 cores, sem cor) e nenhum glifo fora da tabela.

Marca: tools/brand/render_icons.py gera os ícones por tamanho lógico; janela e bandeja nunca usam o de 512 px (detalhes em docs/build-and-release.md).

Relatório PDF: Plex Mono embutida e o saneamento WinAnsi de UsageReportDocument.sanitized permanece; sem a fonte, cai para Helvetica (decisão no PdfUsageReportRenderer.kt).

CI e testes

Decisões, medições e incidentes em docs/build-and-release.md, seção "CI e testes — decisões". Regras:

  • Plataformas ("Platform reality" no CONTRIBUTING.md, #342): a suíte só roda no Windows e nenhum teste exercita o sistema de janelas. Mudança em host de janela é aberta no Linux (X11) antes do merge, ou o PR diz o risco; o PR diz em que plataformas foi testado.
  • Workflows (#344): ci.yml único — job changes recorta por path, jobs em paralelo só do que mudou, ci-ok é o check único (pulado conta como sucesso), exigido pelo ruleset main (#496: só por PR, sem force-push, bypass de admin só por PR); release-linux.yml só por tag, versão vem da tag (-PappVersion), sem commit de bump. Cache do Gradle pela gradle/actions/setup-gradle, gravado só na main — tag e CodeQL só leem.
  • CI roda com -PtestForks=3; localmente 1. Com forks, extractSkikoNative roda antes. Verde local e vermelho no CI em teste de UI: olhe o ~/.skiko antes do teste.
  • Teste de tela usa ScreenTestTheme (Reduced); teste de primitiva que anima usa AppTheme. Teste de tela novo vai no arquivo da tela dele.
  • Job que pulou a suíte diz que pulou (tools/ci/test-summary.mjs --require).
  • delay em runTest é tempo virtual: espera de estado de view model usa yield() + Thread.sleep (pauseForBackgroundWork). awaitSettledState espera a coleta inteira (refreshingTargets vazio), não o primeiro Success.
  • Cobertura opt-in por -Pcoverage; meta de 95% de linhas (Kotlin e servidor) com catraca: piso em coverageLineFloorPercent (koverVerify no CI) e thresholds.lines do vitest, só sobe, no commit que o eleva (plano cobertura-95-execucao.md).
  • Cobertura do diff (#496, tools/ci/diff-coverage.mjs): linhas de produção que o PR altera, piso 90%, nos jobs desktop-windows (Kover) e server (lcovonly). Nasce informativa (aviso, fora do ci-ok) — o #495 mediu 60%; vira bloqueante pelo critério do plano fluxo-automatizado-496-execucao.md.
  • Dependabot (#496): auto-merge só de minor/patch de gradle/npm_and_yarn (dependabot-automerge.yml); major e github_actions continuam manuais.
  • Job test-report (skill usage-monitor-test-report): HTML de testes e cobertura no artefato test-report a cada run com a suíte do desktop; informativo, fora do ci-ok.
  • Classe open com todo método open sobrescrito no teste: cobertura alta sem costura testada.

Fluxo de trabalho (desde 2026-10-22; sempre ativo desde 2026-10-28, #496)

Vale para todo pedido que altera o repositório, sem o usuário citar o fluxo — qualquer verbo ("ajusta", "corrige", "muda", "adiciona"), issue ou tarefa. Claude conduz o resto, nesta ordem e sem esperar aprovação entre os passos. Esta regra é a autorização de commit, push, PR e merge exigida pela skill usage-monitor-commit-push. Roteiro executável, com os comandos de cada passo: skill usage-monitor-workflow.

  1. Issue sempre, e dois planos. Sem issue, Claude cria uma (gh issue create). O plano vai na issue em no máximo 15 linhas (o quê, atividades, onde, como valida). O detalhado, que Claude segue: docs/planos/ com atividades A01, A02… e tabela de pontos de situação. O do usuário, no chat: no máximo um parágrafo.
  2. Desenvolvimento em TDD pelos agentes de implementação, em worktree/branch própria, nunca na main; uma atividade, um commit. Teste primeiro e vermelho na asserção (erro de compilação não conta), depois o código mínimo, depois a refatoração; a linha da atividade no plano registra a execução vermelha e a verde. Correção de bug começa pelo teste que a reproduz.
  3. Testes locais antes do PR: os recortes de "Commands" e o relatório da skill usage-monitor-test-report.
  4. PR aberto por Claude, dizendo em que plataformas foi testado, com gh pr merge --auto --merge na abertura: o ruleset da main exige o ci-ok e o GitHub mescla sozinho. Claude acompanha o CI e corrige o que ficar vermelho.
  5. Parada de segurança: cada run de CI vermelho, ou rodada de testes locais falhando depois de aberto o PR, é uma incidência. Até a 3ª, Claude ajusta e tenta de novo; na 4ª, para de desenvolver, não mexe mais na branch e devolve ao usuário com o diagnóstico de cada falha, o que tentou e o estado da branch. A conta é do node tools/ci/ci-incidents.mjs (runs vermelhos do ci.yml, tentativas reexecutadas inclusive; falha local registrada com --local "<o que falhou>"), nunca de memória: saída 3 é o limite.
  6. Merge e encerramento. O auto-merge mescla com o ci-ok verde e apaga a branch remota; nunca --admin. Claude apaga a branch local e a worktree, atualiza a main local (git pull --ff-only no checkout principal), comenta na issue os casos de teste criados em no máximo 20 linhas (o que cada um afirma, vermelho → verde, totais, cobertura do diff, o que ficou sem teste e por quê) e avisa o usuário.

Pergunta que só pede explicação é respondida no chat, fora do fluxo.

Respostas no chat têm no máximo 15 linhas — relatório, explicação, resultado de pesquisa ou dúvida. O que não cabe vai para a issue ou para docs/planos/.

Orquestração e agentes (#513)

A sessão principal é a orquestradora Neferpitou (agent do .claude/settings.json); modelo, effort e ferramentas de cada agente moram só em .claude/agents/, sempre por alias. Medições e decisões em agentes-por-tier-513-execucao.md.

  • Neferpitou faz plano, diagnóstico de falha, decisão e commit. Vermelho → verde e edição são dos agentes de implementação (backend-dev, frontend-dev, prototype-dev).
  • Delegação obrigatória (#515) — esta regra é o pedido explícito do usuário para usar os subagentes abaixo:
    • sempre test-runner para rodar gradlew.bat allTests/desktopTest, npm test, node --test, o relatório de testes, a cobertura do diff, gh run watch/--log-failed e ci-incidents.mjs; nunca rodá-los na sessão principal;
    • sempre explorer para varredura que abre mais de 3 arquivos ou pastas desconhecidas;
    • sempre o agente de implementação para código e teste; direto só ajuste pontual em arquivo conhecido
    • direto só busca pontual (um Grep, um arquivo conhecido): criar agente custa ~6k tokens de entrada.
  • Contra vazamento de contexto: nunca fork (desligado por CLAUDE_CODE_FORK_SUBAGENT=0); prompt mínimo (comando, caminhos, formato do retorno), nunca resumo da conversa; retorno de no máximo 20 linhas, nunca log cru; agente não cria agente.

Convenções de código

  • Nomes em inglês, comentários em português.
  • Evitar scope functions aninhadas (let, apply, run). Preferir fluxo explícito.
  • Commits: Conventional Commits em inglês + Co-Authored-By: Claude <nome do modelo> <noreply@anthropic.com> — o nome do modelo que gerou o commit (ex.: Claude Sonnet 5, Claude Opus 5), não um valor fixo: planos em docs/planos/ já registram qual modelo executou cada atividade, e o trailer do commit é a mesma informação em outro lugar.
  • Uma atividade, um commit. Cada unidade de trabalho fecha sozinha: código, teste e documentação da mesma decisão entram juntos. Commit que só compila com o próximo não é atômico, e commit que junta duas decisões impede reverter uma sem perder a outra.
  • Issue ou comentário criado no GitHub abre com 🤖 Escrito por Claude Code, a pedido de @<usuário>. O gh CLI fica autenticado com a conta pessoal do usuário, não com uma conta ou bot próprio de Claude — sem a linha, o texto aparece publicamente como se o usuário tivesse escrito, o que já causou confusão (issue #124). Vale para gh issue create/gh issue comment/gh api sobre issues/comments; não muda a autoria de commit, que já tem o trailer acima.
  • Trabalho com plano em docs/planos/ mantém ali a tabela de pontos de situação, uma linha por atividade, escrita no mesmo commit da atividade que ela descreve — em commit separado a linha pode existir sem a mudança e vice-versa, e o registro deixa de servir para auditoria. Cada entrada carrega o comando que rodou e o resultado, nunca a intenção.

Endpoints externos

APIEndpointAuth
AnthropicGET https://api.anthropic.com/api/oauth/usageAuthorization: Bearer {accessToken} do credentials.json + anthropic-beta: oauth-2025-04-20
Anthropic (renovação)POST https://platform.claude.com/v1/oauth/tokenCorpo JSON com grant_type, refresh_token, client_id e scope — sem client_id responde 400 Invalid request format
MiniMaxGET https://www.minimax.io/v1/token_plan/remainsAuthorization: Bearer {apiKey} lida de ~/.usage-monitor/api-keys.json
OpenCode GoGET https://opencode.ai/zen/go/v1/usageAuthorization: Bearer {apiKey} lida de ~/.usage-monitor/api-keys.json — a mesma chave do chat/completions do Zen
CursorGET https://cursor.com/api/usage-summary (rota não documentada)Cookie WorkosCursorSessionToken montado da sessão do editor em state.vscdb, lida em read-only e nunca persistida
Antigravity CLIagy --sandbox --print-timeout 30s --output-format json --print /usage (processo local)Sessão já autenticada do próprio CLI; o app nunca inicia login
Telegram (bot, opcional)https://api.telegram.org/bot{token}/getUpdates, sendMessage, deleteWebhookToken do bot em ~/.usage-monitor/telegram.json; long polling de 25 s com timeout estendido

Formato das respostas (unidades, campos, códigos de erro): docs/integrations.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.