pxpipe: nén context Claude Code thành ảnh để cắt input token

TL;DR

• pxpipe là một local proxy mã nguồn mở, render các khối context cồng kềnh của Claude Code - system prompt, tool docs, lịch sử cũ - thành ảnh PNG dày đặc để cắt input token.
• Chi phí token của một ảnh cố định theo kích thước pixel, không phụ thuộc lượng chữ nhồi bên trong. Đó là kẽ hở pxpipe khai thác.
• Trên traffic thực, hóa đơn end-to-end giảm khoảng 59-70%. Một trang ~48k ký tự (~25k text token) co lại còn ~2.7k image token.
• Đánh đổi thẳng thắn: đây là nén lossy. Chuỗi byte chính xác như ID, hash, secret khi đọc lại từ ảnh có thể sai mà không hề báo lỗi.

Vấn đề pxpipe giải quyết

Mỗi request tới Claude Code không chỉ mang câu hỏi của bạn. Nó kéo theo một system prompt lớn, một loạt tool docs mô tả mọi công cụ agent có thể gọi, và toàn bộ lịch sử hội thoại đủ dài để model hiểu ngữ cảnh. Tất cả đều tính bằng input token, và request nào cũng phải gửi lại gần như y hệt. Với một phiên coding kéo dài, đây là phần chi phí phình to nhanh nhất mà bạn gần như không kiểm soát được.

Cách xử lý phổ biến hiện nay là /compact: khi context đầy, model tự tóm tắt phần cũ thành một đoạn prose ngắn rồi tiếp tục. Nó cắt được token, nhưng đánh đổi bằng việc vứt bỏ chi tiết - bạn không lấy lại được nguyên văn prompt hay tool output trước đó. pxpipe đặt câu hỏi khác: nếu thay vì tóm tắt, ta chỉ đơn giản đổi cách mã hóa đúng đống chữ đó thì sao?

Vì sao ảnh lại rẻ hơn chữ

Chìa khóa nằm ở cách tính token của model. Một tấm ảnh tốn số vision token cố định theo pixel, bất kể nó chứa 10 chữ hay 10.000 chữ. Với nội dung dày đặc - code, JSON, tool output - một ảnh đóng gói được khoảng 3,1 ký tự trên mỗi image-token, so với chỉ khoảng 1 ký tự trên mỗi text-token khi để dạng chữ thuần. Traffic Claude Code thực tế chạy ở mức ~1,91 ký tự/token (đo trên 391 request), nên gần như luôn có lợi khi chuyển sang ảnh.

Con số cụ thể: khoảng 48k ký tự system prompt cộng tool docs vốn tốn ~25k token dạng chữ, khi reflow thành một trang ảnh 1573x1248 chỉ còn khoảng 2,7k image token. Đây chính xác là thứ model đọc thay cho chữ:

pxpipe hoạt động thế nào

pxpipe chạy như một proxy nội bộ tại 127.0.0.1:47821. Nó chặn endpoint /v1/messages, viết lại những khối bulk đủ điều kiện thành image block, rồi ghép trở lại theo hướng cache-friendly: phần prefix tĩnh được giữ nguyên nên prompt caching vẫn hoạt động bình thường. Quan trọng là nó chỉ nén request, không bao giờ đụng vào output của model - response vẫn stream về dạng chữ như thường.

Quy trình chuyển đổi khá thẳng: một chuỗi tool_result được wrap ở cột rộng 1928px, pack khoảng 92.000 ký tự mỗi trang, rồi xuất ra mảng PNG.

Phần toán học phía sau rất rõ ràng. Một ảnh 1928x1928 tốn khoảng 4.761 vision token nhưng chứa được ~92.000 ký tự, nghĩa là chữ chỉ thắng khi mật độ vượt ~19 ký tự/token - điều gần như không xảy ra với traffic thật. pxpipe không nén bừa: một estimator chạy trước mỗi request để quyết định, và có một profitability gate được hiệu chỉnh trên 391 dòng dữ liệu production, chỉ image những chỗ mà phép tính có lợi. Prose thưa thì để nguyên dạng chữ.

Thử trong 30 giây

Không cần cấu hình phức tạp. Chạy proxy rồi trỏ Claude Code vào nó:

npx pxpipe-proxy                                  # proxy tại 127.0.0.1:47821
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # trỏ Claude Code vào proxy

Mở dashboard tại 127.0.0.1:47821 để xem token đã tiết kiệm, từng lần chuyển text sang image đặt cạnh nhau, kill switch, và các model chip live. Nếu chỉ muốn dùng như thư viện mà không cần proxy, package pxpipe-proxy export sẵn renderTextToImages và transformAnthropicMessages, chạy được cả trên Node lẫn edge/Workers.

Con số nói gì

