cocoindex-io/cocoindex-code

코드베이스를 위한 가볍고 효과적인 (AST 기반) 시맨틱 코드 검색 (semantic code search) 도구입니다. Rust 기반의 초고성능 데이터 변환 엔진인 CocoIndex를 기반으로 구축되었습니다. CLI에서 사용하거나, Skill 또는 MCP를 통해 Claude, Codex, Cursor 등 모든 코딩 에이전트와 통합할 수 있습니다.

• 토큰 사용량을 즉각적으로 70% 절감합니다.
• 1분 설정— 설치 후 바로 사용 가능하며, 별도의 설정이 필요 없습니다!

🌟 이 프로젝트가 마음에 드신다면 CocoIndex에 Star를 눌러 도와주세요!

Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский | 中文

pipx 사용 시:

pipx install 'cocoindex-code[full]' # 모든 기능 포함 (로컬 임베딩 (local embeddings))
pipx upgrade cocoindex-code # 업그레이드

uv 사용 시:

uv tool install --upgrade 'cocoindex-code[full]'

두 가지 설치 스타일은 동일한 이름의 Docker 이미지 변형을 반영합니다:

cocoindex-code[full]

— 모든 기능 포함 (batteries-included). sentence-transformers를 가져오므로 로컬 임베딩 (local embeddings, API 키 불필요)이 즉시 작동합니다. ccc init 대화형 프롬프트의 기본값은 Snowflake/snowflake-arctic-embed-xs입니다.

cocoindex-code (slim) — LiteLLM 전용. 클라우드 임베딩 제공업체와 API 키가 필요합니다. 로컬 임베딩 의존성(약 1GB의 torch + transformers)을 원하지 않을 때 사용하세요.

다음으로, 코딩 에이전트 통합을 설정하거나, 직접 제어를 선호한다면 수동 CLI 사용법으로 넘어가세요.

코딩 에이전트가 필요할 때 자동으로 시맨틱 검색 (semantic search)을 사용하도록 ccc skill을 설치하세요:

npx skills add cocoindex-io/cocoindex-code

이것으로 끝입니다 — ccc init이나 ccc index가 필요하지 않습니다. 이 skill은 에이전트가 초기화, 인덱싱(indexing) 및 검색을 스스로 처리하도록 학습시킵니다. 작업하는 동안 인덱스를 자동으로 최신 상태로 유지합니다.

