caveman 쓰는 법

Caveman(JuliusBrussee/caveman)은 코딩 에이전트가 쓰는 토큰을 줄이는 도구다. 에이전트가 말하는 문장을 짧게 만드는 무료 MIT 스킬, 에이전트가 읽는 로그·JSON·diff를 줄이는 로컬 프록시(엔진 BSL-1.1 / CLI MIT), 그리고 앱용 미들웨어로 나뉜다. 최신 릴리스 태그 v2.7.0(2026-09-15), GitHub 스타는 작성 시점 API 기준 약 10.8만. 문서 docs.caveman.so · 홈 caveman.so.

이 글은 “caveman 쓰는 법”만 따라간다. 스킬 설치 → 강도(level) → (선택) 프록시 → 확인·되돌리기까지, README·퀵스타트·프록시 문서·LICENSING만 근거로 적는다.

핵심 요약 (TL;DR)

• 무엇인가: 에이전트 출력(말)을 짧게 + 입력(읽기)을 압축해 토큰·비용을 줄이는 스택. 계정·API 키 없이 스킬만으로도 시작 가능.
• 먼저 할 일: npx skills add JuliusBrussee/caveman -g (Claude Code는 플러그인 경로). 세션에서 /caveman → 필요하면 lite/ultra.
• 더 줄이고 싶으면: npm install -g @caveman-ai/cli && caveman setup --install 후 caveman claude(또는 codex/gemini 등)로 로컬 프록시 경유.
• 요구사항(공식): 통합 설치 스크립트는 Node.js 22.13+. 스킬만이면 텍스트 규칙 파일 수준이라 바이너리 불필요.
• 라이선스(공식): 스킬·CLI 등 MIT / 엔진·프록시 등 BSL-1.1(소스 공개, Change Date 후 Apache-2.0). 전체를 “완전 OSI 오픈소스”라고 부르지 말 것.

할 수 있는 일

먼저 용어만 짧게 풀어 둔다.

• 토큰(token): LLM이 읽고 쓰는 비용 단위. 청구·컨텍스트 한도는 보통 토큰 수로 센다.
• 스킬(skill): 에이전트에 붙는 규칙·지침 파일. Caveman 스킬은 “짧게 말하라”는 말투를 주입한다. 계정·바이너리 없이 텍스트만으로 동작한다.
• 프록시(proxy): 에이전트와 모델 API 사이에 두는 로컬 중계. 기본 주소 127.0.0.1:8787. 로그·테스트 출력·JSON·diff 등 읽는 내용을 줄이고, 원문은 로컬에 보관한다.
• 하네스(harness): 에이전트를 감싸 실행 경로·측정을 고정하는 실행 틀. TWMS 표기는 하네스.
• MCP(Model Context Protocol): 에이전트가 외부 도구·서버와 말하는 표준 연결. Caveman은 압축한 조각을 다시 꺼내는 retrieve 도구 등을 MCP로 붙일 수 있다.
• 미들웨어(middleware): 직접 만든 앱/에이전트 코드에서 한 번의 API 호출을 감싸 같은 압축을 적용하는 라이브러리(@caveman-ai/middleware, alpha).

공식 README·docs 기준으로 바로 할 수 있는 일은 대략 이렇다.

• 에이전트 답을 짧게: 서론·군더더기 없이 핵심만. 코드·경로·에러 문자열은 바이트 그대로 두고 주변 산문만 줄인다. 퀵스타트 예시로는 같은 질문이 69 토큰 → 19 토큰.
• 강도 조절: /caveman lite(짧지만 예의), 기본 full, /caveman ultra(거의 웅얼거림), wenyan-*(문언체 변형).
• 읽는 쪽도 압축(프록시): 터미널 에이전트를 caveman claude 등으로 감싸면 도구 출력·로그가 프로바이더에 가기 전에 줄어든다. 원문은 로컬 SQLite 등으로 복구 가능.
• 커밋·리뷰 단축: /caveman-commit, /caveman-review처럼 한 줄 단위 워크플로 명령.
• 메모리 파일 압축: /caveman-compress CLAUDE.md — 제목·경로·명령은 유지하고 산문만 줄이며 원본 백업.
• 앱에 붙이기: npm install @caveman-ai/middleware @caveman-ai/sdk 후 기존 프레임워크 호출을 한 겹 감싼다(공식 문서 기준 alpha).

필요한 것

링크: GitHub · Quickstart · Proxy · INSTALL.md · LICENSING.md · npm @caveman-ai/cli.

단계

1) 스킬 설치 (가장 먼저)

Claude Code — 플러그인이 모드 추적 훅까지 연결한다.

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

그 외 대부분의 에이전트 — skills CLI:

npx skills add JuliusBrussee/caveman -g

-g는 사용자(글로벌) 스킬 디렉터리. 빼면 현재 프로젝트에만 설치된다. JetBrains Junie 예: npx skills add JuliusBrussee/caveman -a junie -g. 에이전트별 표는 INSTALL.md.

원하면 통합 설치(감지된 에이전트 일괄, Node 22.13+):

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.7.0/install.sh | bash
# 미리보기: … | bash -s -- --dry-run

파이프 실행이 불편하면 받아 읽고 bash install.sh. Windows는 같은 태그의 install.ps1.

2) 켜고, 강도 고르기

새 세션을 연 뒤 질문이 짧아지지 않으면 /caveman. 강도:

• /caveman lite — 짧지만 예의 있음
• /caveman / full — 기본
• /caveman ultra — 거의 짧은 조각
• /caveman wenyan 및 wenyan-lite/wenyan-full/wenyan-ultra — 문언체 변형

끄기(세션): stop caveman / normal mode / /caveman off.

3) (선택) 로컬 프록시 — 읽는 쪽 줄이기

npm install -g @caveman-ai/cli
caveman setup --install
caveman claude    # 또는: caveman codex / caveman gemini / caveman aider / …

caveman <agent>는 통합을 심고, 프록시가 없으면 띄운 뒤, 에이전트의 프로바이더 base URL을 로컬 프록시로 돌린다. 한 세션만이면 caveman wrap <agent>. 직접 띄우려면:

caveman start
curl -s http://127.0.0.1:8787/health/live

앱 코드용으로는 같은 런타임에 미들웨어를 붙이거나 SDK의 baseURL을 http://127.0.0.1:8787/…로 바꾼다. 자세한 경로는 Proxy 문서.

4) 확인

Claude 플러그인:

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"
# 기대 예: full

skills CLI 설치:

ls ~/.claude/skills/caveman

프록시 쪽은 caveman stats, Claude Code 안에서는 /caveman-stats(세션 기록; 절감액은 측정 비교 없으면 미지라고 문서가 명시).

5) 되돌리기 / 제거

claude plugin uninstall caveman@caveman   # 플러그인
npx skills remove caveman                 # skills CLI
npx -y github:JuliusBrussee/caveman -- --uninstall   # 통합 설치가 남긴 훅·라우팅
# 프록시 CLI를 지울 때는 위 uninstall을 먼저(문서: caveman disable 필요)

막히는 지점

마치며

Caveman은 농담에서 시작해, 스킬(말 줄이기)과 프록시(읽기 줄이기)로 갈라진 실용 도구다. 오늘은 npx skills add JuliusBrussee/caveman -g(또는 Claude 플러그인)로 스킬만 켜 보고, 청구서에서 “읽기”가 크면 @caveman-ai/cli 프록시로 한 단계 올리면 된다. 수치는 환경마다 다르니, 문서가 권하듯 자기 워크로드에서 caveman trial로 재는 편이 안전하다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.