justrach/codedb

Zig code intelligence server and MCP toolset for AI agents. Fast tree, outline, symbol, search, read, edit, deps, snapshot, and remote GitHub repo queries.

codedb – AI 에이전트를 위한 빠른 코드 지능 서버

무엇인가요 – codedb는 Zig로 작성된 가벼운, 의존성 없이 작동하는 서버로, 로컬 코드베이스(트리그램 전체 텍스트, 역인덱스 단어, 심볼 개요, 호출 그래프, 종속성 그래프 등)에 풍부한 인덱스를 구축합니다. 이 인덱스는 모델 컨텍스트 프로토콜(MCP) 을 통해 노출되며, 이는 AI 기반 코딩 보조 도구(Claude Code, Cursor, Gemini CLI, Codex 등)가 코드에 대한 빠르고 구조화된 컨텍스트를 얻기 위해 호출할 수 있는 JSON-RPC-over-stdio 인터페이스입니다. codedb는 파일을 편집하지 않습니다. 편집은 사용자의 일반 편집기로 남겨둡니다.

주요 기능

여러 언어(Zig, C/C++, Python, Rust, Go 등)에 대한 구조적 인덱싱과 다른 언어에 대한 가벼운 개요 제공.
트리그램 가속 검색과 O(1) 단어 조회.
심볼 조회, 호출 지점 탐지, 호출 경로 계산.
종속성 그래프(임포트 또는 마크다운 링크) 및 최근 변경 추적.
MCP 도구(22개 내장 명령어)로 에이전트가 단일 RPC 호출로 실행할 수 있음.
HTTP 모드(codedb serve)는 MCP가 아닌 클라이언트를 위한 것.
파일 감시기는 인덱스를 증분적으로 최신 상태로 유지(단일 파일 재인덱싱 시간은 2ms 미만).

AI 에이전트에게 왜 중요한가 – 에이전트는 간결하고 토큰 효율적인 컨텍스트가 필요합니다. codedb는 관련된 심볼, 호출자 또는 스니펫만 포함된 구조화된 JSON(또는 일반 텍스트)을 반환하여, 원시 grep/ripgrep 출력에 비해 토큰 사용량을 수백에서 수천 배 줄입니다. 벤치마크 결과에 따르면, 전통적인 도구의 ~55ms CLI 시작 시간과 ~5-7ms 검색 시간에 비해, 쿼리 지연 시간은 밀리초 미만(약 0.05ms)입니다.

설치

macOS / Linux – 적절한 서명된 바이너리를 다운로드하고, 지원되는 AI 코딩 도구에 자동 등록하는 단일 줄 스크립트:
```
curl -fsSL https://codedb.codegraff.com/install.sh | bash
```

Windows – PowerShell 설치 프로그램:

irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5841/install/install.ps1 | iex

npm – codedeebee 패키지는 설치 시 네이티브 바이너리를 다운로드하는 가벼운 런처입니다. CLI 명령어는 여전히 codedb입니다.
모든 바이너리는 SHA-256 검증되며, macOS 빌드는 코드 서명 및 인증 처리되었습니다.

빠른 시작

# MCP 서버 시작 (Claude, Cursor 등과 자동 등록)
codedb mcp /path/to/project

# 또는 단순 HTTP 데몬으로 실행
codedb serve /path/to/project   # localhost:7719에서 리슨

일반적인 에이전트 워크플로우:

트리 – codedb_tree → 심볼 수를 포함한 전체 파일 트리.
개요 – codedb_outline src/main.zig → 라인 번호와 함께 함수/구조체.
심볼 – codedb_find AgentRegistry → 정의 위치.
검색 – codedb_search "handleAuth" → 트리그램 기반 빠른 전체 텍스트 검색.
호출자 / 호출 경로 – codedb_callers 또는 codedb_callpath로 사용 추적.

이 모든 명령어는 HTTP(curl localhost:7719/...) 또는 AI 보조 도구가 사용하는 MCP JSON-RPC 채널을 통해 직접 호출할 수 있습니다.

아키텍처 (고수준)

인덱서 – 시작 시 한 번만 실행되며, 지원되는 언어를 파싱하고 다음을 구축합니다:
- 트리그램 인덱스 (정수 문서 ID, 배치 병합) – 빠른 흐릿한 텍스트 검색을 위해.
- 역인덱스 단어 인덱스 – O(1) 식별자 조회를 위해.
- 구조적 개요 (함수, 구조체, 임포트) – 각 파일별로 저장.
- 종속성 그래프 – 임포트 또는 마크다운 링크를 연결.
스냅샷 – 전체 인덱스를 codedb.snapshot으로 직렬화하여 데몬의 즉각적인 재시작을 가능하게 합니다.
MCP 서버 – stdio 위에 있는 얇은 JSON-RPC 2.0 계층; 각 도구는 사전에 구축된 인덱스를 조합하는 단일 RPC 메서드입니다.
파일 감시기 – 필터링된 디렉터리 탐색을 통해 메모리 내 인덱스를 증분적으로 업데이트; 단일 파일 변경 시 비용은 <2ms입니다.
크로스 플랫폼 – macOS(ARM 및 Intel), Linux(ARM 및 x86_64), Windows용 네이티브 바이너리 제공.

데이터 및 프라이버시

로컬에서만 작동; 공개 GitHub 저장소에 대한 선택적 DeepWiki 원격 MCP를 활성화하지 않는 한 네트워크 트래픽이 없습니다.
HTTP 서버는 기본적으로 localhost에 바인딩되며, 인증 계층은 제공되지 않습니다.
민감한 파일(.env, 키 등)은 인덱싱에서 자동으로 차단됩니다.

누가 사용할 수 있을까?

AI 코딩 보조 도구를 개발하는 개발자 – 빠르고 토큰 효율적인 코드 컨텍스트가 필요합니다.
Claude Code, Cursor, Gemini CLI 또는 유사한 에이전트를 사용하는 팀 – 즉시 사용 가능한 로컬 지식 기반을 원합니다.
코드를 위한 검색 증강 생성(RAG)을 실험하는 연구자.

현재 상태

알파 – API가 안정화 중입니다. 핵심 기능(MCP 도구, 트리그램 검색, 단어 인덱스, 구조적 개요, 종속성 그래프)은 생산 환경에서 사용 가능하며 매일 사용되고 있습니다.
지속적인 작업: 더 깊은 파서 커버리지, 증분 세그먼트 기반 인덱싱, WASM 타겟, 다중 프로젝트 지원, mmap 기반 트리그램 인덱스.

결론 – codedb는 무거운 도구를 포함하지 않고도 AI 에이전트가 코드베이스를 빠르고 구조화된 방식으로 볼 수 있도록 해줍니다. 밀리초 미만의 쿼리 시간과 매우 작은 토큰 사용량은 모든 LLM 기반 코딩 워크플로우에 실용적인 기반을 제공합니다.