How teamchong/pxpipe works
1. What this repo is
- pxpipe is a token-compression proxy/library for Claude Code–style traffic.
- Its core move is architectural: it rewrites selected request-side context into PNG images before the request leaves the machine, while leaving responses untouched.
2. Main ingress/egress boundary
- The primary runtime boundary is an Anthropic-compatible /v1/messages proxy.
- Clients such as Claude Code point ANTHROPIC_BASE_URL at the local proxy; the proxy forwards to Anthropic/GPT backends after transformation.
- Unsupported models or non-eligible content are passed through byte-identically.
3. Request transformation pipeline
- The central pipeline lives in src/core/transform.ts and related helpers.
- It parses a request, classifies message blocks, decides what is profitable to image, and rewrites eligible blocks into image content.
- Important policy knobs include keepSharp for forcing text retention and emitRecoverable for retaining originals of imaged blocks.
4. Rendering subsystem
- Text-to-image conversion is isolated in src/core/render.ts, png.ts, atlas.ts, and atlas-gray.ts.
- The renderer wraps dense text into fixed-size pages, then encodes pages as PNGs using bundled font assets in assets/.
- This is the mechanical heart of the compression: long text slabs become dense image pages sized to fit model vision input efficiently.
5. Eligibility, sizing, and layout
- src/core/applicability.ts, measurement.ts, and factsheet.ts determine whether a block should be imaged and how it should be laid out.
- The system is intentionally selective: recent turns, sparse prose, and small chunks stay text; bulky tool output, history, and system/tool-document slabs are candidates for imaging.
- The docs under docs/RENDER_SIZING.md and docs/TRANSFORM_INFO.md appear to capture these constraints and the page geometry assumptions.
6. Cost, caching, and “savings” accounting
- src/core/baseline.ts, openai-savings.ts, history.ts, and openai-history.ts track the economics of a transformed request versus a counterfactual plain-text request.
- The proxy measures savings against a token-count baseline and records actual billed usage, rather than inferring savings from just the touched portion.
- Cache behavior matters: the architecture preserves static prefixes where possible so prompt caching still works, and the accounting explicitly includes cache write/read effects.
7. Model profiles and provider-specific behavior
- src/core/gpt-model-profiles.ts, openai.ts, and proxy.ts reflect that the system is not Anthropic-only.
- The README shows two key provider families: Claude/Anthropic and GPT models, with different handling for tool definitions and cache markers.
- Model allowlisting is part of the control plane: some models are imaged by default, others are opt-in or pass through unchanged.
8. Persistence and telemetry
- The proxy writes operational events to ~/.pxpipe/events.jsonl and uses those rows as the canonical record for savings and behavior.
- src/core/tracker.ts, stats.ts, sessions.ts, and export.ts suggest a second layer that aggregates per-session and per-request state for analysis, dashboards, and export.
- src/export-collect.ts is the likely boundary for turning raw proxy logs into reportable artifacts.
9. Local dashboard and operator controls
- src/dashboard.ts plus src/dashboard/ implement a local UI served by the proxy.
- The dashboard exposes live model chips, token savings, per-request conversions, and a kill switch.
- This is an operational control surface, not a separate backend: it reads the same proxy state and event log.
10. Runtime targets and packaging
- The repo is designed for pure JS runtime portability across Node and Cloudflare Workers; src/node.ts and src/worker.ts are the deployment entrypoints.
- wrangler.toml indicates an edge/Workers deployment path, while bin/cli.js is the local CLI entry.
- @napi-rs/canvas is build-time only; the runtime stays JavaScript-first.
11. Research, evaluation, and receipts
- The eval/ tree is a substantial measurement harness, not production code.
- It contains benchmark runners, grading scripts, receipts, and reports for recall, savings, SWE-bench variants, GSM8K, and other experiments that justify the compression policy.
- The demo/ tree contains smaller reproducible scenarios, including cost A/B examples and context-efficiency demos.
12. Testing and release boundaries
- The tests/ suite is broad and architectural: cache alignment, proxy behavior, render fidelity, export correctness, dashboard API, restart/restore, and savings honesty.
- GitHub Actions in .github/workflows/ run CI and release workflows, indicating the repo is shipped as a packaged tool/library with reproducible builds.
- The presence of pnpm-workspace.yaml, tsconfig.json, and vitest.config.ts shows a TypeScript monorepo-style setup with a single cohesive runtime package plus supporting evaluation assets.
13. Diagram-friendly summary
- If you draw this repo, the key flow is: client → local proxy → transform/render decision → PNG/text rewrite → upstream model API → response passthrough.
- Surrounding that path are three support planes: policy/accounting (savings, cache, model profiles), observability/UI (events, dashboard, exports), and research/test harnesses (eval/, demo/, tests/) that validate whether the compression remains useful and honest.
Main entry points: proxy.ts Proxy · render.ts Render · transform.ts Transform · tracker.ts Tracker
Components 24
Runtime
Deployment entrypoints and proxy boundary
- CLI · Local command entry for running and controlling the tool
bin/cli.js - Node app · Node runtime entrypoint and server bootstrap
src/node.ts - Worker app · Cloudflare Workers entrypoint
src/worker.ts
Core pipeline
Request transformation, rendering, and model-specific handling
- Proxy · Anthropic-compatible /v1/messages boundary that forwards transformed traffic
src/core/proxy.ts - Transform · Parses requests, classifies blocks, and rewrites eligible text into images
src/core/transform.ts - Applicability · Selects which blocks are profitable or allowed to image
src/core/applicability.ts - Measurement · Estimates block size and layout constraints for compression decisions
src/core/measurement.ts - Factsheet · Captures page geometry and transform assumptions
src/core/factsheet.ts - Render · Converts dense text slabs into paged image content
src/core/render.ts - PNG encode · Encodes rendered pages into PNG payloads
src/core/png.ts - Atlas · Primary glyph atlas used by the renderer
src/core/atlas.ts - Gray atlas · Alternate grayscale atlas for rendering
src/core/atlas-gray.ts - Model profiles · Model-specific behavior and eligibility rules
src/core/gpt-model-profiles.ts - OpenAI bridge · Provider-specific request shaping for GPT/OpenAI-style traffic
src/core/openai.ts
Ops & data
Accounting, persistence, sessions, and dashboard surfaces
- Accounting · Baseline, history, and savings math for transformed requests
src/core/baseline.ts - History · Tracks request and cache history for cost accounting
src/core/history.ts - Tracker · Writes canonical operational events and usage records
src/core/tracker.ts - Export · Aggregates logs into exportable reports and artifacts
src/export-collect.ts - Stats · Session and request-level summaries for savings and behavior
src/stats.ts - Sessions · Groups proxy activity into session state
src/sessions.ts - Dashboard · Local operator UI served alongside the proxy
src/dashboard.ts
Research & QA
Evaluation, demos, tests, and validation assets
- Eval suite · Measurement and grading harness for compression quality and savings
eval/README.md - Demos · Reproducible scenarios for cost and context-efficiency behavior
demo/README.md - Tests · Architectural and end-to-end regression coverage
tests/public-api.test.ts
Connections 26
- CLI → Proxy: start · Launches the local proxy and control surface
- Node app → Proxy: serves · Bootstraps the proxy in Node runtime
- Worker app → Proxy: serves · Bootstraps the proxy in Workers runtime
- Proxy → Transform: rewrite · Transforms eligible requests before forwarding
- Transform → Applicability: decide · Checks whether blocks should stay text or become images
- Transform → Measurement: measure · Estimates block size and fit for pagination
- Transform → Render: render · Sends selected text slabs to image generation
- Measurement → Factsheet: constraints · Uses geometry and layout assumptions
- Render → Atlas: glyphs · Uses bundled font atlas for page construction
- Render → Gray atlas: glyphs · Can use grayscale atlas variant
- Render → PNG encode: encode · Packages rendered pages as PNG images
- Proxy → Model profiles: select model · Applies allowlisting and model-specific behavior
- Proxy → OpenAI bridge: adapt · Handles GPT/OpenAI-style provider differences
- Proxy → Accounting: record savings · Computes counterfactual and transformed cost
- Accounting → History: consult · Uses request and cache history for billing math
- Proxy → Tracker: emit · Writes operational events for canonical recordkeeping
- Tracker → Stats: aggregate · Feeds session and request summaries
- Stats → Sessions: group · Organizes activity into sessions
- Dashboard → Tracker: read · Displays live events and usage state
- Dashboard → Stats: read · Shows savings and per-request summaries
- Export → Tracker: consume · Turns event logs into reports and exports
- Eval suite → Render: exercise · Benchmarks render quality and compression behavior
- Demos → Transform: demonstrate · Shows cost and context-efficiency scenarios
- Tests → Proxy: verify · Covers proxy, cache, and passthrough behavior
- Tests → Render: verify · Checks render fidelity and sizing behavior
- Tests → Export: verify · Checks export and accounting correctness