teamchong/pxpipe

pxpipe – Claude Code 및 기타 LLM을 위한 토큰 절약 프록시

정의 – pxpipe는 LLM 요청의 부피가 큰 부분(시스템 프롬프트, 도구 정의, 긴 채팅 기록, 파일 diff 등)을 모델에 도달하기 전에 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 대 $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에 큰 시스템 프롬프트나 긴 파일 diff를 보내는 에이전트 도구(예: 코드 어시스턴트, 도구 사용 봇)를 구축하는 개발자.
워크로드가 토큰 밀도가 높은 경우 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는 비전 토큰 가격 책정을 활용하여 대규모 텍스트 컨텍스트를 이미지로 압축하고, 통합 표면을 단순하게(로컬 HTTP 프록시만) 유지하면서 토큰이 많은 LLM 워크플로에서 측정 가능한 비용 절감을 제공하는 실용적인 오픈 소스 도구입니다.