@octasend/token-control

Monitora o consumo de tokens do Claude Code na sua máquina e avisa — por e-mail, WhatsApp, Telegram ou push — no momento em que o limite é resetado. Inclusive com a máquina desligada, porque o aviso é agendado no servidor.

Faz parte do módulo Token Control do OctaSend. Você precisa de uma conta com o módulo habilitado para gerar o token de máquina.

Instalação

Na tela Token Control → Máquinas do OctaSend, clique em Adicionar máquina. A tela mostra o comando pronto:

npx @octasend/token-control connect --token=tc_live_...

Isso registra a máquina, instala a inicialização automática e começa a monitorar.

Comandos

| Comando | O que faz | |---|---| | connect --token=<token> | Registra a máquina, instala o autostart e inicia o monitor | | start | Inicia o monitor (usado pelo autostart) | | status | Mostra a que servidor está conectado e quais pastas monitora | | logs | Mostra o registro recente do agente | | disconnect | Remove o autostart e a configuração local |

Opções do connect

| Opção | Efeito | |---|---| | --token=<token> | Obrigatório. Gerado na tela Máquinas | | --api-url=<url> | Servidor alternativo (padrão: produção do OctaSend) | | --claude-dir=<caminho> | Pasta do Claude Code a monitorar. Pode repetir, para contas isoladas em diretórios diferentes | | --no-autostart | Não instala a inicialização automática |

O que sai da sua máquina

Somente contadores: tokens de entrada, saída e cache, o modelo, o nome da pasta do projeto, o identificador da sessão e da conta, e o texto das mensagens de limite atingido do próprio Claude Code.

Nenhum prompt, resposta ou trecho de código sai da máquina — nem pela rede, nem para o log local. Essa garantia é fixada por teste automatizado.

Inicialização automática

| Sistema | Mecanismo | Verificado | |---|---|---| | Windows | Tarefa Agendada (schtasks), gatilho de logon | Não verificado nesta sessão de desenvolvimento (ambiente sandboxed sem permissão para schtasks /create) | | macOS | launchd (~/Library/LaunchAgents) | Não testado em máquina real | | Linux | systemd --user | Não testado em máquina real |

O gerador dos artefatos de instalação (o conteúdo exato de cada arquivo/comando) tem cobertura de teste automatizado para as três plataformas. A execução real do schtasks/systemctl/launchctl no sistema operacional, porém, não foi verificada em nenhuma delas nesta sessão de desenvolvimento. Se encontrar um problema ao instalar, abra uma issue no repositório.

Para instalar manualmente em vez de automaticamente, use --no-autostart e configure o mecanismo do seu sistema apontando para octasend-token-control start.

Requisitos

Node.js 20 ou superior.

Publicação (mantenedores)

cd token-control-agent
npm login                       # exige navegador/OTP; não roda em CI sem token
npm pack --dry-run              # confira que só dist/ e README.md entram
npm publish --access public     # --access public é obrigatório para escopo @

npm publish é praticamente irreversível: o npm restringe fortemente o unpublish, e o nome fica associado à organização. Confira o version antes.

Changelog

0.3.0

• Autostart não é mais instalado quando o agente roda via npx. O npx guarda o pacote num cache temporário que ele mesmo limpa e rotaciona; um autostart apontando para lá quebraria sozinho, em silêncio. Agora o agente detecta esse caso e explica como instalar de forma permanente (npm install -g @octasend/token-control@latest) em vez de criar uma tarefa condenada.
• A falha do agendador diz o motivo. Antes vinha só "saiu com codigo 1"; a mensagem real do sistema (por exemplo Acesso negado, quando falta terminal elevado) era descartada.
• O comando manual de instalação agora é colável. Ele era montado juntando os argumentos com espaço, o que destruía as aspas: o nome da tarefa chegava partido e o comando não rodava nem copiando à mão.

0.2.0

• O horário de reset e o tipo do limite passam a vir do objeto quotaLimits que o Claude Code grava no transcript, em vez de serem interpretados do texto do erro. Instante exato, sem inferir fuso.
• Versões do Claude Code que não gravam esse objeto continuam funcionando: o servidor volta a interpretar o texto.

0.1.0

• Primeira versão pública.