ColGREP: 터미널과 코딩 에이전트를 위한 의미 기반 코드 검색 도구

핵심 아이디어

• grep/ripgrep은 패턴 매칭만 하지만, ColGREP은 코드의 의미를 이해하는 검색을 터미널에서 바로 제공함
• 코드가 외부 서버로 전송되지 않고, 100% 로컬에서 동작함. CPU만으로도 충분히 빠름
• Apache-2.0 라이선스 오픈소스이며, brew install lightonai/tap/colgrep으로 바로 설치 가능

4가지 검색 모드

• semantic: ColBERT 모델 기반 의미 검색. "HTTP 요청 보내는 함수" 같은 자연어 쿼리가 동작함
• keyword: FTS5 trigram 키워드 검색. "parse"를 검색하면 parse_arguments, JSON.parse 등 서브스트링 매칭됨
• hybrid (기본값): semantic + keyword를 RRF(Reciprocal Rank Fusion)로 합산. alpha=0.75로 시맨틱 쪽에 가중치를 둠
• regex: ERE 문법의 정규식 검색. -e 플래그로 사용하며, regex로 후보를 좁힌 뒤 시맨틱으로 랭킹하는 조합도 가능함

ColBERT 멀티벡터 임베딩이 핵심

• 일반적인 임베딩 모델은 코드 단위당 단일 벡터 하나를 생성하지만, ColBERT는 토큰 레벨의 다중 벡터(코드 유닛당 ~300개, 128차원)를 생성함
• 쿼리 시 각 쿼리 토큰이 문서의 모든 토큰 중 가장 유사한 것을 찾는 MaxSim 스코어링 방식을 사용함
• 단일 벡터에서 손실되는 세밀한 정보가 보존되므로, 코드 검색 정확도가 확연히 높아짐
• 기본 모델은 LateOn-Code-edge (17M 파라미터)로, 코드 검색에 최적화된 경량 모델임. CPU에서 돌아감

Tree-sitter 기반 AST 파싱 — 5단계 분석

• Tree-sitter로 소스 파일을 AST 파싱하여 함수, 메서드, 클래스, 상수, raw 코드 블록 단위로 추출함. 파일 커버리지 100%
• 각 코드 유닛에 대해 5개 레이어의 분석을 수행함:
  1. AST: 시그니처, 파라미터, 리턴 타입, 독스트링, 부모 클래스
  2. Call Graph: 나가는 호출(outgoing calls) + 역방향 called_by
  3. Control Flow: 루프, 분기, 에러 핸들링, 순환 복잡도
  4. Data Flow: 변수 선언 및 할당
  5. Dependencies: 함수 내에서 사용되는 임포트
• 이 구조화된 표현을 임베딩하므로 raw 코드만 넣는 것보다 훨씬 풍부한 시그널을 모델에 제공함
• 파일 경로도 정규화됨: HttpClient → http client, snake_case → 분리 처리

PLAID 알고리즘으로 인덱스 압축

• 멀티벡터 임베딩은 용량이 크기 때문에, PLAID 알고리즘으로 product quantization(2-bit 또는 4-bit) 적용하여 압축함
• 임베딩 풀링(기본 factor: 2)으로 인덱스 크기를 추가로 ~50% 줄임
• 메모리 맵(memory-mapped) 인덱스로 저장되어 메모리 효율적임
• 증분 업데이트(incremental updates) 지원: 변경된 파일만 다시 인코딩함. colgrep init으로 프리워밍도 가능

AI 코딩 에이전트 통합

• Claude Code, Codex, OpenCode에 원커맨드로 설치됨: colgrep --install-claude-code
• Claude Code 통합 시 세션/태스크 훅이 설치되어:
  • 에이전트 시스템 프롬프트에 colgrep 사용법이 주입됨
  • 인덱스 상태를 체크하고 (>3000 청크 미인덱스 시 스킵)
  • 서브 에이전트에도 태스크 훅을 통해 전파됨
• 즉, Claude Code가 자동으로 colgrep을 기본 검색 도구로 사용하게 됨

grep 호환 플래그 & 실용적 기능

• -e, -E, -F, -w, -l, -r 등 grep 호환 플래그를 그대로 제공함. 기존 워크플로우 전환 비용이 낮음
• --include, --exclude, --exclude-dir로 glob 필터링 가능
• --json 출력, --code-only(docs/config 제외), --files-only 등 에이전트 친화적 옵션 제공
• 상대 경로 출력 모드로 LLM 사용 시 토큰 ~35% 절약 가능
• 테스트 함수는 쿼리에 "test"가 포함되지 않으면 자동으로 순위가 낮아짐

지원 언어 & 설치

• 20개 이상 프로그래밍 언어 지원: Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, Scala, PHP, Lua, Elixir, Haskell, OCaml, Zig, Julia, SQL, Vue, Svelte 등
• Markdown, YAML, TOML, JSON, Dockerfile, Makefile, Shell 등 설정/문서 파일도 인덱싱됨
• macOS는 Apple Accelerate + CoreML 하드웨어 가속이 기본 활성화됨
• Linux/Windows에서 GPU 가속 원하면 Cargo로 빌드: cargo install colgrep --features openblas (또는 cuda, tensorrt, directml)
• ONNX Runtime은 첫 사용 시 자동 다운로드됨