Điểm đáng khen là pxpipe đo bằng bài toán số ngẫu nhiên mới toanh, thứ model không thể học thuộc từ trước, và công khai cả những chỗ nó thua:

Ở tier gist - nhớ được kế hoạch, giá trị, đường dẫn, trạng thái file - pxpipe đạt parity tuyệt đối với dạng chữ. Trong một thử nghiệm SWE-bench Lite, cả hai phía đều giải 10/10 ở mức giảm 65% kích thước request. Nhưng bảng trên cũng phơi bày ngay ranh giới của nó ở dòng cuối.

Phần thành thật: đây là nén lossy

pxpipe không giấu nhược điểm, và đây là phần bạn phải hiểu trước khi bật nó. Với chuỗi hex 12 ký tự nằm trong nội dung ảnh dày đặc, Fable 5 đọc đúng 13/15, còn Opus đọc đúng 0/15. Tệ hơn, những lần đọc sai là confabulation im lặng: model bịa ra một giá trị trông hợp lý và khẳng định chắc nịch, chứ không báo lỗi. Vì thế mọi giá trị byte-exact - ID, hash, secret - phải giữ dạng chữ, và những lượt hội thoại gần nhất luôn được giữ nguyên text.

Từ ràng buộc đó là loạt quy tắc an toàn. Phạm vi model mặc định chỉ gồm claude-fable-5 và gpt-5.6; Opus 4.7/4.8 đọc sai khoảng 7% số trang render nên phải opt-in thủ công qua PXPIPE_MODELS hoặc dashboard. Muốn tắt hoàn toàn thì đặt PXPIPE_MODELS=off. Với công việc cần chính xác từng byte, có escape hatch: route nó sang subagent chạy model ngoài allowlist để phần đó đi qua nguyên dạng chữ.

Tác giả cũng ghi lại một lần hỏng thật ngoài benchmark: trong nhiều tuần dùng hằng ngày, đúng một lần model nhớ sai tên một người từ lịch sử đã bị đóng thành ảnh - không lỗi, chỉ là một cái tên sai đầy tự tin. Coding session chịu được điều này vì agent luôn đọc lại file trước khi sửa; chat recall thuần thì không có lớp kiểm tra đó.

So với /compact

Đặt cạnh /compact, hai cách có profile mất mát ngược nhau. /compact mất nội dung nhưng giữ độ chính xác - text tóm tắt vẫn đúng, và model biết rõ giới hạn của mình. pxpipe thì ngược lại: mất độ chính xác nhưng giữ nội dung - mọi thứ vẫn nằm trong pixel, chỉ là không đọc lại chính xác từng ký tự được.

Ưu điểm của hướng ảnh là dữ liệu vẫn recoverable thay vì bị vứt, là một dốc thoải thay vì vách đứng, và không dính vòng lặp tóm-tắt-của-tóm-tắt càng lúc càng nhòe. Điểm yếu duy nhất thật sự là hình dạng của lỗi: /compact khi bí sẽ nói không biết, còn pxpipe trên Opus lại trượt vào confabulation tự tin. Đó là lý do Opus bị để mặc định tắt.

Ai nên dùng

pxpipe hợp nhất với những phiên agent coding dài, nơi hóa đơn token dày đặc và bản thân workflow đã có sẵn cơ chế tự kiểm tra. Nếu bạn chạy Claude Code hàng giờ trên Fable 5 và thấy chi phí input leo thang vì system prompt cùng lịch sử lặp lại, đây là thứ đáng thử ngay - phần lỗ ở độ chính xác được che chắn bởi việc agent luôn đọc lại file gốc trước khi hành động.

Ngược lại, nếu công việc của bạn xoay quanh việc nhớ chính xác từng chuỗi ID, khóa, hay dữ liệu nhạy cảm dạng chat thuần, hãy cân nhắc kỹ hoặc để nguyên phần đó dạng chữ. pxpipe không cố bán cho bạn một phép màu không mất mát; nó bán một sự đánh đổi được đo đạc rõ ràng, và để bạn tự quyết có chấp nhận hay không.

Kết

pxpipe là một ý tưởng vừa đơn giản vừa hơi ngược đời: token của model tính theo pixel chứ không theo chữ, nên đôi khi cách rẻ nhất để gửi một đống văn bản lại là đừng gửi nó dưới dạng văn bản. Điều khiến nó thuyết phục không phải con số 70%, mà là cách nó công khai đo cả phần thắng lẫn phần thua, và để lại cho người dùng đúng những công tắc cần thiết để kiểm soát đánh đổi đó. Một chi tiết thú vị khép lại: phần lớn code và tài liệu của chính repo được viết bởi các phiên agent chạy sau pxpipe, đọc lịch sử của chính mình dưới dạng ảnh trong lúc làm việc.

via teamchong/pxpipe