---
title: "ColGREP: 터미널과 코딩 에이전트를 위한 의미 기반 코드 검색 도구"
published: 2026-02-12T23:54:44.000Z
canonical: https://jeff.news/article/731
---
# ColGREP: 터미널과 코딩 에이전트를 위한 의미 기반 코드 검색 도구

ColBERT 멀티벡터 임베딩과 Tree-sitter AST 파싱을 결합해 코드의 의미를 이해하는 로컬 검색 도구. 17M 파라미터 경량 모델로 CPU에서 동작하며, grep 호환 플래그와 Claude Code/Codex 통합을 제공함.

## 핵심 아이디어

- 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은 첫 사용 시 자동 다운로드됨

> [!TIP]
> `colgrep init`으로 인덱스를 미리 빌드해두면 첫 검색이 즉시 응답함. CI/CD 파이프라인이나 dev setup 스크립트에 넣어두면 편리함.

## 핵심 포인트

- semantic/keyword/hybrid/regex 4가지 검색 모드 제공, 기본은 ColBERT + FTS5 trigram을 RRF로 합산하는 하이브리드
- ColBERT 멀티벡터 임베딩(토큰당 128차원 벡터)으로 단일 벡터 대비 세밀한 코드 검색 가능
- Tree-sitter로 AST 파싱 후 시그니처/콜그래프/제어흐름/데이터흐름/의존성 5단계 분석
- PLAID 알고리즘으로 2-bit/4-bit 양자화 압축, 증분 인덱스 업데이트 지원
- Claude Code, Codex, OpenCode에 원커맨드 통합, 20개 이상 언어 지원

## 인사이트

코딩 에이전트의 코드 검색 품질이 곧 에이전트의 성능 천장을 결정하는 시대. grep/ripgrep의 패턴 매칭 한계를 의미 검색으로 넘어서면서도 로컬 실행과 grep 호환성을 유지한 것이 실용적인 접근임.