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
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- orchestrateSkill
- usage-monitor-commit-pushSkill
- usage-monitor-designSkill
- usage-monitor-nsis-installerSkill
- usage-monitor-release-betaSkill
- usage-monitor-releaseSkill
- usage-monitor-release-videoSkill
- usage-monitor-social-videoSkill
- usage-monitor-test-reportSkill
- usage-monitor-token-cleanupSkill
- usage-monitor-visual-optionsSkill
- usage-monitor-workflowSkill
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
- Very specific: line 72
Use cases usam operator fun invoke() — chamados como useCase().
≈ “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.
Files
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 cleanServidor 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:3000Arquitetura
KMP Desktop (JVM único alvo). Código organizado em três camadas com dependências unidirecionais: presentation → domain ← data.
Source sets
| Source set | Conteúdo |
commonMain | domain + data (exceto leitura de ficheiros) + presentation/UI |
desktopMain | LocalCredentialDataSource (usa java.io.File) + Main.kt (arranque e composição dos hosts) + AppGraph.kt (DI) + hosts de janela |
commonTest | Testes unitários de domain, mappers e ViewModel |
desktopTest | Testes de componente Compose (runDesktopComposeUiTest) |
Camada domain (commonMain/domain/)
Núcleo puro — zero imports de Ktor, Compose ou bibliotecas externas.
QuotaInfo: entidade compercentageUsederemainingcalculados.UsageUnitdiferenciaTOKENS,REQUESTS(MiniMax),PERCENTAGE(Anthropic/Codex) eCURRENCY_USD(saldo DeepSeek).currencyCode(default"USD") diz em que moeda os valores monetários estão. Não crie valores novos emUsageUnit: oswhenexaustivos 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 deQuotaInfopor API.- Interfaces
AnthropicRepository/MiniMaxRepository: o domain define o contrato;dataimplementa. - Use cases usam
operator fun invoke()— chamados comouseCase().
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 usamsuspendRunCatching { }, que relançaCancellationException(runCatchingo 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_idescope(sem eles,400 Invalid request format); checar status HTTP antes de desserializar; regravar o ficheiro por patch deJsonObject, nunca pelo DTO (apagariamcpOAuth/refreshTokenExpiresAt). User-Agent: claude-code/1.0.0no/api/oauth/usageé obrigatório.- Créditos Anthropic:
extra_usageprimário,spendsecundá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.mscapientra nomodules(...)só no build Windows (jlink de outro SO falharia). - Tipo com credencial nunca usa o
toStringgerado:data classsobrescreve comredactedSecret, ou é classe comum (CursorSessionCredentials).ArchitectureRulesTestcobra 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 semprofileId; id das extras começa comcodex-. Cor/emoji por conta leemanthropicProfileId, nuncaprofileIdcru. - Índice CLI (#381):
message.idrepetido funde porMAX(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 emcodex_cli_index_meta. - Acesso web local (#388) e bot Telegram (#387): opt-in, segredo em
~/.usage-monitor/{web-access,telegram}.json, tipos semdata class. Servidor sóGET, token em toda rota (MessageDigest.isEqual); bot começa do agora e só atende conversa pareada. Saem doUsageSnapshot— 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 interfaceLoading/Success(data)/Error(message); falha parcial emiteSuccesscom dados parciais.onDestroy()ao fechar janela; escopos comSupervisorJob.DashboardViewModel: coleta adaptativa por alvo (60 s com sessão ativa, 5 min sem, backoff em 429), publicação incremental por alvo sobstateMutex, 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"), labelBRT. 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 nocliBusy, que é global e aceleraria todas as fontes. - Nunca valor novo em
CliSessionRangepara 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 usagroupCostMicroscom a parte longa, nuncacostMicros; sufixo depois do prefixo é só data de 8 dígitos. nullé "não medido", zero é "medido e sem valor" — não colapsar.INDEX_SCHEMA_VERSIONvive emcli_index_meta, não emPRAGMA user_version; coluna nova emcli_sessionsprecisa 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 owaitForIdle).
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. SemMsi; oupgradeUuidfica para remover instalações MSI antigas. jpackage não faz cross-compile. - Auto-start: entrada com
--autostart; o nome do valorRunnão muda. Agendador de Tarefas foi medido e recusado. - Segunda instância nunca sai calada: pedido em
~/.usage-monitor/focus.request, atendido porfocusHud(a janela da HUD).activateWindowalternaalwaysOnTopfalse → true → anterior. - Atualização automática: SHA-256 contra o
digestda 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ó emAppVersionComparison.kt(SemVer:X.Y.Z-beta.N < X.Y.Z). - Canal beta (#355): tag
vX.Y.Z-beta.Npublicada como prerelease e nuncalatest— é isso que protege quem não optou. Opt-inreceiveBetaUpdates; 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 skillusage-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 debuild/. - Diagnóstico (#416):
app.logrecebe falha não tratada (registro noCrashHandler, nunca handler por escopo),recordFailure,stderre EDT parado;--diagnosticsempacota por lista fechada, sem janela. - Linha de comando (#418):
parseCommandLineé o dono doargv; 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 aoConfigApplier(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-monitorsó peloAppDataDirectory(file= dados/instância,installationFile= o que NSIS/updater leem em caminho fixo); configurada uma vez nomain(). Fora da raiz padrão: atualização e autostart desligados. - Ajuda: passos citam o rótulo real do controle; GIF animado pelo
Codecdo Skia com cópia imutável dos bytes; laço de quadros emdesktopMain;gradlew.bat generateHelpMediaregenera.
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/setShapesó emHudWindow.kteDesktopWindowFrame.kt— outro arquivo falha. - Direção das camadas por import:
domainnão importa Ktor, Compose,kotlinx.serialization,java.io,datanempresentation;datanão importapresentationnem Compose;presentationnão importadata. Quando a apresentação precisa de algo dedata, o contrato sobe para o domain como porta edatao 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.PTem produção — texto novo vai porlocalized(language, pt, en)ou objeto de rótulos (CommonLabels,CliSessionsLabels…); migrar um arquivo baixa o teto. Classificação de fonte é predicado do domain comwhenexaustivo (ApiSourceClassification.kt), nunca conjunto literal repetido. - Sem exceções:
FILE_CEILINGS/FUNCTION_CEILINGSestão vazias e exceção nova não entra — divida o arquivo (histórico emdocs/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, semorganizationUuid. - Chave de time é por pessoa; se amarra a conta por
POST /v1/claimou ingest. NenhumGETreivindica.labelcom e-mail é portão (TEAM_KEY_LABEL_MATCH, nascestrict). TEAM_ADMIN_TOKENlê e é o portão único dosDELETE(requireAdminTokennã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 emPreferencesSettings. - Vários times (#547): agregado
TeamIntegrations, uma conta em no máximo um time,enabledsó no agregado;team.jsonv2 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 aplicaModelPricingTable.tools/ci/check-pricing-parity.mjscompara 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, semsession_id/cwdcomo 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ência | Quem vence | O que fazer |
| Compose × design system | design system | corrigir o Compose |
| Compose × protótipo (layout de tela) | protótipo | corrigir o Compose |
| Design system × protótipo | design system | corrigir o protótipo, no mesmo commit |
| Design system tecnicamente errado | o Kotlin | corrigir 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.AppMotionPolicynasceStatic; só oMainpassa 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 porStateFlow; nome na trilha é fixo (diagnosticName). Diálogo interno éAppDialog, nuncaAlertDialog. - Tipografia: Plex Mono em
label*/title*/headline*/display*, Plex Sans embody*; carga do classpath, nuncacomposeResources. Número élabel*. - Primitivas são stateless. Aba × segmentado × chip têm papéis distintos. Cor nunca informa sozinha. Acento é
identidade de fonte.
AppSwitchligado é 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 — jobchangesrecorta por path, jobs em paralelo só do que mudou,ci-oké o check único (pulado conta como sucesso), exigido pelo rulesetmain(#496: só por PR, sem force-push, bypass de admin só por PR);release-linux.ymlsó por tag, versão vem da tag (-PappVersion), sem commit de bump. Cache do Gradle pelagradle/actions/setup-gradle, gravado só namain— tag e CodeQL só leem. - CI roda com
-PtestForks=3; localmente 1. Com forks,extractSkikoNativeroda antes. Verde local e vermelho no CI em teste de UI: olhe o~/.skikoantes do teste. - Teste de tela usa
ScreenTestTheme(Reduced); teste de primitiva que anima usaAppTheme. 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). delayemrunTesté tempo virtual: espera de estado de view model usayield()+Thread.sleep(pauseForBackgroundWork).awaitSettledStateespera a coleta inteira (refreshingTargetsvazio), não o primeiroSuccess.- Cobertura opt-in por
-Pcoverage; meta de 95% de linhas (Kotlin e servidor) com catraca: piso emcoverageLineFloorPercent(koverVerifyno CI) ethresholds.linesdo vitest, só sobe, no commit que o eleva (planocobertura-95-execucao.md). - Cobertura do diff (#496,
tools/ci/diff-coverage.mjs): linhas de produção que o PR altera, piso 90%, nos jobsdesktop-windows(Kover) eserver(lcovonly). Nasce informativa (aviso, fora doci-ok) — o #495 mediu 60%; vira bloqueante pelo critério do planofluxo-automatizado-496-execucao.md. - Dependabot (#496): auto-merge só de minor/patch de
gradle/npm_and_yarn(dependabot-automerge.yml); major egithub_actionscontinuam manuais. - Job
test-report(skillusage-monitor-test-report): HTML de testes e cobertura no artefatotest-reporta cada run com a suíte do desktop; informativo, fora doci-ok. - Classe
opencom todo métodoopensobrescrito 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.
- 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. - 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. - Testes locais antes do PR: os recortes de "Commands" e o relatório da skill
usage-monitor-test-report. - PR aberto por Claude, dizendo em que plataformas foi testado, com
gh pr merge --auto --mergena abertura: o ruleset damainexige oci-oke o GitHub mescla sozinho. Claude acompanha o CI e corrige o que ficar vermelho. - 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 doci.yml, tentativas reexecutadas inclusive; falha local registrada com--local "<o que falhou>"), nunca de memória: saída 3 é o limite. - Merge e encerramento. O auto-merge mescla com o
ci-okverde e apaga a branch remota; nunca--admin. Claude apaga a branch local e a worktree, atualiza amainlocal (git pull --ff-onlyno 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-runnerpara rodargradlew.bat allTests/desktopTest,npm test,node --test, o relatório de testes, a cobertura do diff,gh run watch/--log-failedeci-incidents.mjs; nunca rodá-los na sessão principal; - sempre
explorerpara 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.
- sempre
- 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 emdocs/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>. OghCLI 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 paragh issue create/gh issue comment/gh apisobreissues/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
| API | Endpoint | Auth |
| Anthropic | GET https://api.anthropic.com/api/oauth/usage | Authorization: Bearer {accessToken} do credentials.json + anthropic-beta: oauth-2025-04-20 |
| Anthropic (renovação) | POST https://platform.claude.com/v1/oauth/token | Corpo JSON com grant_type, refresh_token, client_id e scope — sem client_id responde 400 Invalid request format |
| MiniMax | GET https://www.minimax.io/v1/token_plan/remains | Authorization: Bearer {apiKey} lida de ~/.usage-monitor/api-keys.json |
| OpenCode Go | GET https://opencode.ai/zen/go/v1/usage | Authorization: Bearer {apiKey} lida de ~/.usage-monitor/api-keys.json — a mesma chave do chat/completions do Zen |
| Cursor | GET 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 CLI | agy --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, deleteWebhook | Token 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.
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
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.

