Ingestão

1. O payload de statusline do Claude Code

Este é o caminho que não precisa de nenhum trabalho extra assim que o Claude Code está conectado. O Claude Code roda seu comando de statusline a cada renderização e escreve um objeto JSON descrevendo a sessão atual na entrada padrão desse comando. Quando esse objeto carrega um bloco de limite de taxa, openlimiter statusline o valida, escreve no cache, e renderiza os números atualizados na mesma chamada.

{
  "rate_limits": {
    "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
    "seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
  }
}

used_percentage é a fração da janela já usada, de 0 a 100. resets_at é um número epoch Unix em segundos, não uma string de data. Os dois nomes de campo e a codificação epoch vêm da documentação de statusline publicada pela Anthropic, não deste projeto, e cada janela é opcional de forma independente: um payload nomeando só uma delas é um meter completo, não um parcial.

• rate_limits aparece só para assinantes do Claude.ai num plano Pro ou Max, e só depois da primeira resposta de API de uma sessão. Um payload sem bloco rate_limits é o formato normal de uma conta gratuita ou de uma sessão que ainda não chamou a API, não um erro.
• Um reinício implausivelmente distante para sua própria janela, uma janela de cinco horas reiniciando dias depois, é descartado sozinho, em vez de confiado. A outra janela continua contando.

Qualquer outra coisa no objeto de sessão é ignorada. Uma janela que falha na validação é descartada e a outra janela continua contando.

2. Um documento manual no disco

Escreva manual.json dentro do diretório de estado e todo comando vai pegar esse arquivo. Veja configuração para onde esse diretório fica em cada plataforma.

{
  "version": 1,
  "meters": [
    { "name": "MONTHLY", "used_percent": 61.5, "reset_at": "2026-08-29T12:11:29.714Z" }
  ]
}

As regras que cada linha precisa satisfazer

• name é um identificador em maiúsculas, de até 32 caracteres, começando com uma letra.
• used_percent é um número de 0 a 100.
• reset_at é um instante ISO no futuro.
• Até dez meters são lidos. Linhas além da décima são ignoradas.
• Uma linha que quebra qualquer uma dessas regras é descartada, e as linhas restantes continuam contando. Nada é consertado.

Rode openlimiter snapshot --refresh para dobrar o arquivo dentro do cache.

3. O comando genérico ingest

Qualquer script ou agente pode entregar um documento ao OpenLimiter sem uma integração de provedor. O comando lê a entrada padrão, ou um documento inline passado com --payload.

echo '{"meters":[{"name":"AGENT_BUDGET","used_percent":12.5,"reset_at":"2026-08-09T13:11:30.141Z"}]}' | openlimiter ingest

openlimiter ingest --payload '{"meters":[{"name":"AGENT_BUDGET","used_percent":12.5,"reset_at":"2026-08-09T13:11:30.141Z"}]}'

Sem uma flag de provedor, o documento é tratado como um documento manual, então o snapshot resultante é rotulado com precisão manual. Com --provider <id>, o documento é entregue ao parser daquele connector e mantém os rótulos daquele connector.

openlimiter ingest --provider codex --payload '{"rate_limits":{"primary_window":{"used_percent":33,"reset_at":"2026-08-09T14:11:30.264Z"}}}'

Ids de provedor válidos são claude, openrouter, codex, antigravity, opencode, e manual. Um id desconhecido é um erro de uso e sai com 2.

O que acontece com os dados

Linhas ingeridas se fundem num único cache, sob o mesmo lock que todo outro escritor usa, então nada já em cache é perdido, e dois escritores observando provedores diferentes não conseguem apagar silenciosamente as linhas um do outro.

• Valores são validados contra o schema do snapshot antes de qualquer coisa ser escrita.
• Porcentagens ficam entre 0 e 100. Um valor fora desse intervalo não é ajustado, é descartado.
• Toda escrita passa por uma substituição atômica, então um leitor observa o conteúdo anterior ou o conteúdo novo, e nunca um arquivo parcial.
• A atualização é derivada de quando uma leitura foi observada e quando ela expira, então dados desatualizados são rotulados em vez de reaproveitados silenciosamente como atuais.

Nada sobrevive à validação? O comando reporta que nenhum meter limitado sobreviveu e sai com falha, em vez de escrever um placeholder.