에이전트는 도움이 될 만한 상황에서 자동으로 시맨틱 검색을 사용합니다. 또한 명시적으로 유도할 수도 있습니다. 단순히 코드베이스를 검색해 달라고 요청하거나(예: *

Claude Code 사용자에게 이 저장소는 플러그인 마켓플레이스(plugin marketplace)이기도 합니다. Claude Code 내부에서 다음 명령어로 스킬(skill)을 설치할 수 있습니다:

/plugin marketplace add Roxabi/cocoindex-code
/plugin install cocoindex-code@cocoindex-code

이를 통해 동일한 ccc 스킬을 버전 고정(version pinning)과 함께 번들로 제공하며, 업데이트를 위해 /plugin marketplace update를 사용할 수 있습니다.

또는 ccc mcp를 사용하여 MCP 서버로 실행할 수도 있습니다:

Claude Code

claude mcp add cocoindex-code -- ccc mcp

Codex

codex mcp add cocoindex-code -- ccc mcp

OpenCode

opencode mcp add

MCP 서버 이름 입력: cocoindex-code

MCP 서버 유형 선택: local

실행할 명령 입력: ccc mcp

또는 opencode.json을 사용하세요:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
...

설정이 완료되면, 에이전트(agent)는 설명으로 코드를 찾거나, 익숙하지 않은 코드베이스를 탐색하거나, 퍼지/개념적 매칭(fuzzy/conceptual matches)을 수행하거나, 정확한 이름을 모르는 상태에서 구현부를 찾는 등 시맨틱 코드 검색(semantic code search)이 도움이 되는 시점을 자동으로 결정합니다.

참고: 하위 명령어가 없는 cocoindex-code 명령어는 하위 호환성을 위해 여전히 MCP 서버로 작동합니다. 첫 실행 시 환경 변수(environment variables)로부터 설정을 자동으로 생성합니다.

MCP 도구 참조 (MCP Tool Reference)

MCP 서버(ccc mcp)로 실행할 때, 다음 도구가 노출됩니다:

** search** — 시맨틱 유사도(semantic similarity)를 사용하여 코드베이스를 검색합니다.

search(
query: str, # 자연어 쿼리 또는 코드 스니펫
limit: int = 5, # 최대 결과 수 (1-100)
...

파일 경로, 언어, 코드 내용, 줄 번호 및 유사도 점수(similarity score)와 함께 일치하는 코드 청크(code chunks)를 반환합니다.

CLI를 직접 사용할 수도 있습니다. 이는 수동 제어, 설정 변경 후 인덱싱 실행, 상태 확인 또는 에이전트 외부에서 검색할 때 유용합니다.

ccc init # 프로젝트 초기화 (설정 생성)
ccc index # 인덱스 구축
ccc search "authentication logic" # 검색!

백그라운드 데몬(background daemon)은 첫 사용 시 자동으로 시작됩니다.

팁: ccc init을 아직 실행하지 않았다면 ccc index가 자동으로 초기화하므로, 바로 인덱싱 단계로 넘어갈 수 있습니다.

명령 (Command)	설명 (Description)
ccc init	프로젝트 초기화 — 설정 파일을 생성하고, .gitignore에 .cocoindex_code/를 추가합니다.
ccc index	인덱스(index)를 빌드하거나 업데이트합니다 (필요 시 자동 초기화). 스트리밍 진행 상황을 보여줍니다.
ccc search <query>	코드베이스 전체에 대한 시맨틱 검색 (Semantic search)
ccc status	인덱스 통계 표시 (청크 수, 파일 수, 언어별 분류)
ccc mcp	stdio 모드에서 MCP 서버로 실행
ccc doctor	진단 실행 — 설정, 데몬 (daemon), 모델, 파일 매칭 및 인덱스 상태를 점검합니다.
ccc reset	인덱스 데이터베이스 삭제. --all 옵션은 설정 파일도 함께 삭제합니다. -f 옵션은 확인 절차를 건너뜁니다.
ccc daemon status	데몬 버전, 가동 시간(uptime) 및 로드된 프로젝트 표시
ccc daemon restart	백그라운드 데몬 재시작
ccc daemon stop	데몬 중지

ccc search database schema # 기본 검색
ccc search --lang python --lang markdown schema # 언어별 필터링
ccc search --path 'src/utils/*' query handler # 경로별 필터링
...

기본적으로 ccc search는 결과를 현재 작업 디렉토리(프로젝트 루트 기준 상대 경로)로 제한합니다. 이를 재정의하려면 --path를 사용하세요.

재현 가능하고 의존성이 없는 설정을 원하는 팀을 위해 Docker 이미지가 제공됩니다. 호스트에 Python, uv, 또는 시스템 의존성을 설치할 필요가 없습니다.

권장되는 방식은 **지속성 컨테이너 (persistent container)**를 사용하는 것입니다. 컨테이너를 한 번 시작한 후, docker exec를 사용하여 CLI 명령을 실행하거나 MCP 세션을 연결하세요. 내부의 데몬은 세션 간에도 활성 상태를 유지하므로, 임베딩 모델 (embedding model)이 단 한 번만 로드됩니다.

각 릴리스마다 두 가지 변형이 배포됩니다:

| 태그 (Tag) | 크기 (Size) | 임베딩 백엔드 (Embedding backends) | 선택 기준 |
|---|---|---| |
cocoindex/cocoindex-code:latest (slim, 기본값) | ~450 MB | LiteLLM (클라우드: OpenAI, Voyage, Gemini, Ollama, …) | 대부분의 사용자. 클라우드 기반 임베딩, 작은 이미지 크기, 빠른 다운로드. |
cocoindex/cocoindex-code:full | ~5 GB | sentence-transformers (로컬) + LiteLLM | API 키 없이 로컬 임베딩을 사용하거나, 오프라인 환경용 컨테이너가 필요한 경우. torch + transformers로 인해 용량이 더 큽니다. |

이 섹션의 나머지 부분은 :latest를 사용합니다.

전체 변체 (full variant)를 원하는 경우, image: 및 docker run 명령에서 :latest를 :full로 대체하세요.

로컬 임베딩 추론을 실행하는 Mac 사용자의 경우, macOS의 Docker는 Apple의 Metal (MPS) GPU에 접근할 수 없기 때문에 Docker 내부에서는 CPU 전용으로 동작합니다. 로컬 임베딩과 빠른 추론을 원한다면 대신 네이티브로 설치하세요: :full 변체: pipx install 'cocoindex-code[full]'.
:latest (slim) 변체는 영향을 받지 않습니다. LiteLLM은 모델을 제공자(provider) 측에서 실행하므로, Docker 사용 여부와 네이티브 사용 여부는 차이가 없습니다.

클론(clone) 없이 한 줄로 실행하세요 (bash / zsh):

# macOS / Windows
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d
# Linux (바인드 마운트된 경로의 파일 소유권을 호스트 사용자와 일치시킴)
...

또는 docker/docker-compose.yml을 가져와서 그 옆에서 docker compose up -d를 실행하세요 (Windows cmd / PowerShell을 포함한 모든 셸에서 작동합니다).

기본적으로 홈 디렉토리가 컨테이너 내부로 마운트됩니다 (COCOINDEX_HOST_WORKSPACE를 설정하여 이를 특정 코드 폴더로 제한할 수 있습니다). 인덱스 데이터와 임베딩 모델 캐시는 재시작 시에도 Docker 볼륨(volume)에 유지됩니다. $HOME/.cocoindex_code/global_settings.yml에 있는 글로벌 설정 파일은 호스트에서 확인 및 편집이 가능하며, 편집 사항은 다음 ccc 명령 시 적용됩니다.

다른 이미지를 선택하려면 COCOINDEX_CODE_IMAGE를 설정하여 기본값을 재정의하세요. 예를 들어, :full 변체를 사용하거나:
GHCR:COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d
COCOINDEX_CODE_IMAGE=ghcr.io/cocoindex-io/cocoindex-code:latest docker compose up -d

Docker Desktop (macOS / Windows)

docker run -d --name cocoindex-code \
--volume "$HOME:/workspace" \
--volume cocoindex-data:/var/cocoindex \
...

Linux (PUID / PGID 포함)

docker run -d --name cocoindex-code \
-e PUID=$(id -u) -e PGID=$(id -g) \
--volume "$HOME:/workspace" \
...

ccc를 사용할 수 있도록 이 내용을 ~/.bashrc / ~/.zshrc에 붙여넣으세요.

호스트에서 네이티브하게 작동하는 느낌을 주며,
현재 디렉토리를 기반으로 올바른 프로젝트를 선택합니다:

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

이제 워크스페이스 하위의 어떤 프로젝트로든 cd 하여
ccc init,
ccc index,
ccc search ...,
ccc status 등을 실행하세요. — 그냥 바로 작동합니다.

Claude Code

$PWD가 해당 위치를 가리키도록 대상 프로젝트 내부에서 MCP를 등록하세요:

claude mcp add cocoindex-code -- docker exec -i \
-e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

또는 .mcp.json을 통해 등록할 수 있습니다:

{
"mcpServers": {
"cocoindex-code": {
...

참고: -i를 사용하세요 (-it가 아님). -t 플래그는 터미널을 할당하는데, 이는 stdin/stdout을 통한 MCP의 JSON 메시징을 방해합니다. ccc init과 같은 대화형 ccc 명령에만 -t를 추가하세요.

Codex

codex mcp add cocoindex-code -- docker exec -i \
-e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

이전 이미지들은 cocoindex-db와 cocoindex-model-cache 볼륨(volume)을 별도로 사용했습니다. 현재 이미지는 이를 하나의 cocoindex-data 볼륨으로 통합했습니다. 새 이미지를 가져오기(pull) 전에 기존 컨테이너와 볼륨을 삭제하세요. 인덱스(indexes)는 다음 ccc index 실행 시 다시 구축되며, 임베딩 모델(embedding model)은 첫 실행 시 자동으로 다시 채워집니다:

docker rm -f cocoindex-code
docker volume rm cocoindex-db cocoindex-model-cache

-e를 사용하여 docker run 또는 compose에 설정을 전달하세요:

# 추가 확장 기능 (예: Typesafe Config, SBT 빌드 파일)
-e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"
# 빌드 결과물 제외 (Scala/SBT 예시)
...

보안 참고 사항: $HOME을 마운트(mounting)하면 컨테이너가 그 하위의 모든 항목에 대해 읽기/쓰기 권한을 갖게 됩니다. 권한 범위가 너무 넓다면, 대신 더 좁은 디렉토리를 바인드 마운트(bind-mount) 하세요 (COCOINDEX_HOST_WORKSPACE=/path/to/code).

docker build -t cocoindex-code:local -f docker/Dockerfile .

시맨틱 코드 검색 (Semantic Code Search): grep이 잘 작동하지 않을 때 자연어 쿼리를 사용하여 관련 코드를 찾고, 토큰을 즉시 절약합니다.
초고성능 (Ultra Performant): ⚡ 초고성능 Rust 인덱싱 엔진을 기반으로 구축되었습니다. 변경된 파일만 다시 인덱싱하여 빠른 업데이트를 지원합니다.
다국어 지원 (Multi-Language Support): Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell 등을 지원합니다.
임베디드 (Embedded): 휴대 가능하며 별도의 데이터베이스 설정 없이 바로 작동합니다!
유연한 임베딩 (Flexible Embeddings): [full] 옵션을 통해 로컬 SentenceTransformers (무료, API 키 불필요!)를 사용하거나, LiteLLM을 통해 100개 이상의 클라우드 제공업체를 사용할 수 있습니다.

임베딩 모델을 선택하고 구성하는 방법에 대한 자세한 가이드는 EMBEDDINGS.md를 참조하세요.

설정은 두 개의 YAML 파일에 저장되며, 두 파일 모두 ccc init에 의해 자동으로 생성됩니다.

모든 프로젝트에서 공유됩니다. 데몬 (daemon)을 위한 임베딩 모델 및 환경 변수를 제어합니다.

embedding:
  provider: sentence-transformers # 또는 "litellm"
  model: Snowflake/snowflake-arctic-embed-xs
...

참고: 데몬은 사용자의 셸 환경을 상속받습니다. 만약 API 키(예: OPENAI_API_KEY)가 이미 환경 변수로 설정되어 있다면, envs에 중복해서 작성할 필요가 없습니다. envs 필드는 환경 변수에 없는 값들을 위해서만 사용됩니다.

사용자 정의 위치: global_settings.yml을 ~/.cocoindex_code/가 아닌 다른 곳에 배치하려면 COCOINDEX_CODE_DIR을 설정하세요. 이는 파일을 프로젝트와 함께 두고 싶을 때(예: 동기화된 폴더) 유용합니다.

일부 임베딩 모델은 문서와 쿼리에 대해 서로 다른 모드를 노출합니다 (비대칭 검색 (asymmetric retrieval)). 예를 들어, Cohere의 v3 모델은 코퍼스(corpus) 콘텐츠를 임베딩할 때는 input_type: search_document를, 사용자 쿼리를 임베딩할 때는 input_type: search_query를 요구합니다. 여러 SentenceTransformers 모델은 동일한 목적으로 prompt_name: passage / prompt_name: query를 사용합니다. 이러한 설정값들은 indexing_params 및 query_params 아래에 위치합니다:

embedding:
  provider: litellm
  model: cohere/embed-english-v3.0
...

ccc init

인식 가능한 모델들에 대해 이를 자동으로 채워줍니다. 여기에는 모든 Cohere v3, Voyage, Nvidia NIM, Gemini 임베딩 (gemini/gemini-embedding-*, gemini/text-embedding-*, gemini/embedding-* — LiteLLM은 input_type을 Gemini의 task_type으로 자동 매핑합니다), nomic-ai/CodeRankEmbed, nomic-ai/nomic-embed-code, nomic-ai/nomic-embed-text-v1/v1.5, mixedbread-ai/mxbai-embed-large-v1, 그리고 Snowflake/snowflake-arctic-embed-* 제품군이 포함되며, 선택된 기본값(defaults)을 출력합니다. 다른 모델의 경우, embedding: 아래에 주석 처리된 템플릿을 남겨두어 사용자가 직접 채울 수 있도록 합니다.

OpenAI 임베딩 (text-embedding-3-*, text-embedding-ada-002)은 의도적으로 목록에 포함되지 않았습니다. 이들은 대칭적(symmetric)이며 그에 상응하는 조절 노브(knob)가 없기 때문입니다.

허용되는 키(Accepted keys): prompt_name (sentence-transformers) 및 input_type