Caveman: AI 에이전트를 위한 토큰 압축

1. 프로젝트 개요

Caveman은 AI 코딩 에이전트의 토큰 소비를 줄이기 위해 에이전트가 읽는 내용(입력)과 말하는 내용(출력)을 모두 압축하는 오픈소스 툴킷으로, Claude Code 스타일의 스킬과 로컬 프록시로 구성됩니다. 이를 통해 정확한 코드, 오류 또는 핵심 컨텍스트를 손실하지 않으면서 리소스를 절약할 수 있습니다.

2. 배경 및 포지셔닝

핵심 미션: 에이전트 기반 코딩 세션이 길어질수록 컨텍스트 윈도우는 빠르게 가득 차고 API 비용도 함께 증가합니다. Caveman의 철학인 "적을 수 있을 때 왜 많은 토큰을 쓰는가"는 장황한 도구 출력, 로그, JSON, diff 등을 실시간으로 축소하여 에이전트가 동일한 예산 내에서 더 많은 작업을 수행할 수 있게 하며, 동시에 원본 바이트를 항상 복구할 수 있도록 보장합니다.
두 가지 보완적 제품: 오리지널 Caveman 스킬은 턴당 약간의 오버헤드를 감수하고 에이전트 자체의 응답을 더 간결하게 만듭니다(벤치마크 기준 출력 토큰 약 65% 감소). 최신 로컬 프록시인 Caveman 2는 제공자(provider)로 향하는 트래픽을 가로채어 요청이 기기를 떠나기 전에 입력을 압축합니다(고정 벤치마크 결과 제공자 보고 기준 입력 토큰 33.2% 감소).
유사 프로젝트와의 차별점: 내용을 요약하거나 의역하려는 시도(정확한 코드나 스택 트레이스가 손실될 위험이 있음) 대신, Caveman은 콘텐츠 유형을 인식하는 무손실 안전 압축을 적용합니다. 크기가 확실히 줄어들 때만 변환을 전송하고, 바이트 단위의 정확한 복구를 위해 콘텐츠 주소 지정 방식으로 원본을 보관하며, 자체 문서("정직한 수치")에서 로컬 추론 절감 효과와 독립적으로 벤치마킹된 결과를 명확히 구분합니다.

3. 기능 카테고리

🗜️ 압축 엔진
에이전트가 가장 자주 다루는 콘텐츠를 위한 유형 인식 압축기:

JSON 구조 압축 (키/구조/오류 트리) — 일반적으로 70–90% 감소
로그 압축 (오류, 트레이스, 경계) — 85–95%
코드 압축 (임포트, 시그니처, 타입) — 40–70%
Diff 압축 (헤더, 변경된 라인) — 60–80%
검색 결과 및 텍스트/HTML 압축 — 50–95%
목적: 컨텍스트 토큰을 소모하기 전에 가장 시끄럽고 반복적인 콘텐츠 유형을 축소합니다.

🖼️ 픽셀 모드
조밀한 텍스트(번들 도구 카탈로그, 긴 로그 등)를 시각 지원 모델용 PNG 이미지로 렌더링합니다. 문서화된 한 사례에서는 약 55k 텍스트 토큰이 약 11k 이미지 토큰으로 감소했습니다(−79%).
목적: 모델이 원시 텍스트보다 이미지를 더 저렴하게 읽을 수 있을 때 텍스트 토큰을 이미지 토큰으로 대체합니다.

🧠 학습 및 분석
caveman learn 명령은 에이전트의 로컬 기록을 스캔하여 토큰 과소비 지점을 찾고 수정 사항을 분류합니다.
목적: 데이터를 외부로 전송하거나 사용자에게 비용을 청구하지 않고 구체적이고 정량화된 절감 기회를 발견합니다.

🔌 에이전트 래핑
Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, OpenClaw에 대한 네이티브 래핑을 지원하며, Vercel AI SDK, LangChain, LiteLLM, CrewAI, PydanticAI와 같은 프레임워크와는 baseURL 수준에서 호환됩니다. 총 30개 이상의 에이전트를 지원합니다.
목적: 기존 에이전트 설정이 최소한의 코드 변경 또는 변경 없이 압축 프록시를 통해 라우팅되도록 합니다.

