teamchong/pxpipe

pxpipe – Token‑saving proxy for Claude Code and other LLMs

What it is – pxpipe is a local proxy that rewrites the bulky parts of an LLM request (system prompt, tool definitions, long chat history, file diffs, etc.) into PNG images before the request reaches the model. Because vision‑enabled models charge per image token (which depends on pixel count, not on the amount of text inside the image), a dense block of code or JSON can be represented with far fewer tokens than the same text would consume. The proxy works with Anthropic’s Claude Code, Google Gemini, and any OpenAI‑compatible endpoint that accepts vision inputs.

Key ideas

Concept	How it works
Token‑density boost	An image of 312 × 728 px (Claude‑Fable‑5 profile) holds roughly 3.1 chars per image‑token, compared with 1 char per text‑token on Claude‑Code. This translates to a 4.7‑5× increase in characters that can be fit into a 1 M‑token window.
Selective compression	Only eligible bulk context is turned into images (system prompt, tool docs, closed tool‑call rounds, older history). Recent turns and any byte‑critical data (IDs, hashes, secrets) stay as plain text.
Lossy but guarded	The image conversion can mis‑read exact hex strings (e.g., 13/15 correct on Fable‑5). A “factsheet” attached to each request preserves up to 96 high‑precision tokens; everything else is best‑effort.
Profitability gate	pxpipe runs a cheap token‑count probe (`count_tokens`) on the original request and only applies image conversion when the expected cost saving exceeds a threshold (≈ 60‑70 % for dense workloads).
Model‑specific rendering profiles	Different models use different fonts, cell sizes, and page dimensions (e.g., Claude‑Fable‑5 uses a 5×8 Spleen font, Grok uses JetBrains Mono 14 px). The proxy selects the correct profile based on the model ID.

How to try it (quick start)

# Start the local proxy (listens on 127.0.0.1:47821)
npx pxpipe-proxy

# Point Claude Code at the proxy
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

The dashboard at http://127.0.0.1:47821/ shows live token‑savings, side‑by‑side text‑vs‑image rendering, and a kill‑switch.

Alternatively, use the warp wrapper which injects the proxy automatically:

pxpipe warp -- claude   # no need to set ANTHROPIC_BASE_URL

You can also export any text or git repository to PNG pages without a running proxy:

npx pxpipe-proxy export src/          # renders files in src/
cat prompt.txt | npx pxpipe-proxy export --stdin
npx pxpipe-proxy export --git          # renders the current repo history

The export creates a folder containing page-*.png, a factsheet.txt, a manifest.json, and the original prompt.txt.

Real‑world impact (as reported in the repo)

Metric	Reported result
End‑to‑end cost reduction	~59–70 % lower bill on production workloads (e.g., $6.06 vs $42.21 in a demo).
Token reduction	25 k text tokens → ~2.7 k image tokens for a 48 k‑char system prompt.
Benchmark quality	Arithmetic 100/100, gist ~98/98, state 18/18 on Claude‑Fable‑5; modest drops on hex‑string recall (13/15).
SWE‑bench	Same‑accuracy results with ‑65 % request size on the “Lite” suite; ‑60 % on the “Pro” suite.

Limitations & cautions

Lossy conversion – Exact identifiers (12‑char hex, secrets) can be mis‑read; such tokens are deliberately kept as text when possible.
Model‑dependence – Savings are high for models that accept vision inputs and have large context windows; sparse prose may actually increase cost.
Only request‑side compression – Model outputs are never turned into images, so output token cost is unchanged.
Profitability gate is heuristic – The built‑in threshold works for the authors’ production data (≈ 391 rows) but may need tuning for different workloads.
Supported models – By default: Claude‑Fable‑5, Claude‑Opus‑5‑5, Gemini‑Flash. Other models (Grok, Sol, GPT‑5.6‑Sol, etc.) are opt‑in via PXPIPE_MODELS.

Who might use it?

Developers building agentic tools (e.g., code‑assistants, tool‑using bots) that send large system prompts or long file diffs to Claude Code or Gemini.
Teams looking to reduce LLM API spend when their workloads are token‑dense.
Researchers interested in vision‑augmented prompting and measuring token‑compression trade‑offs.

Quick reference cheat‑sheet

Command	Purpose
`npx pxpipe-proxy`	Start the proxy server (default port 47821).
`pxpipe warp -- <cmd>`	Run a command (e.g., `claude`) with the proxy injected automatically.
`pxpipe warp --route '<src>=<dst>' <cmd>`	Add custom routing rules for non‑Anthropic endpoints.
`pxpipe-proxy export <path>`	Render files or stdin to PNG pages without a running proxy.
`pxpipe stats`	Summarize saved tokens/cost from the event log (`~/.pxpipe/events.jsonl`).

Bottom line – pxpipe is a practical, open‑source tool that leverages vision‑token pricing to compress large textual contexts into images, delivering measurable cost savings for token‑heavy LLM workflows while keeping the integration surface simple (just a local HTTP proxy).