teamchong/pxpipe

pxpipe – Claude Code などの LLM 向けトークン節約プロキシ

概要 – pxpipe は、LLM リクエストのかさばる部分（システムプロンプト、ツール定義、長いチャット履歴、ファイル差分など）を、リクエストがモデルに到達する前にPNG画像に書き換えるローカルプロキシです。ビジョン対応モデルは画像トークンごとに課金されるため（ピクセル数に依存し、画像内のテキスト量には依存しない）、コードやJSONの密集したブロックは、同じテキストが消費するトークンよりもはるかに少ないトークンで表現できます。このプロキシは、AnthropicのClaude Code、Google Gemini、およびビジョン入力をサポートするOpenAI互換エンドポイントで動作します。

主要なアイデア

概念	仕組み
トークン密度の向上	312×728pxの画像（Claude-Fable-5プロファイル）は、画像トークンあたり約 3.1文字を保持します。Claude Code のテキストトークンあたり約1文字と比較すると、1Mトークンのウィンドウに収まる文字数が約4.7〜5倍に増加します。
選択的圧縮	対象となるバルクコンテキストのみが画像に変換されます（システムプロンプト、ツールドキュメント、クローズされたツールコールラウンド、古い履歴）。最近のターンやバイトクリティカルなデータ（ID、ハッシュ、シークレット）はプレーンテキストのままです。
非可逆だが保護付き	画像変換は正確な16進文字列を誤読する可能性があります（例：Fable-5で15件中13件正解）。各リクエストに添付される「ファクトシート」は、最大96個の高精度トークンを保持します。それ以外はベストエフォートです。
収益性ゲート	pxpipe は元のリクエストに対して安価なトークンカウントプローブ（`count_tokens`）を実行し、期待されるコスト削減がしきい値（密なワークロードで約60〜70%）を超える場合にのみ画像変換を適用します。
モデル固有のレンダリングプロファイル	モデルによってフォント、セルサイズ、ページ寸法が異なります（例：Claude-Fable-5は5×8 Spleenフォント、GrokはJetBrains Mono 14pxを使用）。プロキシはモデルIDに基づいて正しいプロファイルを選択します。

試してみる方法（クイックスタート）

# ローカルプロキシを起動（127.0.0.1:47821で待ち受け）
npx pxpipe-proxy

# Claude Code をプロキシに向ける
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

http://127.0.0.1:47821/ のダッシュボードには、ライブのトークン節約量、テキストと画像のレンダリングの並列表示、およびキルスイッチが表示されます。

または、プロキシを自動的に注入する warp ラッパーを使用します。

pxpipe warp -- claude   # ANTHROPIC_BASE_URL を設定する必要はありません

プロキシを実行せずに、任意のテキストやgitリポジトリをPNGページにエクスポートすることもできます。

npx pxpipe-proxy export src/          # src/ 内のファイルをレンダリング
cat prompt.txt | npx pxpipe-proxy export --stdin
npx pxpipe-proxy export --git          # 現在のリポジトリ履歴をレンダリング

エクスポートすると、page-*.png、factsheet.txt、manifest.json、元の prompt.txt を含むフォルダが作成されます。

実際の効果（リポジトリでの報告による）

指標	報告された結果
エンドツーエンドのコスト削減	本番ワークロードで約59〜70% の請求額削減（例：デモで$6.06 vs $42.21）。
トークン削減	48k文字のシステムプロンプトで、25kテキストトークン → 約2.7k画像トークン。
ベンチマーク品質	Claude-Fable-5で算術100/100、要点約98/98、状態18/18。16進文字列の再現では若干の低下（15件中13件）。
SWE-bench	「Lite」スイートでリクエストサイズ‑65%、「Pro」スイートで‑60%の同等精度の結果。

制限事項と注意点

非可逆変換 – 正確な識別子（12文字の16進数、シークレット）は誤読される可能性があります。そのようなトークンは、可能な場合は意図的にテキストとして保持されます。
モデル依存性 – ビジョン入力を受け入れ、コンテキストウィンドウが大きいモデルでは節約効果が高くなります。疎な散文は実際にはコストが増加する可能性があります。
リクエスト側のみの圧縮 – モデルの出力は画像に変換されないため、出力トークンコストは変わりません。
収益性ゲートはヒューリスティック – 組み込みのしきい値は作者の本番データ（約391行）で機能しますが、さまざまなワークロードに合わせて調整が必要な場合があります。
サポートされているモデル – デフォルト：Claude-Fable-5、Claude-Opus-5-5、Gemini-Flash。その他のモデル（Grok、Sol、GPT-5.6-Solなど）は、PXPIPE_MODELS でオプトインできます。

誰が使うべきか？

Claude Code や Gemini に大きなシステムプロンプトや長いファイル差分を送信する エージェントツール（例：コードアシスタント、ツール使用ボット）を構築する開発者。
ワークロードがトークン密度の高い場合に LLM API 費用を削減 したいチーム。
ビジョン拡張プロンプティング とトークン圧縮のトレードオフの測定に興味のある研究者。

クイックリファレンスチートシート

コマンド	目的
`npx pxpipe-proxy`	プロキシサーバーを起動（デフォルトポート47821）。
`pxpipe warp -- <cmd>`	プロキシを自動的に注入してコマンド（例：`claude`）を実行。
`pxpipe warp --route '<src>=<dst>' <cmd>`	Anthropic以外のエンドポイント用のカスタムルーティングルールを追加。
`pxpipe-proxy export <path>`	プロキシを実行せずにファイルまたは標準入力をPNGページにレンダリング。
`pxpipe stats`	イベントログ（`~/.pxpipe/events.jsonl`）から節約されたトークン/コストを要約。

結論 – pxpipe は、ビジョントークンの価格設定を活用して大きなテキストコンテキストを画像に圧縮し、トークンが多いLLMワークフローで測定可能なコスト削減を提供しながら、統合面をシンプル（ローカルHTTPプロキシのみ）に保つ実用的なオープンソースツールです。