The star count should be read together with the date of checking: the parameter is dynamic and moves fast.

Why an image can be cheaper than text

Ordinary text goes through a tokeniser first, and dense machine text - code, JSON, logs - burns tokens especially greedily. An image is counted differently: the provider prices it by geometry and vision-input rules, not by the number of characters drawn inside it.

pxpipe exploits exactly that difference. It packs monospaced text onto a PNG page as tightly as possible and tries to fit more source characters into one vision token than ordinary tokenisation would allow.

The README gives an example of roughly 48 thousand characters of system prompt and tool documentation: about 25 thousand tokens as text against roughly 2.7 thousand vision tokens for one particular render profile. That is the project's example, not a universal coefficient for any text and any model.

The same mechanism has a second consequence, about capacity rather than money. By the project's own measurements the same context window holds noticeably more source text through images: for Fable 5 that is roughly 19 million characters instead of four, a factor of 4.8, and for Gemini 3.6 Flash about 21 million, a factor of 5.3. The density there is measured from a live render when the chart is generated, not typed in by hand.

An important caveat: the gain only appears on sufficiently dense text. The project itself states plainly that on sparse prose - around 3.5 characters per token - the conversion loses its economic sense. That is why a profitability gate runs before rendering.

How it works inside

The mechanism is split into several parts in the source, and this is worth noting separately: the architecture described in the README really is traceable in the code rather than existing only in the description.

Parsing the request is the job of src/core/transform.ts - it classifies content and decides which blocks may be rendered and which must stay byte-exact. Turning text into PNG is handled by src/core/render.ts, with geometry and font profiles for a specific model. And src/core/baseline.ts computes the text counterfactual and compares it with the actual cost of the transformed request. The Node proxy itself accepts the request locally, transforms the suitable parts and passes it on.

What gets compressed, and what stays text

In the code there are separate thresholds for tool results, a limit on images per result, a limit on the total weight of images, and a bucket chosen by content type.

But the project deliberately does not try to turn everything into pictures. What stays as text: the current user request, the most recent turns, open or improperly closed tool-call states, dynamic system blocks that change from turn to turn, content too small or economically pointless to convert, and content for models outside the allowlist. And separately - the model's own output: pxpipe does not compress that at all.

The practical sense is simple: savings come from the old and bulky, while the hot part of the conversation stays ordinary text.

Installation in a minute

You need Node.js 20.19 or newer. The shortest route:

By default the proxy comes up here:

After that Claude Code is routed through it with a single variable:

A dashboard is available at the same local address: it shows conversions, saved tokens, the model profile, and lets you switch imaging off. The advantage of the approach is that a first test requires no changes to the agent's code and no MCP of your own - pxpipe sits at the network layer in front of the API.

The warp mode and offline export

If you would rather not touch ANTHROPIC_BASE_URL, there is a separate mode:

The README lists other commands behind warp too - cursor-agent, codex, shell aliases. For additional endpoints the route is set by hand:

Just do not confuse the existence of a route with universal compatibility: the fact that traffic can be directed does not mean every model reads dense PNGs well. Render profiles and the model allowlist are not a formality here.

Export deserves a separate mention - rendering files or text into PNG with no proxy and no agent attached at all:

The command creates a directory with page-*.png pages, a factsheet.txt, a manifest.json description and prompt.txt. The resulting set of dense pages can be loaded by hand into any client that reads images.

What happens to prompt caching

Here is where the project turns out smarter than you might expect. Simply turning the system prompt into a picture would break the prompt cache and destroy part of the savings - because a warm cache makes a large text prefix rather cheap.

The documentation describes the key invariant: pxpipe does not create a new cache boundary arbitrarily but moves the existing cache_control marker onto the last image page produced from the same logically stable content.

Dynamic blocks - environment, git status, runtime reminders - are separated from the stable slab so the picture does not change on every turn and does not destroy the cache key. In effect the project understands the difference between "fewer tokens" and "a cheaper request", and the profitability gate accounts for the cost of a possible cache burn too.

How the savings are calculated

The authors deliberately separate the provider's ordinary cache discount from pxpipe's own savings. For the Anthropic path every eligible request gets a baseline through /count_tokens for the original uncompressed body, while the actual usage figures come from the real transformed request. Both numbers are written to the ~/.pxpipe/events.jsonl log.

With a warm cache both sides are counted warm; with a cold one, cold. Negative rows are not hidden, and if the baseline probe turned out unreliable, the row is excluded from the total. Version 0.13.0 added a command for analysing the accumulated log without a running dashboard:

What the measurements actually show

The README claims a 59-70 percent reduction of the end-to-end bill on observed production traces of Claude Code. It is important not to turn that figure into a promise.

