usage-monitor
AGENTS.md19 starsChanged 50 days agoMITView on GitHub
Todos os comandos usam gradlew.bat ou .\gradlew.bat no PowerShell: Importante: a task raiz test nao existe neste projeto KMP. Use allTests, desktopTest ou build. Chaves obrigatórias para MiniMax e DeepSeek: Ao habilitar qualquer uma das duas em Configurações -> APIs, a aplicação abre um campo mascarado para a API key. A chave é persistida em ~/.usage-monitor/api-keys.json, com escrita atômica e acesso restrito ao usuário. As variáveis de ambiente não são lidas pela aplicação. Arquitetura em tres camadas com dependencia unidirecional:…
- Reads credentials
- Commits and pushes
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.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
Files
AGENTS.md
Build commands (Windows)
Todos os comandos usam gradlew.bat ou .\gradlew.bat no PowerShell:
gradlew.bat run % roda a app desktop
gradlew.bat desktopJar % gera o JAR executavel
gradlew.bat build % compila + roda checks
gradlew.bat allTests % suite agregada de testes
gradlew.bat desktopTest % testes JVM/Desktop
gradlew.bat desktopTest --tests "com.usagemonitor.domain.*" % foco em domain/common tests
gradlew.bat desktopTest --tests "com.usagemonitor.presentation.*" % foco em ViewModel/common tests
gradlew.bat desktopTest --tests "com.usagemonitor.ui.*" % testes Compose Desktop
gradlew.bat createDistributable % gera distribuicao desktop
gradlew.bat packageInstaller % gera instalador NSIS se o NSIS estiver instalado
gradlew.bat clean % limpa artefatosImportante: a task raiz test nao existe neste projeto KMP. Use allTests, desktopTest ou build.
Chaves obrigatórias para MiniMax e DeepSeek:
Ao habilitar qualquer uma das duas em Configurações -> APIs, a aplicação abre um
campo mascarado para a API key. A chave é persistida em
~/.usage-monitor/api-keys.json, com escrita atômica e acesso restrito ao usuário.
As variáveis de ambiente não são lidas pela aplicação.
Architecture
Arquitetura em tres camadas com dependencia unidirecional: presentation -> domain <- data
| Source set | Platform | Contents |
commonMain | shared | domain + data (DTOs, mappers, repositories) + presentation/UI |
desktopMain | JVM only | data sources locais com java.io.File, AutoStartManager, Main.kt (arranque), AppGraph.kt (DI) e hosts de janela |
commonTest | shared | testes unitarios de domain, mappers e ViewModel |
desktopTest | JVM only | testes de componentes Compose Desktop |
installer | Windows only | scripts e assets do NSIS installer |
Domain layer constraints
- Zero imports de Ktor, Compose ou bibliotecas de infra. Apenas Kotlin puro (
ClockeInstantvêm dekotlin.time) +kotlinx.datetime(fuso, data local, período). - Entidades e contratos do domain nao conhecem HTTP, JSON, ficheiros locais ou UI.
LocalCredentialDataSourceeLocalCodexAuthDataSourceficam emdesktopMain, nao emcommonMain, porque leem ficheiros do utilizador.
DI and lifecycle
AppGraph.kt monta o grafo manualmente e AppViewModels.kt os view models; Main.kt so faz o arranque e compoe os hosts:
HttpClient(OkHttp) -> LocalCredentialDataSource + LocalCodexAuthDataSource + RemoteApiDataSource -> repositories -> use cases -> DashboardViewModel -> DashboardScreen
Regras importantes:
DashboardViewModelfaz polling a cada 10 minutos viawhile(true) + delay.- O scope usa
SupervisorJob, para que falha de uma API nao cancele as outras. - Tem de chamar
viewModel.onDestroy()ao fechar a janela. AppViewModels.shutdown()e o dono unico do encerramento (idempotente): para os view models e fechaHttpClient, bancos e registro de perfis na saida do app, noonDisposee no shutdown hook.
Architecture and size rules
Impostas por ArchitectureRulesTest (src/desktopTest/.../architecture/), que roda no allTests:
- Direcao das camadas por import:
domainnao importa Ktor, Compose,kotlinx.serialization,java.io,datanempresentation;datanao importapresentationnem Compose;presentationnao importadata. Precisando de algo dedata, o contrato sobe para o domain como porta (precedente:UsageExportEncoder). - Arquivo de producao <= 800 linhas; funcao <= 300. Nada de arquivo-deus nem composable-deus.
- As excecoes (
FILE_CEILINGS/FUNCTION_CEILINGS) tem teto exato e so encolhem; as duas estao vazias desde as issues #302-#309. Excecao nova nao entra na lista — divida o arquivo.
External API calls
Anthropic
- Endpoint atual:
GET https://api.anthropic.com/api/oauth/usage - Headers obrigatorios:
Authorization: Bearer <accessToken>anthropic-beta: oauth-2025-04-20User-Agent: claude-code/1.0.0
- O token vem de
~/.claude/.credentials.json->claudeAiOauth.accessToken - Se o token estiver perto de expirar,
LocalCredentialDataSourcetenta refresh emhttps://platform.claude.com/v1/oauth/token- O corpo precisa de
client_idescopealem degrant_type/refresh_token. Semclient_ido endpoint responde400 Invalid request formatcom qualquer refresh token - A regravacao do ficheiro e patch de JSON: ele tem nos que o app nao declara (
mcpOAuth,refreshTokenExpiresAt) e serializar o DTO de volta os apagava
- O corpo precisa de
- O payload retornado traz janelas de uso
five_houreseven_day
MiniMax
- Endpoint:
GET https://www.minimax.io/v1/token_plan/remains - Autenticacao: API key informada em Configurações -> APIs
- Nunca hardcode a chave
- A app hoje filtra quotas do modelo
MiniMax-M*
Codex
- Endpoint:
GET https://chatgpt.com/backend-api/codex/usage - Autenticacao:
- bearer token de
~/.codex/auth.json->tokens.access_token - cookie
cap_sidlido de~/.codex/cap_sid
- bearer token de
- O endpoint legado hoje deve ser tratado como fonte da quota 5h
- A quota semanal do Codex depende de uma segunda fonte ainda nao descoberta/validada
Persistence and preferences
- Preferencias locais usam
PreferencesSettings(Preferences.userRoot().node("com.usagemonitor")) - Chaves persistidas hoje:
enabledApisisDarklanguageautoStartwindowOpacityPercentuiScalePercent(escala global da interface; troca a densidade emAppTheme, nao a tipografia)teamUsageWindow*(geometria da janela de Sessoes do time)teamPresenceWindow*(geometria da janela de Conectados agora)
AutoStartManagerescreve emHKCU\Software\Microsoft\Windows\CurrentVersion\Run- A configuracao de time NAO vai para as preferencias. Vive em
~/.usage-monitor/team.json(LocalTeamSettingsDataSource), com escrita atomica erestrictToOwnerReadWrite: a chave do servidor e um segredo e as preferencias sao gravadas em claro no registro do Windows.
Team integration (server/)
Recurso opcional, desligado por default. Um servidor Node.js self-hosted pela empresa recebe os turnos indexados de cada maquina e devolve a visao agregada por conta Anthropic.
- Codigo do servidor em
server/— Express 4 + TypeScript ESM + SQLite (better-sqlite3).cd server && npm test. Detalhes de contrato e deploy Dokploy emserver/README.md. - Build file:
Dockerfile.dokployna raiz, contexto na raiz (mesmo padrao domontador-pacote). O.dockerignoreda raiz nega tudo e reinclui soserver/— sem isso obuild/do Gradle, com o runtime Java, entraria no contexto. Compose emdocker/docker-compose.yml(context: ..). - Chave de agrupamento: o
accountUuidda conta (UsageAccountKey.providerAccountId), sem oorganizationUuid— este e nulo em parte das instalacoes e usa-lo na chave quebraria o agrupamento entre maquinas da mesma conta. - Envio:
TeamSyncService(desktopMain), laco de 30s, independente da janela. Marcador de progresso emteam_sync_state(mesmousage-history.db), pela conexao compartilhada doLocalCliSessionDataSource. - Cada passada indexa antes de enviar (
ensureIndexFresh). O servico so ve turno que ja esta no indice: sem indexar na propria passada, a latencia do time seria a do laco de background (10min) e nao a dos 30s. Falha ao indexar entra no relatorio mas nao cancela o envio do que ja estava indexado. Abrir o modal chamarequestImmediateSync(), que antecipa uma passada sem reiniciar o laco. - Leitura:
TeamUsageViewModel, laco ao vivo de 5s, so com a janela aberta. - Presenca (servidor 0.4.0+):
POST /api/v1/presencecarimbateam_members.last_seen_ata cada passada de 30s, mesmo sem turno novo — e o que separa "app aberto" de "houve consumo". Rota propria porque e escrita, com a conta no corpo ex-admin-tokenrecusado; nenhuma coluna nova. Contra servidor anterior o 404 cai num ingest so-membro, lembrado por URL. A telaTeamPresenceViewModelclassifica online (90s de janela) e trabalhando agora (ACTIVE_SESSION_WINDOW_MILLIS), corrigindo o relogio pelo desvio que a propria resposta do heartbeat mede. - Precificacao: o servidor devolve tokens por
(deviceId, sessionId, model)e nao calcula custo. Quem aplicaModelPricingTablee o cliente, viaWindowedSessionAccumulator— a mesma classe que o indice local usa. - Nao trafega conteudo de prompt ou resposta, so metadados de uso
(
sessionId,messageId,ts,model, tokens,cwd,gitBranch,hostName). - O botao no card so aparece com a integracao ligada e a conta marcada em Configuracoes -> Integracao com time.
UI and presentation
- Nomes em ingles, comentarios em portugues.
- Evitar nested scope functions (
let,apply,run). Preferir fluxo explicito. - Componentes de UI devem ser stateless: dados por params, eventos por lambdas.
DashboardScreene o ponto stateful principal da UI.UiStateaceita sucesso parcial: se pelo menos uma API responder, a tela mostra os dados e lista erros das APIs que falharam.
Sistema visual
A app passou por uma refatoracao visual integral em agosto de 2026 (linguagem do OpenCode). O
detalhamento esta em CLAUDE.md, secao "Sistema visual"; o plano com as decisoes em
docs/planos/refatoracao-visual-opencode-execucao.md e a especificacao de aparencia em
docs/planos/prototipo-visual-opencode.html.
O essencial para nao quebrar nada:
- Tokens em
presentation/ui/theme/AppTheme.kt: superficies neutras, raio maximo 10dp, elevacao 0 para superficie de dados, espacamento emAppSpacing, motion 120/180/240. - Tipografia IBM Plex: mono em rotulo/numero/titulo, sans em texto corrido. Os TTFs vivem em
desktopMain/resources/fonts/e sao carregados porappFontFamilies(expect/actual). - Primitivas em
presentation/ui/components/App{Structure,Controls,States}.kt. Componente novo de UI deve sair delas — e primitiva construida e nao adotada nao conserta nada: a refatoracao de agosto fechou comAppWindowScaffoldeAppToolbarem zero telas, e cada tela continuava montando o proprio retangulo. O commit que cria e o que consome andam juntos. - Cor nunca informa sozinha:
AppStatusIndicatortraz ponto e palavra, e o tom sai deAppTone. - Acento e identidade de fonte, nao de valor. Numero fica na cor do texto e em
label*(mono):body*e sans e existe para texto corrido, e fonte proporcional nao alinha coluna. - Nada de Material cru na camada de UI:
TextButton,IconButton,OutlinedTextField,Checkbox,CardeHorizontalDividertrazem altura, raio e cor proprios.Slidere a excecao, e so pelos slotstrack/thumb— a semantica de progresso tem de continuar vindo dele. weightnao funciona dentro deFlowRow; acao com icone precisa decontentDescriptionna semantica; placeholder de campo precisa declearAndSetSemantics.- Tela mais alta exige subir a altura da cena do teste de componente, nao a do
Boxinterno.
Testing
commonTestcobre domain, mappers eDashboardViewModeldesktopTestcobre componentes Compose Desktop- A suite agregada atual passa com
gradlew.bat allTests
Installer (NSIS) - Debugging Lessons
Problema: installer travava em 99% e/ou na tela de finish
Causas raiz:
- LZMA compression -> thread deadlock (NSIS Bug #248)
- ExecWait -> bloqueia installer esperando a app fechar
Solucoes:
SetCompressor zlibno topo do.nsi- Evitar launch bloqueante no fluxo de sucesso do instalador
Sintomas:
- Freeze em 99% = forte sinal de problema de compressao LZMA
- Freeze na tela final = forte sinal de processo bloqueante
Diagnostico correto:
- Analisar imagens e logs com atencao; o ponto exato do freeze importa
- Pesquisar antes de chutar solucao
- Perguntar "onde exatamente trava?" antes de propor fix
Commit convention
Antes de commitar:
git config user.name "codex"
git config user.email "codex@openai.com"Depois de commitar, restaurar:
git config user.name "edilsonvilarinho"
git config user.email "edilson.vilarinho.messias@gmail.com"Nunca rodar git commit ou git push sem pedido explicito do utilizador.
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.

