ultronpx
PT Install
ultronpx

Local proxy · visual context compression · Claude Code

ultronpx intercepts Claude Code traffic to the Anthropic API and converts dense blocks — large tool results, old history, the system slab — into PNG images. Vision tokens are priced per pixel, not per character: ~3× cheaper on converted blocks, with exact identifiers protected and fail-open guaranteed. Open source, MIT.

Install in 2 minutes View on npm

npm i -g ultronpx · Node ≥ 22 · MIT · runs on 127.0.0.1

Vision tokens: ~3× cheaper Verbatim Guard: SHAs never become pixels Fail-open: byte-identical passthrough Local-first: nothing leaves your machine Auditable savings, per request Adaptive gate driven by real telemetry Open source · MIT · npm Vision tokens: ~3× cheaper Verbatim Guard: SHAs never become pixels Fail-open: byte-identical passthrough Local-first: nothing leaves your machine Auditable savings, per request Adaptive gate driven by real telemetry Open source · MIT · npm
What it is

A proxy between Claude Code and the Anthropic API

You point ANTHROPIC_BASE_URL at 127.0.0.1:47821 and use Claude Code as usual. ultronpx decides, request by request, what is worth rendering as an image — and audits every cent saved.

The trick

Pixels cost less than text

Vision tokens are priced by the image's pixel dimensions, not by how much text is inside. Dense text runs at ~1.9 chars/token; rendered as a PNG, it reaches ~19 chars/vision-token. ultronpx applies this where it weighs the most: large tool results, old history, the system slab.

Zero workflow change

Transparent and fail-open

Nothing changes in your workflow: Claude Code stays the same, just talking to the local proxy. Any internal error degrades to byte-identical passthrough — ultronpx's worst case is the behavior you already had without it.

Origin

A rewrite of the pxpipe concept

A complete rewrite of the concept from pxpipe, by teamchong — with attribution to the original. What the rewrite adds: Verbatim Guard, an adaptive gate, auditable savings and local-first. Includes an importer for pxpipe users.

How it works inside

Engineering to compress without breaking anything

Compressing context is easy; compressing without corrupting a SHA, leaking a secret or blocking your flow is the real problem. Every piece below exists for that — and all of it ships in v1.0 on npm.

Verbatim Guard

highlight
  • SHAs · UUIDs · IPsExact identifiers are extracted into a textual sidecar before rendering — byte for byte, they never become pixels.
  • stack tracesFile paths and traces stay text-readable: Claude cites the exact line, not an approximate visual reading of it.
  • secretsA detected secret pins the entire block as text — credentials are never rendered into an image.

Adaptive Gate

profitability
  • live thresholdThe point where compression pays off recalibrates with real telemetry (EWMA with hard bounds) — not a fixed guess.
  • model profilesPer-model profiles + a fidelity probe calibrate rendering for the model you are actually using.
  • render cacheBlocks repeated across requests are not re-rendered — the render cost is paid once.

Auditable savings

per request
  • count_tokensEvery modified request records the real cost and the counterfactual — measured via Anthropic's free endpoint, not estimated.
  • events.jsonlA full trail in ~/.ultronpx/events.jsonl: what was converted, what it cost, what it would have cost.
  • dashboardA local dashboard shows the running total; ultronpx stats summarizes it in the terminal.

CLI

4 commands
  • ultronpx initCreates ~/.ultronpx/config.toml and shows the activation steps.
  • ultronpx doctorValidates port, env, key, connectivity and render fonts before you depend on the proxy.
  • ultronpx startStarts the proxy on 127.0.0.1:47821.
  • ultronpx statsAccumulated savings, right in the terminal.

Request comes in → Verbatim Guard splits out the untouchable → the gate decides if it pays off → render (or passthrough) → savings recorded. All on 127.0.0.1.

Security model

A proxy in the path of your API key has to earn trust

ultronpx sits between Claude Code and Anthropic — a position that demands explicit guarantees, not promises.

API key is never persisted

The key lives only in the client environment. The proxy forwards the header to api.anthropic.com and never writes it to config, logs, telemetry events or pixels.

Secrets pin the block as text

If the Verbatim Guard detects a secret in a block, the whole block is excluded from rendering — credentials never become an image, not even by accident.

Byte-exact identifiers

SHAs, UUIDs, IPs and stack traces go to a textual sidecar before rendering. Claude cites the exact commit — not an approximate visual reading of it.

Fail-open, always

