# pxpipe

> A local proxy that sends bulky context to the model as images

- Category: App Orchestration / Context Compression & Token Budgets
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/teamchong/pxpipe
- Canonical page: https://ai-tldr.dev/tools/pxpipe/
- Updated: 2026-07-03

## In short

pxpipe is a proxy you run on your own machine that sits between a coding agent and its model provider and rewrites the bulky parts of each request into compact PNG pages. It sits in the Context Compression & Token Budgets category of the App Orchestration tools and is open-source, written in TypeScript and licensed MIT.

## Overview

pxpipe is a proxy you run on your own machine that sits between a coding agent and its model provider and rewrites the bulky parts of each request into compact PNG pages. The idea rests on how vision models are billed: an image's token cost is fixed by its pixel dimensions, not by how much text is drawn inside it, so dense content such as code, JSON and tool output packs far more characters per token as an image than as text.

In practice the system prompt, tool definitions and older conversation turns are the parts that get imaged, while recent turns stay as text. Only the request is compressed — responses stream back normally, untouched. A dashboard on the proxy port shows tokens saved, every text-to-image conversion side by side, live model chips and a kill switch, and each request is measured against a free count_tokens counterfactual logged to ~/.pxpipe/events.jsonl.

The project is unusually direct about its limits. Imaging is lossy: byte-exact values such as IDs, hashes and secrets can be silently confabulated, so they must stay in text, and a profitability gate calibrated on production traffic only images content where the token math actually wins — sparse prose costs more as an image than as text. Model support is an explicit allowlist; anything outside it passes through byte-identical.

## What it does

- Local proxy for the Anthropic Messages API that images the system prompt, tool docs and older history while recent turns stay text
- Request-only compression — model responses stream back unchanged
- Dashboard on the proxy port with per-request savings, side-by-side conversions, model chips and a kill switch
- Per-request measurement against a count_tokens counterfactual, logged to ~/.pxpipe/events.jsonl
- A profitability gate that skips imaging on sparse prose, where rendering would cost more tokens than it saves
- Offline export mode that renders files, stdin or a git diff to PNG pages plus a factsheet, with no proxy involved

## Getting started

The proxy runs from npx with no install. Point your agent's base URL at it, or let pxpipe wrap the command for you.

1. Start the proxy and point Claude Code at it

   The proxy listens on 127.0.0.1:47821; the dashboard is served at the same address.

```bash
npx pxpipe-proxy
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude
```

2. Or wrap the command instead

   pxpipe warp runs the agent without setting ANTHROPIC_BASE_URL, so first-party gates and connectors keep working. Agents that reach their provider over a different base URL need an explicit route rule.

```bash
pxpipe warp -- claude
pxpipe warp --route '127.0.0.1:9090/v1/*=http://127.0.0.1:47821' -- codex
```

3. Choose which models get imaged

   PXPIPE_MODELS is an allowlist; models outside it pass through byte-identical, and PXPIPE_MODELS=off disables imaging entirely. The same chips are toggleable from the dashboard.

```bash
PXPIPE_MODELS=off npx pxpipe-proxy
```

4. Export pages without running the proxy

   Each run writes a fresh output folder containing page-*.png, factsheet.txt, manifest.json and prompt.txt, which you can upload to any image-capable client.

```bash
npx pxpipe-proxy export src/
cat prompt.txt | npx pxpipe-proxy export --stdin
npx pxpipe-proxy export --git
```

## When to use it

- Cut the input-token bill of a long-running coding-agent session where the same system prompt and tool docs are re-sent on every turn
- Fit more of a large codebase into a fixed context window by trading text tokens for image tokens on the dense parts
- Measure what imaging would actually save on your own traffic before committing to it, using the logged counterfactual counts
- Render a directory or a git diff to PNG pages for an image-upload client when you cannot run a proxy at all

## Version history

- 2026-07-03 v0.7.1: The release that put pxpipe on the Hacker News front page: a localhost proxy that rewrites bulky system prompts, tool docs and older turns as PNG images the model reads with vision, reported at a 59-70% cut in input tokens on Claude Code traffic.