cocoindex-io/cocoindex-code

cocoindex-code – AST 기반 의미론적 코드 검색

정의 – 소스 파일의 추상 구문 트리(AST)에서 인덱스를 구축하고 자연어 질의로 관련 코드 스니펫을 반환하는 경량 명령줄 도구(및 플러그인)입니다. Rust 기반 CocoIndex 엔진을 사용합니다.

중요성 – 코드 구조를 이해하므로 식별자나 형식이 다르더라도 일치 항목을 찾을 수 있어, 코드를 조회해야 하는 LLM 기반 에이전트의 토큰 사용량을 최대 ~70% 절약할 수 있습니다.

---

주요 기능(README에 설명됨)

• AST 기반 의미론적 검색 – 원시 텍스트뿐만 아니라 코드 구조를 인덱싱합니다.
• 두 가지 설치 변형:
  • cocoindex-code[full] – 로컬 sentence-transformers 모델 포함(API 키 불필요).
  • cocoindex-code(슬림) – LiteLLM 클라우드 공급자를 사용한 임베딩.
• 1분 제로 구성 설정 – ccc init(또는 스킬)이 자동으로 기본값을 생성합니다.
• CLI 명령 – ccc init, ccc index, ccc search, ccc grep(구조 패턴 검색), 상태, 진단, 데몬 제어 등.
• 에이전트 통합 – 스킬(ccc) 및 선택적 훅과 MCP 서버를 제공하여 Claude Code, Grok, Oh My Pi, Codex, OpenCode, Kilo Code 등에서 사용할 수 있습니다.
• Docker 이미지 – cocoindex/cocoindex-code:latest(슬림, 클라우드 임베딩) 및 :full(로컬 임베딩)로 재현 가능하고 종속성 없는 배포를 지원합니다.
• MCP 도구 – 쿼리, 결과 수, 언어/경로 필터, 선택적 인덱스 새로 고침 매개변수가 있는 search 도구를 노출합니다.
• 구조 검색(ccc grep) – 인덱스 없이 동일한 AST 엔진을 사용한 예제 기반 패턴 매칭.

---

빠른 시작(CLI)

# pipx로 설치(전체 변형에는 로컬 임베딩 포함)
pipx install 'cocoindex-code[full]'
# 또는 슬림 변형
pipx install cocoindex-code

# 프로젝트 초기화(.cocoindex_code/settings.yml 생성)
ccc init
# 인덱스 구축(백그라운드 데몬 자동 실행)
ccc index
# 설명으로 검색
ccc search "authentication logic"

도구는 첫 사용 시 자동 초기화되며, 데몬이 인덱스를 웜 상태로 유지합니다.

---

에이전트/플러그인 사용법

1. 스킬(권장) – 코딩 에이전트에 스킬 추가:

   npx skills add cocoindex-io/cocoindex-code
   

   에이전트는 ccc init, ccc index, ccc search를 자체적으로 실행하고 파일 편집 시 인덱스를 업데이트합니다.
2. Claude Code – Claude의 플러그인 마켓플레이스를 통해 설치(/plugin marketplace add …).
3. Grok – 스킬, 세션 시작/도구 사용 후 훅(자동 인덱스), MCP 서버(ccc mcp)가 포함된 플러그인 설치.
4. Oh My Pi – 유사한 설치 경로; 플러그인은 증분 인덱싱을 위한 TypeScript 훅도 제공합니다.
5. MCP 서버 – ccc mcp를 실행하고 MCP를 지원하는 모든 에이전트(Claude, Codex, OpenCode, Kilo 등)에 등록. 노출된 search 도구는 자연어 쿼리와 선택적 필터를 허용합니다.

---

Docker 배포

# 모든 OS에서 한 줄 명령(GitHub에서 compose 파일 가져옴)
# macOS / Windows
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/main/docker/docker-compose.yml) up -d
# Linux(파일 소유권 보존)
PUID=$(id -u) PGID=$(id -g) docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/main/docker/docker-compose.yml) up -d

컨테이너는 데몬을 실행하고 인덱스 데이터를 Docker 볼륨에 저장합니다. 셸 래퍼를 사용하여 ccc 명령을 컨테이너로 전달할 수 있습니다:

ccc() { docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"; }

---

어떤 변형을 사용해야 하나요?

변형	크기	임베딩 소스	최적 용도
cocoindex-code:latest(슬림)	~450MB	LiteLLM 클라우드 제공업체(OpenAI, Gemini 등)	대부분의 사용자, 최소 이미지, 모든 API 키로 작동
cocoindex-code:full	~5GB	로컬 sentence-transformers 모델(예: snowflake-arctic-embed-xs)	오프라인 환경 또는 API 키 노출을 피하려는 경우

---

TL;DR

• pipx install 'cocoindex-code[full]'(또는 슬림 변형)로 설치.
• ccc init && ccc index를 한 번 실행.
• ccc search "…"로 검색하거나 코딩 에이전트가 ccc 스킬/MCP를 호출하도록 허용.
• 팀 전체 재현 가능한 설정을 위한 선택적 Docker 이미지.

이 프로젝트는 의미론적 코드 검색을 위한 진정한 오픈소스 AI 기반 도구로, 최신 LLM 코딩 어시스턴트와 긴밀하게 통합되어 있습니다.