🧰 CLI 유틸리티
caveman shrink, caveman browse, caveman mem remember|recall, caveman toon encode|decode와 같은 독립 실행형 명령을 제공합니다.
목적: 개발자가 에이전트 세션 외부에서도 동일한 압축 프리미티브에 직접 접근하고 스크립트로 활용할 수 있게 합니다.

4. 주요 하이라이트

바이트 단위 정확한 복구: 모든 압축 페이로드는 압축이 전송되기 전에 콘텐츠 주소 지정 저장소에 원본 바이트를 저장하므로 아무것도 실제로 손실되지 않습니다.
작아질 때만 압축 보장: 변환은 크기가 측정 가능하게 줄어들 때만 실행됩니다. 그렇지 않을 경우 콘텐츠가 조용히 저하되는 대신 거절 사유가 로그에 기록됩니다.
입력/출력 분리 압축: 스킬(출력)과 프록시(입력)를 독립적으로 도입할 수 있어 팀은 더 큰 가치를 제공하는 쪽부터 시작할 수 있습니다.
투명한 벤치마킹: "정직한 수치" 문서는 로컬에서 추론된 절감 효과와 독립적으로 측정된 벤치마크 결과를 구분하여 부풀려진 주장을 피합니다.
선택 가능한 강도 수준: 에이전트 내 /caveman 스킬은 다양한 장황함 요구 사항에 맞게 여러 압축 강도(lite, full, ultra 및 "wenyan" 변형)를 지원합니다.
광범위한 에이전트 커버리지: 사용자를 단일 에이전트 제품에 가두지 않고 네이티브 래핑이나 간단한 baseURL 구성을 통해 30개 이상의 에이전트 및 프레임워크에서 작동합니다.

5. 역할별 사용 사례

일반 개발자: 프롬프트 방식을 변경하지 않고도 일상적인 에이전트 코딩 세션(Claude Code, Codex, Gemini CLI, Aider 등) 중 토큰 지출과 컨텍스트 비대화를 줄입니다.
DevOps/SRE: 장황한 CI 로그, 명령 출력, 진단 정보(caveman shrink -- [command])를 압축하여 에이전트가 더 작은 컨텍스트 윈도우 내에서 인시던트를 분류(triage)할 수 있게 합니다.
데이터/리서치 과학자: caveman learn을 사용하여 에이전트 세션 기록을 분석하고 토큰(및 비용)이 실제로 어디에 쓰이는지 정량화하여 워크플로우 변경에 대한 정보를 얻습니다.
프로젝트 매니저: 팀 전체에 Caveman을 배포하기 전에 벤치마크 및 "정직한 수치" 문서를 참조하여 현실적인 비용 절감 기대치를 평가합니다.

6. 시작하기

필요한 정보 찾기
문서 README.md부터 시작하여 아키텍처, CLI 레퍼런스, 보안/개인정보 보호 노트, 벤치마크 방법론에 대해 docs/ 디렉토리를 탐색하십시오.

설치 / 통합

# Proxy (Caveman 2) — 입력 압축
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude   # 또는: codex, gemini, aider, hermes, openclaw

# Skill — 출력 압축, 에이전트의 스킬 디렉토리에 설치
npx skills add JuliusBrussee/caveman

기여하기

git commit -s -m "your message"   # 모든 커밋에는 DCO 서명이 필요합니다

수정한 패키지에 해당하는 테스트 스위트(go test ./..., pnpm test 또는 pytest)를 실행하고, PR은 작고 집중되게 유지하여 메인 리포지토리에 제출하십시오. 질문은 [email protected] 또는 GitHub 토론으로 보내주십시오.

7. 프로젝트 구조

caveman/
├── agents/profiles/       # 에이전트 래핑 정의 (Claude Code, Codex, Gemini CLI, ...)
├── integrations/recipes/  # 제공자 SDK 통합 예제 (LangChain, LiteLLM, ...)
├── engine/                # 압축 엔진 및 픽셀 모드 렌더링
├── browse/                # 브라우저 콘텐츠 압축 구현
└── docs/                  # 아키텍처, CLI 레퍼런스, 벤치마크, 보안 문서

8. 관련 생태계

업스트림 에이전트/플랫폼: Claude Code (Anthropic), OpenAI Codex CLI, Gemini CLI (Google), Aider, opencode, Hermes Agent (Nous Research), OpenClaw — Caveman은 이들을 대체하는 것이 아니라 래핑합니다.
보완적 프레임워크: Vercel AI SDK, LangChain, LiteLLM, CrewAI, PydanticAI는 표준 baseURL 구성을 통해 Caveman 프록시를 가리킬 수 있습니다.
번들 서드파티 컴포넌트: pxpipe (MIT), Spleen 폰트 (BSD-2-Clause), GNU Unifont (OFL-1.1 / GPLv2-with-font-exception)가 내부적으로 사용되며, 특히 픽셀 모드 렌더링에 활용됩니다.

