ultronpx
EN Instalar
ultronpx

Proxy local · compressão visual de contexto · Claude Code

Contexto denso vira imagem.
Custo vira um terço.

O ultronpx intercepta o tráfego do Claude Code para a Anthropic API e converte blocos densos — tool results grandes, histórico antigo, system slab — em imagens PNG. Vision tokens custam por pixel, não por texto: ~3× mais barato nos blocos convertidos, com identificadores exatos protegidos e fail-open garantido. Open source, MIT.

Instalar em 2 minutos Ver no npm

npm i -g ultronpx · Node ≥ 22 · MIT · roda em 127.0.0.1

Vision tokens: ~3× mais barato Verbatim Guard: SHA nunca vira pixel Fail-open: passthrough byte-idêntico Local-first: nada sai da sua máquina Economia auditável em BRL Gate adaptativo com telemetria real Open source · MIT · npm Vision tokens: ~3× mais barato Verbatim Guard: SHA nunca vira pixel Fail-open: passthrough byte-idêntico Local-first: nada sai da sua máquina Economia auditável em BRL Gate adaptativo com telemetria real Open source · MIT · npm
O que é

Um proxy entre o Claude Code e a Anthropic API

Você aponta o ANTHROPIC_BASE_URL para 127.0.0.1:47821 e usa o Claude Code normalmente. O ultronpx decide, request a request, o que vale a pena renderizar como imagem — e audita cada centavo economizado.

O truque

Pixels custam menos que texto

Vision tokens custam pela dimensão da imagem em pixels, não pela quantidade de texto dentro dela. Texto denso consome ~1.9 chars/token; renderizado como PNG, chega a ~19 chars/vision-token. O ultronpx aplica isso onde mais pesa: tool results grandes, histórico antigo, system slab.

Zero mudança de fluxo

Transparente e fail-open

Nenhuma alteração no seu workflow: o Claude Code continua igual, só falando com o proxy local. Qualquer erro interno degrada para passthrough byte-idêntico — o pior caso do ultronpx é o comportamento que você já tinha sem ele.

Origem

Rewrite do conceito do pxpipe

Rewrite completo do conceito do pxpipe, de teamchong — com atribuição ao original. O que o rewrite adiciona: Verbatim Guard, gate adaptativo, economia auditável e local-first. Tem importer para quem vem do pxpipe.

Como funciona por dentro

Engenharia para comprimir sem quebrar nada

Comprimir contexto é fácil; comprimir sem corromper um SHA, vazar um secret ou travar seu fluxo é o problema real. Cada peça abaixo existe para isso — e todas estão na v1.0 do npm.

Verbatim Guard

destaque
  • SHAs · UUIDs · IPsIdentificadores exatos são extraídos para um sidecar textual antes do render — byte a byte, nunca viram pixel.
  • stack tracesCaminhos de arquivo e traces ficam legíveis por texto: o Claude cita a linha exata, não uma leitura aproximada.
  • secretsSecret detectado pina o bloco inteiro como texto — credencial nunca é renderizada em imagem.

Adaptive Gate

rentabilidade
  • threshold vivoO ponto em que compressão compensa se recalibra com telemetria real (EWMA com bounds duros) — não é um chute fixo.
  • model profilesPerfis por modelo + fidelity probe calibram o render para o modelo que você está usando.
  • render cacheBlocos repetidos entre requests não são re-renderizados — o custo do render é pago uma vez.

Economia auditável

em BRL
  • count_tokensCada request modificado registra o custo real e o contrafactual — medidos pelo endpoint gratuito da Anthropic, não estimados.
  • events.jsonlTrilha completa em ~/.ultronpx/events.jsonl: o que foi convertido, quanto custou, quanto teria custado.
  • dashboardDashboard local mostra o acumulado em BRL; ultronpx stats resume no terminal.

CLI

4 comandos
  • ultronpx initCria ~/.ultronpx/config.toml e mostra os passos de ativação.
  • ultronpx doctorValida porta, env, chave, conectividade e fontes de render antes de você depender do proxy.
  • ultronpx startSobe o proxy em 127.0.0.1:47821.
  • ultronpx statsEconomia acumulada, direto no terminal.

Request entra → Verbatim Guard separa o intocável → gate decide se compensa → render (ou passthrough) → economia registrada. Tudo em 127.0.0.1.

Modelo de segurança

Um proxy no caminho da sua API key precisa merecer confiança

O ultronpx fica entre o Claude Code e a Anthropic — posição que exige garantias explícitas, não promessas.

API key nunca é gravada

A chave vive só no ambiente do cliente. O proxy repassa o header para api.anthropic.com e nunca a escreve em config, log, evento de telemetria nem pixel.

Secrets pinam o bloco como texto

Se o Verbatim Guard detecta um secret no bloco, o bloco inteiro fica fora do render — credencial nunca vira imagem, nem por acidente.

Identificadores byte-exatos

SHAs, UUIDs, IPs e stack traces vão para um sidecar textual antes do render. O Claude cita o commit exato — não uma leitura visual aproximada dele.

Fail-open sempre

Qualquer erro interno degrada para passthrough byte-idêntico. O proxy nunca bloqueia seu fluxo nem corrompe um payload — o pior caso é o comportamento sem ultronpx.

