JuliusBrussee/caveman

Caveman – AI 코딩 어시스턴트를 위한 토큰 절약 래퍼

이것이 무엇인가 – Caveman은 AI 기반 코딩 어시스턴트(Claude Code, Codex, Gemini, Cursor 등)와 기본 LLM 제공자 사이에 위치하는 경량 "스킬"(규칙 파일)이자 선택적 로컬 프록시입니다. 그것의 유일한 목적은 모델이 읽고 써야 하는 텍스트의 양을 줄여 청구되는 토큰 수를 낮추는 것입니다.

작동 방식

• 스킬(작은 바위) – 모델 응답의 산문 부분을 간결한 "원시인" 스타일로 다시 작성하는 간단한 프롬프트 스타일 규칙입니다(예: 69토큰 설명을 19토큰으로 변환). 코드 스니펫, 파일 경로 및 정확한 오류 메시지는 그대로 둡니다.
• 프록시(큰 바위) – 에이전트에서 LLM 제공자로 가는 모든 요청을 가로채는 로컬 Node.js 프로세스입니다. 페이로드 유형(JSON, 로그, 코드, diff, 검색 결과 등)을 감지하고 필수 정보(키, 오류 줄, 함수 시그니처 등)를 유지하면서 반복적이거나 잡음이 많은 부분을 버리는 맞춤형 압축기를 적용합니다. 원본 페이로드는 SQLite 캐시에 저장되어 에이전트가 필요 시 전체 텍스트를 검색할 수 있습니다.
• Wrap-any-agent – 프록시를 활성화한 상태에서 대상 에이전트를 시작하는 얇은 래퍼로, 에이전트의 구성 파일을 수정하지 않습니다. 지원되는 에이전트로는 Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, Kilo Code, Qwen Code, opencode, Hermes, OpenClaw 및 Pi가 있습니다.

README의 주요 수치

• 쓰기 측 절감 – 10개의 일반적인 코딩 프롬프트에서 스킬은 출력 토큰을 평균 1,214에서 294로 줄여 65% 절감을 달성했습니다.
• 읽기 측 절감 – 54회 실행된 Claude Code 벤치마크에서 프록시는 입력 토큰을 885,793에서 591,673으로 줄여 전체적으로 33% 절감을 보였습니다(순수 HTML 페이지와 같은 일부 경우에는 약간의 증가가 있었습니다).
• 압축 비율 – JSON 페이로드는 70-90%, 로그는 85-95%, 코드는 40-70%, diff는 60-80% 줄어듭니다.

설치

1. 스킬만 – skills CLI를 통한 한 줄 설치:

   npx skills add JuliusBrussee/caveman
   

   그런 다음 에이전트 내에서 /caveman을 호출하거나(에이전트가 자동으로 로드하지 않는 경우 /caveman을 입력합니다).
2. 프록시 – 전역 npm 설치 및 설정:

   npm install -g @caveman-ai/cli && caveman setup --install
   caveman claude   # 또는 codex, gemini 등
   

   macOS/Linux(install.sh) 및 Windows PowerShell(install.ps1)용 전체 설치 스크립트도 제공됩니다.

일반적인 작업 흐름

1. caveman <agent>(또는 caveman wrap <agent>)를 실행하여 프록시가 활성화된 상태에서 선택한 코딩 어시스턴트를 시작합니다.
2. 에이전트가 LLM에 도움을 요청하면 프록시가 업스트림으로 보내기 전에 큰 컨텍스트(로그, diff, JSON)를 압축합니다.
3. LLM의 응답은 스킬에 의해 후처리되어 코드는 그대로 두고 장황한 설명을 간결한 문장으로 바꿉니다.
4. 다음과 같은 도우미 명령을 사용하세요:
   • /caveman-commit – 간결한 Conventional Commit 메시지
   • /caveman-review – 한 줄 코드 리뷰 노트
   • caveman compress <file> – 로컬에서 큰 마크다운 파일 축소
   • caveman stats – 현재 세션의 토큰 사용 통계 보기
   • caveman learn – 디스크의 과거 세션을 분석하고 토큰 낭비가 발생하는 위치를 제안합니다.

왜 원할까요?

• 비용 절감 – 토큰당 비용을 지불하는 경우(예: Anthropic, OpenAI), 입력과 출력을 모두 줄이면 특히 큰 로그나 diff가 포함된 장기 실행 디버깅 세션에서 청구서를 눈에 띄게 낮출 수 있습니다.
• 속도 – 페이로드가 작을수록 전송되는 데이터가 줄어들고 왕복 시간이 빨라집니다.
• 개인정보 보호 – 프록시는 원본 데이터를 로컬에 저장합니다. 압축된 버전만 제공자에게 전송됩니다.

주의 사항 / 제한 사항

• 스킬은 산문만 줄입니다. 모델의 추론이나 프록시가 압축할 수 없는 입력 컨텍스트에 사용되는 토큰은 줄이지 않습니다.
• 압축은 턴당 약 1-1.5k 입력 토큰의 오버헤드를 추가하므로 이미 간결한 상호작용에서는 절감 효과가 상쇄될 수 있습니다.
• 특정 페이로드 유형(예: 순수 HTML)은 압축기가 줄일 부분이 거의 없어 순 증가가 발생할 수 있습니다.
• 이 도구는 "래퍼"입니다. 기본 에이전트의 코드를 수정하지 않지만 각 지원 에이전트에 대해 Node 22+ 및 호환 가능한 CLI가 필요합니다.
• README는 토큰 절감 주장이 벤치마크임을 명시합니다. 실제 절감 효과는 다양하며 caveman stats 또는 맞춤 A/B 테스트로 측정해야 합니다.

라이선스 – 스킬 구성 요소는 MIT 라이선스로 평생 무료입니다. 프록시 런타임은 MIT + BSL-1.1 이중 라이선스입니다.

---

위의 모든 세부 사항은 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추론되지 않았습니다.