Any internal error degrades to byte-identical passthrough. The proxy never blocks your flow or corrupts a payload — the worst case is the behavior without ultronpx.

Local-first, zero analytics

Listens on 127.0.0.1:47821; the only network destination is api.anthropic.com — the same as Claude Code without a proxy. Not a single telemetry byte leaves your machine.

Open, auditable code

MIT on npm: you can read exactly what passes through the proxy. Every modified request leaves a trail in ~/.ultronpx/events.jsonl.

How to install

Up and running in 2 minutes

Requires Node.js ≥ 22. Install globally via npm (or run with npx without installing), validate the environment with doctor and that's it — Claude Code won't even notice there's a proxy in the path.

npm · 2 minutes

Install and activate

Four commands and one environment variable. From there, use Claude Code as usual.

  1. Install. Globally via npm — or npx ultronpx <cmd> without installing.
    # Node.js ≥ 22
npm install -g ultronpx
  2. Configure and validate. init creates ~/.ultronpx/config.toml; doctor checks port, env, key, connectivity and render fonts.
    ultronpx init
ultronpx doctor
  3. Start and point. The proxy listens on 127.0.0.1:47821; Claude Code starts talking to it.
    ultronpx start
export ANTHROPIC_BASE_URL=http://127.0.0.1:47821
After it runs

See the savings

Every modified request records real and counterfactual cost — measured via count_tokens, not estimated.

  1. In the terminal.
    ultronpx stats
# accumulated savings per period,
# converted blocks, conversion rate
  2. In the local dashboard. Running total, request by request: what it cost vs what it would have cost without compression.
  3. In the raw trail.
    ~/.ultronpx/events.jsonl
# every modified request, auditable

Frequently asked questions

Still unsure about something? Write to bruno@b2tech.io.

How much does it cost?
Nothing. ultronpx is open source under the MIT license, published on npm. The savings show up directly on your Anthropic bill: every modified request records both the real cost and the counterfactual, and the local dashboard shows the running total.
How can an image be cheaper than text?
Vision tokens are priced by the image's pixel dimensions, not by how much text is inside it. Dense text runs at ~1.9 characters per token; the same text rendered as a PNG reaches ~19 characters per vision token — in practice, ~3× cheaper on converted blocks. ultronpx applies this to the blocks that weigh the most in your context: large tool results, old history and the system slab.
Can Claude actually read context turned into an image?
Yes — Claude models read text rendered in images with high fidelity, and ultronpx calibrates rendering per model (model profiles + fidelity probe). Anything that requires byte-exact accuracy never becomes a pixel: the Verbatim Guard extracts SHAs, UUIDs, IPs and stack traces into a textual sidecar before rendering, and the adaptive gate only converts a block when telemetry shows it pays off.
What about my API key?
It lives only in the client environment. The proxy forwards the auth header to api.anthropic.com and never writes the key to config, logs, telemetry events or pixels. Blocks with detected secrets are pinned as text — credentials never become an image.
What if the proxy fails mid-request?
Fail-open, always: any internal error degrades to byte-identical passthrough — the request goes to Anthropic exactly as Claude Code emitted it. ultronpx's worst case is the behavior you already had without it; the proxy never blocks your flow or corrupts payloads.
Does any data leave my machine?
No. The proxy listens on 127.0.0.1:47821 and the only network destination is api.anthropic.com — the same as Claude Code without a proxy. Zero remote analytics: savings telemetry stays in ~/.ultronpx/events.jsonl, on your machine.
How does it relate to pxpipe?
ultronpx is a complete rewrite of the concept from pxpipe, by teamchong — with attribution and thanks to the original project. What the rewrite adds: Verbatim Guard for exact identifiers, an adaptive profitability gate (EWMA with hard bounds), auditable savings via count_tokens, fail-open always and local-first. There is an importer for anyone coming from pxpipe.
What do I need to run it?
Node.js ≥ 22 and npm. Install with npm install -g ultronpx (or use npx ultronpx without installing), run ultronpx init and ultronpx doctor — doctor validates port, environment variables, key, connectivity and render fonts before you point ANTHROPIC_BASE_URL at the proxy. Want to master Claude Code end to end? Check out the Claude Code Architect training (in Portuguese).
Start now

The context you already pay for,
at the price it should cost.

One npm install, four commands and one environment variable. From the next request on, dense blocks become PNGs when it pays off — with identifiers intact, fail-open guaranteed and every cent audited in events.jsonl.

Install in 2 minutes View on npm

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