BeaconBay/ck

Local first semantic and hybrid BM25 grep / search tool for use by AI and humans!

📦 ck – 의미 기반 코드 검색

ck (읽기: "seek")은 소스 코드를 의미에 따라 검색할 수 있도록 해주는 Rust 기반 명령줄 도구입니다. 단순한 텍스트 일치가 아니라, 개념을 이해하고 검색합니다. 코드의 로컬 임베딩을 생성하고, 인크리멘탈로 캐시하며, 에러 처리나 인증 로직과 같은 키워드가 정확히 포함되지 않아도 관련된 함수, 클래스, 코드 블록을 검색할 수 있습니다.

🎯 기능

기능	제공 기능
의미 기반 검색	벡터 임베딩(BGE‑Small, Mixedbread, Nomic, Jina‑Code 등)을 사용해 코드 개념을 검색합니다.
하이브리드 검색	유사도 점수와 전통적인 정규표현식/키워드 매칭을 Reciprocal Rank Fusion으로 결합합니다.
grep 호환 CLI	`grep`/`ripgrep`와 동일한 플래그(-n, -R, -l 등)를 지원합니다.
인터랙티브 TUI	실시간 결과, 미리보기 모드, 다중 선택, 에디터 통합을 지원하는 전체 화면 터미널 UI입니다.
AI 에이전트(MCP) 서버	Model Context Protocol(MCP)를 통해 `semantic_search`, `regex_search` 등의 도구를 노출하여 Claude Desktop, Cursor 등 에이전트가 프로그래밍 방식으로 호출할 수 있습니다.
인크리멘탈, 청크 단위 인덱싱	변경된 청크만 재임베딩; 일반적인 수정에서 캐시 히트율은 80–90%입니다.
스마트 파일 필터링	`.gitignore`, 전용 `.ckignore`, 명령줄 제외 플래그를 존중합니다.
구조화된 출력	스크립트 및 LLM 파이프라인용으로 `--json`(단일 배열) 또는 `--jsonl`(라인 구분)을 지원합니다.
다중 언어 지원	Python, JavaScript/TypeScript, Rust, Go, C/C++, C#, Ruby, Haskell, Dart, Markdown, 일반 텍스트 형식 등.
오프라인 전용	모든 임베딩 모델은 로컬에서 실행되며, 초기 모델 다운로드 이후 네트워크 트래픽 없음.

⚙️ 작동 방식 (개요)

인덱싱 – ck --index <root>는 소스 트리를 탐색하고, Tree‑sitter를 사용해 언어 인식 청크(함수, 클래스 등)로 분할한 후 FastEmbed로 임베딩을 계산합니다. 인덱스 데이터는 .ck/ 디렉터리(또는 CK_INDEX_DIR로 커스텀)에 저장됩니다.
검색 – 쿼리는 동일한 모델로 임베딩되며, 저장된 벡터와의 유사도 점수가 계산됩니다. 하이브리드 모드에서는 전통적인 정규표현식 검색이 병렬로 실행되고, 두 결과 목록이 병합됩니다.
서빙 – ck --serve는 MCP 서버를 시작하여 검색 도구를 JSON-RPC 엔드포인트로 노출하여 AI 어시스턴트가 직접 호출할 수 있도록 합니다.

🚀 빠른 시작 (CLI)

# crates.io에서 바이너리 설치
cargo install ck-search

# 의미 기반 검색 (첫 실행 시 인덱스 자동 생성)
ck --sem "error handling" src/

# 하이브리드 검색 (의미 + 키워드)
ck --hybrid "connection timeout" src/

# 전통적인 grep 스타일 검색
ck -R "TODO|FIXME" .

# 인터랙티브 터미널 UI
ck --tui "authentication logic"

🤖 AI 에이전트 통합 (MCP)

# 서버 시작
ck --serve

서버는 semantic_search와 같은 도구를 등록하여 에이전트가 호출할 수 있도록 합니다:

{
  "tool": "semantic_search",
  "args": {"query": "authentication logic", "path": "/my/project", "top_k": 25}
}

응답은 JSONL 형식으로 스트리밍되며, LLM 기반 워크플로우에서 쉽게 처리할 수 있습니다.

📚 일반적인 사용 사례

개발자 생산성 향상 – 정확한 식별자를 기억하지 않아도 개념의 구현으로 바로 이동.
코드 리뷰 준비 – 보안에 중요한 패턴을 구현하는 모든 함수 목록 생성.
CI/CD 자동화 – 리포지토리에서 불안전한 패턴 스캔 (ck --json --sem "password|secret" . | my_scanner).
팀 온보딩 – 관련 테스트 파일이나 중복된 로직을 빠르게 찾기.
LLM 강화 도구 – 구조화된 검색 결과를 Claude, Cursor, 또는 사용자 정의 에이전트에 공급.

📦 설치 방법

방법	명령어
Crates.io (권장)	`cargo install ck-search`
소스에서	`git clone https://github.com/BeaconBay/ck && cd ck && cargo install --path ck-cli`
미래의 패키지 매니저	Brew/apt 패키지 계획 중이지만 아직 출시되지 않음.

📄 라이선스

MIT 및 Apache‑2.0 이중 라이선스 (자세한 내용은 LICENSE-MIT / LICENSE-APACHE 참조).

🙏 더 알아보기

전체 문서: https://beaconbay.github.io/ck/
TUI 가이드: 리포지토리 내 TUI.md
모델 선택 및 인덱싱 세부 정보는 README 테이블에 기재됨.

ck는 실제 사용되고 있으며, 지속적으로 유지보수되는 오픈소스 프로젝트로, 익숙한 명령줄 코드 검색에 현대적인 AI 기반 의미 기반 검색을 제공합니다. 오프라인 전용이며, .gitignore를 존중하며, 인간 워크플로우와 AI 에이전트 모두와 원활하게 통합됩니다.