pxpipe: A local proxy that trades text tokens for image tokens in Claude Code

What pxpipe targets and who should care

This is not a general-purpose compression tool. It is built for Claude Code and similar agents that send the same bulky context repeatedly. If your workload is sparse prose, the README says the math loses money, because prose already packs around 3.5 characters per token. The project includes a profitability gate calibrated on 391 production rows that only images content where the token math wins. So the target user is someone with token-dense, repetitive context, not someone writing documentation or chat transcripts.

The mechanism: request rewriting, not output compression

The proxy also tracks what it converts. The dashboard at http://127.0.0.1:47821/ shows tokens saved, every text-to-image conversion side by side, a kill switch, and live model chips. The events log in ~/.pxpipe/events.jsonl records per-request token counts against the counterfactual. This measurement layer is a practical feature: you can see exactly how much you saved on your own traffic, rather than trusting a marketing number.

Getting it running: proxy, warp, and offline export

If you do not want to run the proxy at all, the export subcommand renders text, files, or diffs to PNG pages offline. Examples include npx pxpipe-proxy export src/, cat prompt.txt | npx pxpipe-proxy export --stdin, and npx pxpipe-proxy export --git. Each run writes a fresh pxpipe-export-XXXXXX/ folder containing page-*.png, factsheet.txt, manifest.json, and prompt.txt. You can upload the PNGs and paste the prompt into image-upload clients like Cursor. This offline path is useful for getting visual context without touching the proxy. The README says if the package is installed, use pxpipe export instead of npx pxpipe-proxy export.

The lossy trade-off: silent confabulation on exact strings

The escape hatch is to route byte-exact work to subagents on non-allowlisted models, which pass through as text. The README gives the example CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6, or setting model: sonnet in agent frontmatter. This is a practical workaround, but it adds configuration complexity. If you cannot guarantee that your critical strings will be in the factsheet, you should treat pxpipe as unsuitable for that part of your pipeline. The lossy nature is not a bug; it is inherent to the approach. The project is honest about it, which is refreshing, but it means the adoption decision hinges on how much exact-string fidelity you need.

Model support and per-model behavior

Verbatim recall varies by model. Fable 5 scored 13 out of 15 on hex strings, while Opus 5 scored 2 out of 15, though Opus 5 still handled arithmetic and never-stated checks well. The README suggests a medium effort for Opus 5. On the GPT path, tool definitions stay native JSON and no Anthropic cache_control markers are used, which means the compression behavior differs from the Anthropic-native path. Response history compression recognizes completed function_call and function_call_output pairs, including OpenCode's parallel rounds, and only images old closed rounds atomically. Open calls and malformed states remain native. The base profile keeps the newest six completed pairs and allows 32 images; Sol keeps one pair and allows 64; Grok allows 24. You can change the GPT long-session coverage with PXPIPE_GPT_HISTORY_MAX_IMAGES=48, but the README warns to validate the provider's request cap first. This per-model tuning suggests the project is still evolving its support matrix, and you should verify your specific model's behavior before relying on it.

Evidence from evaluations and the honest part

The README also includes a demo where pxpipe counts an exact token 10 out of 10 across 39 imaged filler files, matches grep line-for-line, gets multi-step ledger arithmetic right, and ends a session at $6.06 with context to spare versus $42.21 at 96 percent full. But there is a caveat: the pxpipe arm needed a nudge to match the requested one-line output format. This is a small but telling detail. The compression can change formatting behavior in ways that require manual correction. The project calls this section 'the honest part', and it is. It lists the lossy nature, the model variance, and the workload dependence. The profitability gate is calibrated on 391 production rows, which is a real dataset, but it is still a fixed snapshot. Your traffic may differ.

Alternatives and how they differ

Another alternative is to manually trim the context: shorten the system prompt, reduce tool definitions, or compact history more aggressively. That approach does not require a proxy and has no lossy risk, but it is manual and does not scale to large histories. A third alternative is to use a model with a larger context window, such as the 1M-token windows mentioned in the README's chart, which reduce the need for compression but do not reduce the token cost per request. pxpipe's approach is fundamentally different: it changes the modality of the context, not the size of the window. That is the key difference from any text-based optimization. If you cannot tolerate any risk of silent string errors, the only safe alternative is to keep those strings in text, which pxpipe itself supports through the factsheet and subagent routing, but that is a partial solution.

Maintenance, license, and upgrade considerations

The documentation is thorough for a small project: it includes a findings file, a caching and savings doc, and evaluation receipts. That reduces the maintenance burden for adopters because you can understand the failure modes without reverse-engineering. However, the project does not appear to have a formal support channel or SLA. You are essentially adopting a tool that is honest about its limitations but still young. The token savings are real, but the lossy risk and per-model variance mean you should budget time for verification. The README's own advice is to measure per-request token cuts in ~/.pxpipe/events.jsonl, which is a concrete step you can take before committing to a full rollout.

Editorial conclusion

Adopt pxpipe if you run long Claude Code sessions with token-dense content like code, JSON, or tool output, and if you can tolerate a small risk of silent confabulation on exact strings. Do not use it for workloads that require byte-exact IDs, hashes, or secrets, unless you route those through a subagent on a non-allowlisted model. Before adopting, verify the token savings on your own traffic by running the proxy and checking ~/.pxpipe/events.jsonl, and test the verbatim recall on the specific strings you rely on. The project is MIT licensed and actively maintained, but the lossy compression is a real boundary that you must measure against your own use case.

Official sources

1. Official README
2. Project repository
3. Release notes