TL;DR

  • CaveCode는 대규모 코드베이스와 다중 파일 에이전트 작업에서 소스 코드의 불필요한 토큰을 압축해 입력 토큰을 추정치 기준 80~85% 이상 줄이는 도구임.
  • ultra, medium, lite 세 가지 압축 모드가 각각 구조·시그니처, 압축 구문, 전체 함수 본문과 로직을 보존함.
  • 9개 프로그래밍 언어에 전용 추상 구문 트리(AST) 파서와 구문 변환기를 제공하며, 마크업·설정 파일은 변경 없이 통과시킴.
  • 압축 출력은 에이전트용 정보 표현이며 실행 가능한 소스 코드가 아니므로, 실제 편집·디버깅·패치는 원본 파일에서 수행해야 함.
  • cavecode read, compress, revert, estimate, verify 명령으로 코드 읽기, 압축 파일 생성·정리, 토큰 추정, 원본 무결성 확인을 지원함.

CaveCode 소개

  • 대형 언어 모델(LLM)과 AI 코딩 에이전트는 상용구, 반복 구문, 장황한 형식을 읽는 데 많은 토큰을 소비함.
  • CaveCode는 에이전트에 코드를 전달하기 전에 불필요한 토큰을 제거하면서 핵심 정보를 보존하며, 토큰 절감량은 모두 추정치임.
  • 주요 기능은 브라우저에서 압축 모드를 시험하는 웹 플레이그라운드, 9개 언어의 압축 예시를 모은 쇼케이스, AI 코딩 에이전트용 AGENT.md 문서임.
  • 압축 결과는 에이전트가 참고하는 정보 표현이지 실행 가능한 소스 코드가 아니며, 에이전트는 원본 소스 파일을 계속 읽고 편집해야 함.

설치

  • pip로 cavecode를 설치하거나, 다음 깃 저장소에서 직접 설치할 수 있음: https://github.com/grimm67123/cavecode.git
  • 저장소를 복제한 뒤 편집 가능한 개발 모드로 설치하는 방법도 제공함.
  • 설치 후 cavecode version 명령으로 설치 여부를 확인함.

압축 모드

  • lite: 추정 토큰 절감률 약 5~10%이며 함수 본문과 코드 로직 전체를 보존함.
  • medium: 추정 절감률 약 15~20%이며 함수 본문을 보존하면서 구문을 압축함.
  • ultra: 추정 절감률 약 80~85% 이상이며 AST 구조, 시그니처, 타입을 유지함. 권장 모드임.

지원 언어

  • 전용 AST 파서와 구문 변환기를 갖춘 9개 언어를 지원함.
  • Python: .py
  • JavaScript: .js, .jsx, .mjs, .cjs
  • TypeScript: .ts, .tsx
  • Rust: .rs
  • Go: .go
  • Java: .java
  • C++: .cpp, .cc, .cxx, .hpp
  • C#: .cs
  • C: .c, .h

AI 에이전트 운영 지침

  • 코드베이스 탐색, 아키텍처 파악, 외부 모듈·클래스·함수의 호출 관계 확인에는 cavecode read를 사용함. ultra는 시그니처·타입·클래스를 보여주며 추정 절감률은 약 80~85% 이상임. 로직을 살펴볼 때는 함수 구현을 보존하는 lite를 사용할 수 있음.
  • cavecode read는 압축된 코드를 표준 출력으로 내보내며 디스크 파일을 수정하지 않음. 파일 하나뿐 아니라 디렉터리 전체도 읽을 수 있음.
  • 코드를 직접 편집하거나 디버깅할 때는 기본 파일 읽기 도구로 원본을 확인해야 함. 정확한 들여쓰기, 바이트 단위 문자열 일치, 실제 줄 번호 확인이 필요하기 때문임.
  • 압축 텍스트를 패치나 차이(diff) 대상으로 사용하지 않음. 공백 정규화와 구문 축약으로 인해 압축 결과의 문자열은 원본 파일에 존재하지 않으므로, 편집·검색 및 치환·통합 차이는 원본 소스 파일을 대상으로 해야 함.
  • -n 옵션의 줄 번호는 압축 출력 스트림 기준이며 원본 파일의 실제 줄 번호가 아님. 이를 자동 패치 도구나 린터에 전달하지 않아야 함.
  • 여러 작업이나 명령 사이에 압축 파일을 디스크에 유지할 필요가 있으면 cavecode compress로 .cave 동반 파일을 생성할 수 있음. 이 파일은 읽기 전용 참고 자료이며 컴파일러, 린터, 테스트 실행기, 디버거는 원본 파일에서만 실행함. 작업이 끝나면 cavecode revert로 정리함.

압축 모드 상세

  • 기본 모드는 ultra이며 --mode 또는 -m 옵션으로 선택함.
  • ultra: 아키텍처와 시그니처를 100% 보존하고 주석·문서 문자열을 제거하며, 함수와 메서드 본문을 pass 또는 { ... } 형태의 구조적 골격으로 축약함. 클래스 계층, 타입 주석, 함수 정의를 유지함. 대규모 저장소 탐색, 아키텍처 파악, 의존성 매핑, 수정하지 않는 파일의 API 계약·매개변수 확인에 적합함.
  • lite: 함수 본문과 로직을 100% 보존함. 문서 문자열과 라이선스 블록을 제거하고 들여쓰기를 두 칸으로 정규화하며 임포트를 압축함. 전체 토큰 사용량을 감수하지 않고 외부 모듈의 알고리즘이나 내부 데이터 흐름을 살펴볼 때 적합함.
  • medium: 함수 본문을 100% 보존함. pub, priv, const 같은 키워드 밀도를 높이고 디버그·정보 로그 호출을 제거하며 주석을 요약함. 상호 의존 파일 여러 개의 로직을 간결하게 훑을 때 적합함.

명령줄 인터페이스

  • cavecode read는 cavecode view, cavecode cat의 별칭을 제공하며, 소스 파일이나 디렉터리를 AST 압축해 표준 출력으로 읽음. 디스크는 수정하지 않음.
  • cavecode read에서 기본 ultra 모드로 파일을 읽거나 -m lite로 함수 구현을 보존할 수 있음. -l 1:50은 압축 출력의 특정 줄 범위를 읽고, -n은 압축 스트림에 줄 번호를 표시함. 디렉터리의 지원 파일도 한 번에 출력할 수 있음.
  • cavecode compress는 파일 또는 디렉터리를 압축해 대상 파일 옆에 <name>.cave.<ext> 동반 파일을 생성하며, 원본 파일은 변경하지 않음.
  • cavecode revert는 파일 또는 디렉터리에서 생성된 .cave 동반 파일을 제거함.
  • cavecode estimate는 별칭 cavecode stats를 제공하며, 파일이나 디렉터리의 추정 토큰 사용량과 절감량을 계산함. 디스크 파일은 생성하지 않음.
  • cavecode verify는 SHA-256 암호학적 검증을 수행해 대상 소스 파일이 수정되지 않았음을 확인함.

언어 지원 및 범위

  • 전용 AST 파서를 제공하는 언어는 Python, JavaScript, TypeScript, Rust, Go, Java, C++, C#, C임.
  • HTML, CSS, JSON, YAML, Markdown 같은 마크업 및 설정 형식에는 AST 구조가 없으므로 그대로 통과시킴. 이 형식에는 일반 파일 읽기 도구를 사용해야 함.