Where the boundary of trust lies. The repository contains the measurement harnesses, the committed results, the source code of the measurements and an honest description of the failed tests - all of which raises confidence in the method. But there is still no independent external validation of the claimed 59-70 percent, so the correct phrasing is "measured by the authors on their traffic" rather than guaranteed savings for any user.

The main drawback: this is lossy compression

This is the most important part of the whole story. The model does not receive the source characters - it receives visual representations. Similar glyphs can be read wrongly, and the error need not look like a recognition error: the model is capable of confidently returning a plausible but incorrect string.

A telling measurement from the repository - exact reading of 12-character hexadecimal strings on a dense render:

The conclusion from that table is simple: a PNG cannot be treated as reliable byte storage. Hashes, secrets, identifiers, paths with critical characters, checksums, API keys - anything where every character matters must not be handed over through an image alone.

The risk is partly mitigated: the factsheet keeps a limited number of recognised precision-critical fragments as text, while recent state and open tool calls stay in their original form. But the README admits plainly that there is no universal guard against verbatim distortion yet. The authors also document a real failure: the model once misremembered a person's name from history that had gone into an image and confidently produced the wrong one.

Why you cannot say "any vision model is supported"

pxpipe uses different render profiles for different models: geometry, font size, the number of columns, history depth and the maximum number of images all depend on the specific model. The code includes, for instance, the bitmap Spleen 5×8 and several JetBrains Mono profiles, and the README stresses that the exact model identifier matters.

The logic runs like this. A strong reader lets images be packed more aggressively and yields a high number of characters per vision token. A weak one needs larger glyphs, so the image cost rises and the savings fall. For an unknown model outside the allowlist pxpipe prefers to pass the request through unchanged, byte for byte. That is the right engineering tradeoff: the quality of reading matters more than the technical ability to send a picture.

Security: the proxy sees your prompts and keys

The security documentation warns about this plainly: pxpipe handles API credentials and may see confidential prompts and tool results. The project's recommendations are these: keep the server on the local address 127.0.0.1; do not expose the proxy publicly without an authenticated encrypted reverse proxy; for the Cloudflare Workers variant with provider credentials use PXPIPE_WORKER_SECRET; do not enable debug capture of errors in production, since it may contain prompts and keys; and remember that event logs, dumped PNGs and export artifacts may themselves contain sensitive data.

The practical rule: treat pxpipe as a component inside your trust boundary. If you are not prepared to let a process see the original prompt and the API traffic, this architectural option is not for you.

When it is sensible, and when to stay on text

pxpipe fits especially well in long coding sessions, where the system block, the tools and the old history keep growing and being resent. Large logs and JSON sit well too - dense tool results pack into PNG efficiently. The more expensive the large uncached input, the more noticeable the effect. And a separate value is measurability: the dashboard and the event log let you check your own workload instead of trusting a headline.

Testing is worth doing properly: bring the proxy up locally, work through several real sessions rather than one synthetic prompt, look at pxpipe stats, check exact-reading errors separately on your typical code and logs, and compare not only input tokens but the actual cost, the latency and the quality of the agent's decisions.

In conclusion: a clever experiment, not free magic

pxpipe is interesting not because it is one more way to save tokens but because it attacks the problem from another side. Most tools reduce context semantically: they delete lines, make summaries, build syntax trees, truncate output. pxpipe keeps far more of the original material but changes how it is encoded.

There are three strengths: substantial potential savings on very dense context; a transparent local proxy that requires no change to the agent itself; and a rare honesty for an experimental project - the failed tests and limitations are documented.

There is one fundamental drawback, and it is not going away: an image of text is not text. As long as vision models sometimes confuse characters, pxpipe cannot be considered lossless compression.

Hence the way to use it: not "switch it on and forget", but measure your own sessions. For large Claude Code workloads the gain may prove very serious. For tasks where every character must be exact, ordinary text remains safer. The result has to be judged on three metrics at once: tokens, money and correctness.

Sources

The material was checked against the teamchong/pxpipe repository itself: the documentation, the sources and the measurement material inside it. Third-party retellings were not used as a source of facts. Checked on 11 August 2026; the star count and current version are dynamic parameters and will change over time. Supplemented on 15 August 2026 against a fresh clone: the version in the main branch raised to the current one, and the context-capacity gain and the size of the later trace added; the verbatim-accuracy and dense-corpus cost tables were checked row by row and held.

• pxpipe - the repository and README
• CHANGELOG.md - versions and changes
• package.json - version, Node requirement, metadata
• LICENSE - MIT
• SECURITY.md - deployment security
• CACHING_AND_SAVINGS.md - the prompt cache and the savings maths
• FINDINGS.md - research, failed experiments and model evaluations
• src/core/transform.ts - request transformation
• src/core/render.ts - the PNG renderer and font profiles
• src/core/baseline.ts - cache-aware savings calculations