9. 라이선스

Caveman은 디렉토리별로 분리된 라이선스를 사용합니다.

✅ 스킬, 에이전트 SDK, CLI, 클라이언트 SDK 및 도입 표면 도구는 MIT 라이선스에 따라 자유롭게 사용, 수정 및 재배포할 수 있습니다.
✅ 엔진, 프록시, 캐시 엔진, 재작성기, 브라우즈 기능 및 MCP 서버를 자사 트래픽용으로 자체 호스팅하는 경우 BSL-1.1에 따라 무료로 사용할 수 있습니다.
❌ 프로젝트로부터 상업적 라이선스를 받지 않고 BSL-1.1 적용 컴포넌트(엔진/프록시/MCP 서버)를 서드파티 호스팅 또는 임베디드 서비스로 제공할 수 없습니다.
ℹ️ BSL-1.1 적용 코드는 2030년 6월 21일 또는 각 버전 출시 후 4년 중 먼저 도래하는 시점에 자동으로 Apache-2.0으로 전환됩니다.
ℹ️ GitHub의 메타데이터는 라이선스를 "NOASSERTION"으로 나열하는데, 이는 분리된 MIT/BSL-1.1 모델이 단일 SPDX 식별자에 매핑되지 않기 때문입니다. 실제로 적용되는 약관은 각 디렉토리의 LICENSE 파일을 확인하십시오.

10. FAQ

Q: Caveman이 데이터를 조용히 손상시키거나 손실하는 경우가 있습니까?
A: 아닙니다. 모든 압축 페이로드는 원본 바이트의 콘텐츠 주소 지정 사본을 유지하며, 변환은 입력보다 엄격하게 작을 때만 전송됩니다. 그렇지 않으면 거절 사유가 로그에 기록됩니다.

Q: 프록시 없이 출력 압축 스킬만 사용하거나 그 반대로 사용할 수 있습니까?
A: 네. 스킬(npx skills add JuliusBrussee/caveman)과 프록시(npm install -g @caveman-ai/cli)는 독립적인 제품이며 별도로 도입할 수 있습니다.

Q: Caveman은 어떤 코딩 에이전트를 지원합니까?
A: 네이티브 래핑은 Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent, OpenClaw를 포함하며, baseURL로 구성 가능한 프레임워크를 포함해 총 30개 이상의 에이전트에 도달할 수 있습니다.

Q: 우리 팀을 위해 프록시/엔진을 자체 호스팅할 수 있습니까?
A: 네, 자사 트래픽용 자체 호스팅은 BSL-1.1에 따라 무료입니다. 상업적 라이선스는 서드파티에게 호스팅 또는 임베디드 서비스로 제공할 때만 필요합니다.

Q: 벤치마크 수치(65%, 33.2%)는 어디서 나왔습니까?
A: docs/HONEST-NUMBERS.md 및 docs/WRAP-BENCHMARK.md를 참조하십시오. 이 문서들은 로컬 추론 추정치와 독립적으로 고정된 벤치마크 결과를 구분합니다.

11. 빠른 링크

리포지토리: https://github.com/JuliusBrussee/caveman
문서: https://github.com/JuliusBrussee/caveman/tree/main/docs
기여 가이드: https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md
토론 / 연락처: 리포지토리의 GitHub Discussions 또는 [email protected]

12. 요약

Caveman은 AI 코딩 에이전트에게 중요한 것을 잃지 않으면서 덜 말하고 덜 읽을 수 있는 실용적인 방법을 제공합니다. 더 간결한 출력 스킬과 입력 압축 로컬 프록시를 쌍으로 제공하며, 둘 다 바이트 단위의 정확한 복구를 보장합니다. 이는 Claude Code, Codex, Gemini CLI 또는 유사한 도구를 사용하여 긴 에이전트 코딩 세션을 실행하는 개발자와 팀에게 가장 유용하며, 정확한 코드, 오류 또는 로그를 포기하지 않으면서 측정 가능한 토큰 지출 절감을 원하는 경우에 적합합니다.