codeindex

AI 코딩 에이전트를 위핸 MCP 서버로 실시되느 구조적 코드 인텔리전스 엔진입니다.

tree-sitter(40+ 언어)로 코드베이스를 인덱싱하고, 트라이그램 전문 텍스트 인덱스, 역방향 단어 인덱스, 의존성 그래프를 구축한 다음, 이를 16가지 MCP 툴로 노출합니다.

 ┌─────────────┐      MCP (stdio)       ┌──────────────┐
 │  AI Agent   │ ◄─────────────────────► │   codeindex  │
 │ (Claude,    │   16 tools, JSON-RPC    │  (Zig binary) │
 │  Cursor…)   │                         │              │
 └─────────────┘                         └──────┬───────┘
                                                │
                                   tree-sitter parse (40+ langs)
                                         trigram + word index
                                         dependency graph
                                         snapshot persistence

Why

AI 코딩 에이전트는 전체 파일을 읽는 데 토큰을 소비합니다. codeindex는 구조적 질문 — 심볼 개요, 정의, 호출자, 전파 범위, 의존성 체인 — 에 대해 수천 개 대신 수백 개 토큰로 답합니다.

plan_change 호출 한 번으로 다음을 반환합니다: 심볼이 정의된 위치, 모든 호출 지점, 파일의 구적 역할(갓 모듈 / 안정 코어 / 아일랜드 / 드라이버), 확인해야 할 하드코딩 리터럴, 그리고 파일 변경 시 전체 전이적 전파 범위.

Related MCP server: OpenCodeHub MCP Server

Quickstart

# Install (prebuilt binary or build from source)
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | bash

# Or build manually:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

AI 에이전트에 등록하세요:

# Claude Code — the plugin is the one-step path. It ships the skill, the hook
# and the MCP server together, and its launcher finds or fetches the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "~/.local/bin/codeindex",
      "args": ["--mcp"]
    }
  }
}

다음에 에이전트가 시작하면, codeindex는 백그라운드에서 프로젝트를 인덱싱하고 구조적 질의에 응답합니다.

MCP Tools

Analyses (analyze tool)

Supported Languages

40+ languages via tree-sitter: Rust, Python, TypeScript/TSX, Go, Zig, C, C++, Java, Ruby, Bash, C#, Kotlin, Lua, Scala, Elixir, R, Swift, Dart, Hasell, TOML, JSON, YAML, HTL, CSS, SCSS, SQL, HCL, Dockerfile, Markdown, Nix, Make, 그 밖에.

Configuration

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

codeindex는 작업 디렉터리에서 위로 올라가며 .git, package.json, Cargo.toml, go.mod, build.zig, pyproject.toml 등을 찾아 프로젝트 루트를 자동 감지합니다.

홈 디렉터리나 파일시스템 루트 전체를 인덱싱하지 않습니다 — 명시적으로 지정하려면 --workspace를 전달하세요.

Architecture

• 파서: 40개 이상의 그램마를 가진 tree-sitter, 단일 바이너리로 컴파일됨

• 인덱스: 퍼지 텍스트 검색용 트라이그램 인덱스 + 정확한 식별자 조회용 역방향 단어 인덱스

• 의존성 그래프: 순방향 및 역방향 에지로 파일 수준 임포트 해석

• 버전 저장소: 증분 업데이트를 위핸 시스 번호로 파일 변경을 추적

• 실시간 감시자: 파일 생성/수정/삭제 시 재인덱싱(MCP 모드에서는 백그라운드 스레드). Linux에서는 inotify, macOS와 Windows에서는 폴링 방식으로 수 초마다 mtime과 크기를 비고합니다. status는 현재 활성 백엔드를 watcher_backend로 보고합니다.

• 스냅샷: 전체 인덱스를 .codeindex.json에 저장하여, 재시작 시 재인덱싱 대신 스냅샷을 로드합니다.

• MCP 서버: stdio를 통한 JSON-RPC, MCP 2024-11-05 프로토콜 구현

Platform support

각 행은 CI에서 빌드되고, 명시된 경우를 제외하고 해당 플랫폼에서 테스트가 실행됩니다. status는 실제 활성 감시자 백엔드를 보고하므로 추측할 필요가 없습니다.

Windows에서 install.sh와 플러그인의 런처는 스크립트이므로 Git Bash, MSYS2 또는 Cygwin이 필요합니다 — 해당 도구를 감지하여 올바른 .exe 자산을 해결합니다. 플러그인은 그 런처를 통핸 서버를 등록하므로, 이 없는 네이티브 Windows Claude Code는 바이너리를 직접 등록해야 합니다:

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

여기 있는 어떤 것도 서명되거나 노타리즈되지 않았습니다. macOS에서 curl로 받은 바이너리는 Gatekeeper 프롬프트 없이 실시됩니다. 브라우저로 다운로드한 파일은 격리되며, xattr -d com.apple.quarantine codeindex로 해제할 수 있습니다.

Building from source

필요 사항: Zig 0.16.0.

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

테스트 실시:

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test는 결과를 빌드 러너의 IPC 프토토콜을 통핸 stdout로 보내는데, 링크된 tree-sitter C 소스가 디버그 printf 경로를 통핸 이를 손상시킵니다. 테스트 바이너리를 빌드하여 직접 실시하는 것은 그 프토토콜이 방해하지 않느 상태에서 같은 테스트를 수행하는 것입니다.

How it compares

Pairs with chat-recall

codeindex는 눈앞의 코드에 대한 질문에 답합니다. **chat-recall**은 이미 수행한 작업에 대한 질문에 답합니다 — Claude Code, Gemini CLI, Codex, OpenCode, Antigravity 세션을 하나의 검색 가능한 기록으로 인덱싱하고 이를 MCP로도 노출합니다.

두 도구는 에이전트가 잊는 두 가지 측면을 모두 다룹니다: codeindex는 개요를 만들 수 있었던 파일을 다시 읽지 않게 하고, chat-recall은 이미 끝낸 작업을 다시 하지 않게 합니다. chat-recall은 PATH에서 codeindex 바이너리를 감지하면 발견 시 코드 인털리전스 도구 4개를 추가로 등록합니다 — 둘 중 하나가 다른 하나를 요구하지는 않습니다.

License

MIT. LICENSE를 참조하세요.