Local-first, zero analytics

Escuta em 127.0.0.1:47821; o único destino de rede é api.anthropic.com — o mesmo do Claude Code sem proxy. Nenhum byte de telemetria sai da sua máquina.

Código aberto, auditável

MIT no npm: você pode ler exatamente o que passa pelo proxy. Cada request modificado deixa rastro em ~/.ultronpx/events.jsonl.

Como instalar

Em pé em 2 minutos

Requer Node.js ≥ 22. Instala global via npm (ou roda com npx sem instalar), valida o ambiente com o doctor e pronto — o Claude Code nem percebe que tem um proxy no caminho.

npm · 2 minutos

Instalar e ativar

Quatro comandos e uma variável de ambiente. A partir daí, use o Claude Code normalmente.

  1. Instale. Global via npm — ou npx ultronpx <cmd> sem instalar.
    # Node.js ≥ 22
npm install -g ultronpx
  2. Configure e valide. O init cria ~/.ultronpx/config.toml; o doctor confere porta, env, chave, conectividade e fontes de render.
    ultronpx init
ultronpx doctor
  3. Suba e aponte. O proxy escuta em 127.0.0.1:47821; o Claude Code passa a falar com ele.
    ultronpx start
export ANTHROPIC_BASE_URL=http://127.0.0.1:47821
Depois de rodar

Veja a economia

Cada request modificado registra custo real e contrafactual — medidos via count_tokens, não estimados.

  1. No terminal.
    ultronpx stats
# economia acumulada por período,
# blocos convertidos, taxa de conversão
  2. No dashboard local. Acumulado em BRL, request a request: o que custou vs o que teria custado sem compressão.
  3. Na trilha bruta.
    ~/.ultronpx/events.jsonl
# cada request modificado, auditável

Perguntas frequentes

Ficou alguma dúvida? Escreva para bruno@b2tech.io.

Quanto custa?
Nada. O ultronpx é open source sob licença MIT, publicado no npm. A economia aparece direto na sua fatura da Anthropic: cada request modificado registra o custo real e o contrafactual, e o dashboard local mostra o acumulado em BRL.
Como uma imagem fica mais barata que texto?
Vision tokens custam pela dimensão da imagem em pixels, não pela quantidade de texto dentro dela. Texto denso consome ~1.9 caracteres por token; o mesmo texto renderizado como PNG chega a ~19 caracteres por vision token — na prática, ~3× mais barato nos blocos convertidos. O ultronpx aplica isso aos blocos que mais pesam no contexto: tool results grandes, histórico antigo e system slab.
O Claude consegue ler o contexto virado imagem?
Sim — modelos Claude leem texto renderizado em imagem com alta fidelidade, e o ultronpx calibra o render por modelo (model profiles + fidelity probe). O que exige exatidão byte a byte nem vira pixel: o Verbatim Guard extrai SHAs, UUIDs, IPs e stack traces para um sidecar textual antes do render, e o gate adaptativo só converte um bloco quando a telemetria mostra que compensa.
E a minha API key?
Ela vive só no ambiente do cliente. O proxy repassa o header de autenticação para api.anthropic.com e nunca grava a chave no config, em log, em evento de telemetria nem em pixel. Blocos com secrets detectados são pinados como texto — credencial nunca vira imagem.
E se o proxy der erro no meio de um request?
Fail-open sempre: qualquer erro interno degrada para passthrough byte-idêntico — o request segue para a Anthropic exatamente como o Claude Code o emitiu. O pior caso do ultronpx é o comportamento que você já tinha sem ele; o proxy nunca bloqueia seu fluxo nem corrompe payloads.
Meus dados saem da minha máquina?
Não. O proxy escuta em 127.0.0.1:47821 e o único destino de rede é api.anthropic.com — o mesmo do Claude Code sem proxy. Zero analytics remoto: a telemetria de economia fica em ~/.ultronpx/events.jsonl, na sua máquina.
Qual a relação com o pxpipe?
O ultronpx é um rewrite completo do conceito do pxpipe, de teamchong — com atribuição e agradecimento ao projeto original. Os diferenciais do rewrite: Verbatim Guard para identificadores exatos, gate de rentabilidade adaptativo (EWMA com bounds duros), economia auditável via count_tokens, fail-open sempre e local-first. Há um importer para quem vem do pxpipe.
O que preciso para rodar?
Node.js ≥ 22 e npm. Instale com npm install -g ultronpx (ou use npx ultronpx sem instalar), rode ultronpx init e ultronpx doctor — o doctor valida porta, variáveis de ambiente, chave, conectividade e fontes de render antes de você apontar o ANTHROPIC_BASE_URL. Quer dominar Claude Code de ponta a ponta? Conheça o treinamento Claude Code Architect.
Comece agora

O contexto que você já paga,
pelo preço que ele deveria custar.

Um npm install, quatro comandos e uma variável de ambiente. A partir do próximo request, blocos densos viram PNG quando compensa — com identificadores intactos, fail-open garantido e cada centavo auditado em events.jsonl.

Instalar em 2 minutos Ver no npm

npm i -g ultronpx · Node ≥ 22 · MIT · local-first