▮token-guard npm GitHub ↗
economia de contexto · ide-agnóstico

A janela de contexto do seu agente não é lixeira.

O token-guard mede o custo real do repositório em tokens e barra as chamadas que estouram a janela — varredura sem escopo, leitura cega de arquivo grande, acesso a node_modules, dump de árvore no shell. Todo bloqueio devolve a alternativa barata, pronta para reexecutar: nunca um deny cego.

Instalar em 3 comandos Código-fonte

zero dependências · node 16+ · copilot · claude code · cursor · mcp

medidor de janela janela de referência: 200k tokens
AGUARDANDO Dispare uma chamada típica de agente e veja o veredito.

Vereditos reais do núcleo de decisão — as mesmas regras que rodam no seu harness.

o problema, em um número
26,7M caracteres

É quanto custa só a lista dos nomes dos arquivos de um monorepo de 215 mil — antes do agente ler uma linha de código. A janela é fixa; o repositório não. Por isso a seleção do que entra é a arquitetura, e é exatamente ela que este kit governa.

$ node token-audit.cjs /monorepo 215.112 arquivos · varridos em 3,2s CAMADA ARQUIVOS VOLUME JANELAS Tudo em disco 215.112 8,4 GB 10.512 Sem ruído 48.203 1,9 GB 2.380 Só código-fonte 31.877 1,1 GB 1.375 Só a lista de caminhos 26,7 MB 33 GANHO IMEDIATO — descartando build/deps: −166.909 arquivos (−77%) · custo: nenhum. É configuração.
o que entra na conta

Cinco regras. Cada bloqueio ensina.

broadScan

Varredura sem escopo devolve a lista de caminhos de todo o repo. O custo não é a busca — é a saída.

✗ glob "**/*"
✓ glob "**/*.java"
✓ glob com paths=["src/main"]

blindRead

Ler um arquivo grande inteiro para usar 20 linhas. Acima de 50KB, peça a faixa.

✗ Read arquivo de 200KB sem faixa
✓ Read com view_range [40, 90]
✓ arquivo pequeno inteiro

noisePath

node_modules, target, dist, .git são artefato: leia a fonte que os produz, nunca o artefato.

✗ Read node_modules/pkg/index.js
✓ allowlist para o caso legítimo

shellDump

O shell é a porta dos fundos: um comando despeja a árvore inteira e cada linha é faturada.

✗ Get-ChildItem -Recurse / ls -R / rg --files
✓ "| Select-Object -First 50"
✓ grep -rn TODO src/ (escopado)

bigResult (pós-execução)

Resultado legítimo que se revela gigante? Vira stub com preview; a versão integral vai para o disco e a dica junto.

✗ 200KB de matches na janela
✓ preview + .token-guard/results/ + "refaça com head_limit"
medido, não prometido

A economia tem número próprio.

437k tokeconomia líquida estimada no replay de 65 sessões REAIS (8.197 chamadas históricas)
85–205k tokpor sessão na simulação paramétrica (repo de 215 mil arquivos), conforme o agente aprende rápido ou repete o erro
28 / 103denies legítimos após a auditoria de falsos positivos do replay — cada bloqueio paga o próprio custo até ~94% de FP
0,15 mspor chamada no modo plugin in-process — quase todo o custo do modo comando é o runtime, não o guard

Fontes: bench/replay-transcripts.cjs (replay real) · bench/savings.cjs (simulação com premissas declaradas) · bench/latency.cjs (meça na sua máquina). Limitações declaradas na documentação.

cobertura real por ide

Onde bloqueia, onde orienta. Sem maquiagem.

HarnessMecanismoBloqueia?Cobre
Copilot CLI / Appextensão in-processsim4 regras + bigResult real
Claude CodePreToolUse + PostToolUse + UserPromptSubmitsim4 regras + contrato injetado + bigResult*
*substituição real no Claude Code ≥ 2.1.121
Cursor (IDE recente)preToolUse genérico + eventos nomeadossimtodas as 4 regras
VS Code / Windsurf / Zed / JetBrainsMCP serverorientatoken_audit · token_guard_check · mcp-cost
instalação

Três comandos. Sem npm install.

01npx @allansantos-dev/token-guard audit
02npx @allansantos-dev/token-guard init --target all --mode warn
03npx @allansantos-dev/token-guard test

Alvos: copilot · claude · cursor · mcp · repo (viaja no git). Emergência: TOKEN_GUARD=off.

princípios inegociáveis
Nunca um deny cego

Todo bloqueio devolve a alternativa barata, pronta para reexecutar. Um guard que só diz "não" transfere o problema para a pessoa.

Fail-open, sempre

Regra quebrada, payload hostil, config corrompida: tudo resulta em liberar. Um guard de economia jamais derruba a sessão que deveria baratear.

Zero dependências

Só Node stdlib — para rodar dentro de harness empacotado e em máquina corporativa sem npm install.

Declara o próprio custo

Latência medida e reproduzível por bench; economia com premissas declaradas e limitações honestas na documentação.