ultronpx

Proxy local de compressão visual de contexto para Claude Code.

O ultronpx intercepta o tráfego do Claude Code para a Anthropic API e converte blocos densos de contexto (tool results grandes, histórico antigo) em imagens PNG — explorando o fato de que vision tokens custam por dimensão em pixels, não por quantidade de texto. Texto denso (~2 chars/token) renderizado na grade do ultronpx chega a ~6 chars por vision token: até ~3× mais barato por bloco, com ~45% de economia medida por bloco imageado em tráfego real.

A economia depende da densidade do workload: logs, JSONL, lockfiles e dados comprimem muito; prosa esparsa (~3,5 chars/token) não compensa e o gate a mantém como texto — por design, não por falha.

Rewrite completo e aprimorado do conceito do pxpipe, de teamchong.

Instalação e ativação

Requer Node.js ≥ 22 e uma licença ativa (vem com a compra do produto — a ativação usa o e-mail da compra).

npm install -g ultronpx
ultronpx setup

O ultronpx setup é o início guiado: num fluxo só ele cria o ~/.ultronpx/config.toml, ativa a licença (código de 6 dígitos enviado ao e-mail da compra), instala o proxy como serviço em background com restart automático (systemd de usuário no Linux/WSL; LaunchAgent no macOS), instala no seu shell um wrapper com fallback (proxy fora do ar = API direta, sem erro) e valida tudo com health check + doctor. Para desfazer: ultronpx setup --undo.

A licença renova sozinha no start (funciona offline por até 7 dias). A partir daí, abra um terminal novo e use o Claude Code normalmente. Cada request modificado é auditado em ~/.ultronpx/events.jsonl; veja a economia com ultronpx stats.

Um proxy serve todos os projetos. O ultronpx é por usuário/máquina (estado em ~/.ultronpx/, credenciais viajam por request): uma instância atende quantos terminais e projetos você tiver abertos — não suba um proxy por projeto.

Montagem manual (opcional): os passos individuais continuam existindo — ultronpx init, ultronpx activate, ultronpx doctor e ultronpx start (foreground, com export ANTHROPIC_BASE_URL=http://127.0.0.1:47821 no shell). O serviço e o wrapper que o setup instala estão documentados passo a passo no how-to docs/how-to/proxy-como-servico.md do repositório.

Diferenciais

1. Verbatim Guard — identificadores exatos (SHAs, UUIDs, IPs, stack traces) nunca viram pixel: vão para um sidecar textual. Secrets pinam o bloco inteiro como texto.
2. Adaptive Gate — o threshold de rentabilidade se recalibra com telemetria real (EWMA com bounds duros).
3. Economia auditável — cada request modificado registra o custo real E o contrafactual (via count_tokens, gratuito) num event store local; resumo em USD/BRL com ultronpx stats.
4. Fail-open sempre — qualquer erro interno degrada para passthrough byte-idêntico.
5. Local-first — nenhum byte das suas sessões sai da máquina exceto para api.anthropic.com; o serviço de licenças só vê o e-mail de compra.

Comandos

| Comando | O que faz | | --------------------------------- | --------------------------------------------------- | | ultronpx setup [--yes] [--undo] | Início guiado: config, licença, serviço, shell | | ultronpx init [--yes] [--force] | Setup interativo do config.toml | | ultronpx activate [--email] | Ativa a licença (código por e-mail) | | ultronpx deactivate | Remove a licença local | | ultronpx doctor [--deep] | Diagnóstico do ambiente (+ self-check de geometria) | | ultronpx start | Sobe o proxy em foreground (exige licença) | | ultronpx stats [--json] | Resumo de economia do event store local | | ultronpx import-pxpipe [src] | Importa eventos v1 do pxpipe |

Segurança: a API key vive apenas no ambiente do cliente — nunca no config.toml, nunca em log, nunca em pixel. O token de licença vive só em ~/.ultronpx/license.json.

Licença

Software proprietário, licenciado mediante compra — ver LICENSE. As versões ≤ 1.0.0 permanecem MIT (irrevogável).