구조적 인덱싱 (Structural indexing) · Trigram 검색 (Trigram search) · 단어 인덱스 (Word index) · 의존성 그래프 (Dependency graph) · 파일 감시 (File watching) · MCP + HTTP

에디터가 아닌, 컨텍스트 엔진 (A context engine, not an editor). codedb는 에이전트가 코드를 찾고 이해하도록 (find and understand) 돕습니다 — 검색, 심볼 (symbols), 호출자 (callers), 의존성 (dependencies), 아웃라인 (outlines) — 그리고 편집 권한은 사용자의 네이티브 도구로 다시 돌려줍니다. codedb_edit은

단지 폴백 (fallback)일 뿐입니다.

상태 (Status) · 설치 (Install) · 빠른 시작 (Quick Start) · MCP 도구 (MCP Tools) · 벤치마크 (Benchmarks) · 아키텍처 (Architecture) · 데이터 및 개인정보 보호 (Data & Privacy) · 빌드 (Building)

알파 소프트웨어 — API가 안정화되고 있으나 변경될 수 있음. codedb는 작동하며 프로덕션 AI 워크플로우에서 매일 사용되고 있지만, 다음과 같은 사항이 있습니다:

파서 (Parser) 지원 — Zig, C/C++, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart/Flutter
경량 아웃라인 (Lightweight outline) 지원 — Java, Kotlin, Svelte, Vue, Astro, shell, CSS/SCSS, SQL, protobuf, Fortran, LLVM IR, MLIR, TableGen
인증 없음 (No auth) — HTTP 서버는 localhost에만 바인딩됨
스냅샷 형식 (Snapshot format) — 버전 간에 변경될 수 있음
MCP 프로토콜 — stdio를 통한 JSON-RPC 2.0 (안정적)

현재 작동하는 것	진행 중인 사항
전체 코드베이스 인텔리전스를 위한 21개의 MCP 도구	더 깊은 파서 커버리지 및 에지 케이스 (edge-case) 처리
...

curl -fsSL https://codedb.codegraff.com/install.sh | bash

사용자의 플랫폼에 맞는 바이너리를 다운로드하고 Claude Code, Codex, Gemini CLI, Cursor, Windsurf, 그리고 Devin에서 codedb를 MCP 서버로 자동 등록합니다 — 각 도구의 설정에 직접적이고 가산적으로 작성됩니다 (해당 도구가 존재할 때만). 설치 프로그램은 등록된 정확한 codedb mcp 명령과 Codex 및 Claude Code를 위한 훅 (hook) 설정 포인터를 출력합니다.

npx -y codedeebee mcp

또는 전역(globally) 설치:

npm install -g codedeebee
codedb mcp

npm 패키지 이름은 codedeebee입니다

(codedb라는 이름은 npm에서 제한되어 있습니다); 이 패키지는 postinstall 단계에서 GitHub Releases로부터 일치하는 네이티브 바이너리를 다운로드하고 SHA256 체크섬을 검증하는 얇은 런처 (thin launcher)를 포함합니다. 설치된 CLI 이름은 여전히 codedb입니다.

이미 npx를 사용하는 MCP 클라이언트 (Claude Code, Cursor, opencode, Claude Desktop)에 유용합니다:

{
"codedb": {
"type": "local",
...

만약 이전 릴리스(release)에서 codedb update가 실패한다면, 설치 프로그램을 다시 실행하세요:

curl -fsSL https://codedb.codegraff.com/install.sh | bash

이 명령은 codedb 바이너리를 최신 GitHub Release로 교체하며, 기존의 MCP 등록 정보, 설정(config), 캐시(caches) 및 스냅샷(snapshots)을 그대로 유지합니다. 내장된 업데이트 도구가 릴리스 체크섬(checksums)을 가져올 수 없는 릴리스의 경우 이 경로를 사용하세요.

MCP 설정 (MCP setup)— 클라이언트별 설정 (Claude Desktop, Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI), 루트 해석(root resolution), 문제 해결(troubleshooting)
기술 베이스 및 컨텍스트 파일 (Skill base & context files)— agents.md, /CLAUDE.md, /GEMINI.md, .codedbrc, 개발자별 메모리(per-developer memory)
CLI 레퍼런스 (CLI reference)— 모든 명령어 및 플래그
아키텍처 (Architecture)— 엔진 내부 구조, 인덱스 레이아웃
벤치마크 (Benchmarks)— 마이크로 벤치마크 + codegraph, FTS5, lean-ctx 대비 에이전트 평가(agentic-eval) 결과

플랫폼 (Platform)	바이너리 (Binary)	서명 여부 (Signed)
macOS ARM64 (Apple Silicon)	codedb-darwin-arm64	✅ 코드 서명(codesigned) + 공증(notarized)
macOS x86_64 (Intel)	codedb-darwin-x86_64	일시적으로 서명되지 않음 (temporarily unsigned)
Linux ARM64	codedb-linux-arm64	—
Linux x86_64	codedb-linux-x86_64	—

또는 GitHub Releases에서 수동으로 설치할 수 있습니다.

설치 후 codedb는 자동으로 등록됩니다. 프로젝트를 열기만 하면 21개의 MCP 도구를 AI 에이전트가 사용할 수 있습니다.

# 수동 MCP 시작 (설치 스크립트에 의해 자동 구성됨)
codedb mcp /path/to/your/project

codedb serve /path/to/your/project
# localhost:7719에서 대기 중

codedb tree /path/to/project # 심볼 개수가 포함된 파일 트리
codedb outline src/main.zig # 파일 내의 심볼(symbols)
codedb find AgentRegistry # 심볼 정의 찾기
...

Model Context Protocol (stdio를 통한 JSON-RPC 2.0)을 통해 21개의 도구를 제공합니다. codedb의 역할은 에이전트에게 컨텍스트를 제공하는 것 — 빠른 구조적 검색, 심볼(symbols), 호출자(callers), 의존성(dependencies) 및 아웃라인(outlines) 제공 — 이지, 사용자의 에디터가 되는 것이 아닙니다. 편집(Editing)은 의도적으로 보조 수단(codedb_edit)으로 설계되었습니다. 가급적 사용 중인 클라이언트의 네이티브 편집 도구를 사용하세요.

도구 (Tool)	설명 (Description)
codedb_tree	언어, 라인 수, 심볼(symbol) 수를 포함한 전체 파일 트리
codedb_outline	파일 내의 심볼: 함수(functions), 구조체(structs), 임포트(imports) 및 라인 번호
codedb_symbol	코드베이스 전체에서 특정 심볼이 정의된 위치를 검색
codedb_search	Trigram 가속 전체 텍스트 검색 (정규 표현식(regex) 및 범위 지정 결과 지원)
codedb_word	O(1) 역색인(inverted index) 단어 조회
codedb_callers	심볼의 모든 호출 지점(call site) — 단어 인덱스 ∩ 아웃라인(outline) 범위, 단일 라운드트립(round-trip)으로 수행
codedb_context	태스크 형태의 컴포저(composer) — 자연어(NL) 태스크를 전달하면 키워드 + 심볼 정의 + 순위가 매겨진 파일 + 상위 스니펫(snippets)을 하나의 블록으로 반환 (3~5회의 연속적인 호출을 대체)
codedb_hot	가장 최근에 수정된 파일들
codedb_deps	의존성 그래프(Dependency graph): imported_by (기본값) 또는 depends_on ; 전체 BFS를 위해 transitive=true 사용 가능
codedb_read	파일 내용 읽기 (라인 범위, 변경되지 않은 경우 건너뛰는 if_hash, compact 모드 지원)
codedb_edit	폴백(Fallback) 편집기 — str_replace / replace / insert / delete / create (원자적 쓰기(atomic writes), 선택적 if_hash 가드 지원).

클라이언트의 네이티브 편집 도구를 우선적으로 사용하세요; codedb는 컨텍스트 (context)를 위한 것이지, 편집을 위한 것이 아닙니다.

codedb_changes |
시퀀스 번호(sequence number) 이후 변경된 파일들

codedb_status |
인덱스 상태 (파일 개수, 현재 시퀀스, 스캔 단계)

codedb_snapshot |
코드베이스의 전체 사전 렌더링된 JSON 스냅샷 (snapshot)

codedb_remote |
api.wiki.codes를 통해 인덱싱된 공개 저장소(public repos)를 쿼리 — 로컬 클론 (local clone)이 필요 없음

codedb_projects |
이 머신에 로컬로 인덱싱된 모든 프로젝트 목록

codedb_index |
로컬 폴더를 인덱싱하고 codedb.snapshot을 작성

codedb_find |
퍼지 파일 이름 검색 (Fuzzy file-name search) (인덱싱된 경로에 대한 오타 허용 하위 시퀀스 매칭 — 내용/심볼 검색이 아님)

codedb_glob |
글롭 패턴 (glob pattern) (src/**/*.zig, *.md, …)에 대해 인덱싱된 경로 매칭

codedb_ls |
디렉토리의 직계 자식 목록 나열 — 디렉토리 우선, 그 다음 언어 + 개수가 포함된 파일

codedb_query |
조합 가능한 파이프라인 (Composable pipeline) — 하나의 요청 내에서 find, search, filter, deps, outline, read, sort, limit를 체이닝 (chain)

클론 없이 인덱싱된 모든 공개 GitHub 저장소를 쿼리하세요. codedb_remote는 항상 api.wiki.codes를 사용합니다. 이전의 codegraff 백엔드 (backend) 이름은 더 이상 지원되는 경로가 아닙니다. backend를 생략하거나, 이전 프롬프트(prompts)를 위해서만 backend="wiki"를 유지하세요.

# 원격 슬러그(remote slug)가 무엇을 지원하는지 확인
codedb_remote repo="vercel/next.js" action="actions"
# 거대한 파일 목록을 쏟아내는 대신 압축된 디렉토리 요약을 가져오기
...

원격 액션 (Remote actions): actions, tree, outline, search, read, symbol, policy, deps, score, cves, commits, branches, dep-history

codedb_remote와 관련된 Codex 및 Claude Code 훅 (hook) 예제는 docs/hooks-labs.md를 참조하세요.

참고: 이 도구는 https://api.wiki.codes를 호출합니다. API 키는 필요하지 않습니다. 저장소는 반드시 공개 서비스에 의해 이미 인덱싱되어 있어야 합니다.

명령어	설명
codedb tree	언어 및 심볼 (symbol) 개수를 포함한 파일 트리 표시
codedb outline <path>	파일 내의 모든 심볼 (symbol) 목록 나열
codedb find <name>	심볼 (symbol)이 정의된 위치 찾기
codedb search <query>	전체 텍스트 검색 (trigram, 대소문자 구분 없음)
codedb search --regex <pattern>	정규 표현식 (Regex) 검색
codedb word <identifier>	역색인 (inverted index)을 통한 정확한 단어 조회
codedb read <path>	파일 내용 읽기 (-L FROM-TO, --compact 지원)
codedb hot	최근에 수정된 파일
codedb snapshot	codedb.snapshot을 프로젝트 루트에 작성
codedb serve	:7719 포트에서 HTTP 데몬 실행
codedb mcp [path]	stdio를 통한 JSON-RPC/MCP 서버
codedb update	최신 릴리스로 자체 업데이트; 이전 빌드에서 실패할 경우 위의 curl 설치 프로그램을 다시 실행하십시오
codedb nuke	codedb 삭제, 캐시/스냅샷 제거 및 MCP 통합 등록 해제
codedb --version	버전 출력

옵션: --no-telemetry

(또는 CODEDB_NO_TELEMETRY 환경 변수 설정)

# 1. 파일 트리 가져오기
curl localhost:7719/tree
# → src/main.zig (zig, 55L, 4 symbols)
...

Apple M4 Pro, 48GB RAM에서 측정되었습니다. MCP = 사전 인덱싱된 웜 쿼리 (평균 20회 반복). CLI/외부 도구에는 프로세스 시작 시간이 포함됩니다 (평균 3회 반복). Ground truth는 Python 참조 구현을 통해 검증되었습니다.

codedb 저장소 (20개 파일, 12.6k 라인):

쿼리	codedb MCP	codedb CLI	ast-grep	ripgrep	grep	MCP 속도 향상
파일 트리	0.04 ms	52.9 ms	—	—	—	CLI 대비 1,253배
심볼 검색 (init)	0.10 ms	54.1 ms	3.2 ms	6.3 ms	6.5 ms	CLI 대비 549배
전체 텍스트 검색 (allocator)	0.05 ms	60.7 ms	3.2 ms	5.3 ms	6.6 ms	CLI 대비 1,340배
단어 인덱스 (self)	0.04 ms	59.7 ms	n/a	7.2 ms	6.5 ms	CLI 대비 1,404배
구조적 개요 (Structural outline)	0.05 ms	53.5 ms	3.1 ms	—	2.4 ms	CLI 대비 1,143배
의존성 그래프 (Dependency graph)	0.05 ms	2.2 ms	n/a	n/a	n/a	CLI 대비 45배

merjs 저장소 (100개 파일, 17.3k 라인):

쿼리 (Query)	codedb MCP	codedb CLI	ast-grep	ripgrep	grep	MCP 속도 향상 (speedup)
파일 트리 (File tree)	0.05 ms	54.0 ms	—	—	—	CLI 대비 1,173배
심볼 검색 (init)	0.07 ms	54.4 ms	3.4 ms	6.3 ms	3.6 ms	CLI 대비 758배
전체 텍스트 검색 (allocator)	0.03 ms	54.1 ms	2.9 ms	5.1 ms	3.7 ms	CLI 대비 1,554배
단어 인덱스 (self)	0.04 ms	54.7 ms	n/a	6.3 ms	4.2 ms	CLI 대비 1,518배
구조적 개요 (Structural outline)	0.04 ms	54.9 ms	3.4 ms	—	2.5 ms	CLI 대비 1,243배

rtk-ai/rtk 저장소 (329개 파일) — codedb vs rtk vs ripgrep vs grep:

도구 (Tool)	"agent" 검색	속도 향상 (Speedup)
codedb (사전 인덱싱됨)	0.065 ms	기준점 (baseline)
rtk	37 ms	569배 느림
ripgrep	45 ms	692배 느림
grep	80 ms	1,231배 느림

codedb는 가공되지 않은 라인 덤프(raw line dumps)가 아닌, 구조화되고 관련성 높은 결과를 반환합니다. AI 에이전트(AI agents)의 경우, 이는 쿼리당 토큰(tokens) 수가 극적으로 줄어듦을 의미합니다:

저장소 (Repo)	codedb MCP	ripgrep / grep	감소량 (Reduction)
codedb (allocator 검색)	~20 tokens	~32,564 tokens	1,628배 감소
merjs (allocator 검색)	~20 tokens	~4,007 tokens	200배 감소

codedb v0.2.57은 결정론적 병합(deterministic merge)을 사용하는 워커 로컬 병렬 스캔(worker-local parallel scan)을 사용합니다. 각 워커는 자체적인 부분 인덱스(partial index)를 구축하고, 결과는 메인 스레드에서 병합됩니다:

저장소 (Repo)	파일 수 (Files)	콜드 스타트 (Cold start)	파일당 (Per file)	v0.2.56 대비
codedb	20	17 ms	0.85 ms	—
merjs	100	16 ms	0.16 ms	—
5,200개 혼합 파일	5,200	310 ms	0.06 ms	—
openclaw/openclaw	6,315	346 ms	0.05 ms	10배 빠름

인덱스는 시작 시 한 번 구축됩니다. 그 후, 파일 워처(file watcher)가 이를 점진적으로 업데이트합니다 (단일 파일 재인덱싱: <2ms). 쿼리는 파일 시스템을 다시 스캔하지 않습니다. 1,000개 이상의 파일이 있는 저장소의 경우, 약 300~500MB를 절약하기 위해 인덱싱 후 파일 내용을 해제합니다.

지표 (Metric)	v0.2.56	v0.2.57	차이 (Delta)
안정 상태 RSS (Steady-state RSS)	1,867 MB	1,706 MB	−161 MB
git 서브프로세스 / 분당 (유휴 상태)	~30	~0	mtime 제한 (mtime-gated)

이제 watcher가 .git/HEAD의 상태를 확인(stats)합니다.

git rev-parse HEAD를 포크(forking)하기 전의 mtime을 확인합니다.

유휴 상태(idle)인 저장소에서는 서브프로세스가 절대 실행되지 않습니다.

MCP 서버
시작 시 한 번 인덱싱(indexing) → 모든 쿼리는 인메모리(in-memory) 데이터 구조를 통해 처리 (O(1) 해시 조회)
CLI
호출할 때마다 약 55ms의 프로세스 시작 시간 + 전체 파일 시스템 스캔 발생
ast-grep
호출할 때마다 tree-sitter를 통해 모든 파일을 다시 파싱 (~3ms)
ripgrep/grep
호출할 때마다 모든 파일을 무차별 대입(brute-force) 방식으로 스캔 (~5-7ms)

• MCP의 장점:
  한 번 인덱싱하여, 밀리초 미만(sub-millisecond)의 지연 시간으로 수천 번 쿼리 가능

기능	codedb MCP	codedb CLI	ast-grep	ripgrep	grep	ctags
구조적 파싱 (Structural parsing)	✅	✅	✅	❌	❌	✅
...

codedb = tree-sitter + 검색 인덱스 (search index) + 의존성 그래프 (dependency graph) + 에이전트 런타임 (agent runtime). 외부 의존성 없음. 순수 Zig. 단일 바이너리.

┌─────────────┐ ┌─────────────┐
│ HTTP :7719 │ │ MCP stdio │
│ server.zig │ │ mcp.zig │
│ ...         │ │ ...         │
└─────────────┘ └─────────────┘

SQLite 없음. 의존성 없음. 목적에 맞게 설계된 데이터 모델:

Explorer— 구조적 인덱스 엔진. Zig, Python, TypeScript/JavaScript, Rust, Go, PHP, Ruby, HCL, R, Dart를 파싱합니다. 단일 뮤텍스(mutex) 뒤에서 아웃라인(outlines), 트리그램 인덱스 (trigram index), 역색인 (inverted word index), 콘텐츠 캐시 (content cache), 의존성 그래프를 유지합니다.
Store— 추가 전용 (append-only) 버전 로그. 모든 변이(mutation: 스냅샷, 편집, 삭제)는 단조 증가하는 시퀀스 번호(sequence number)를 부여받습니다. 버전 기록은 파일당 최대 100개로 제한됩니다.
Watcher— 폴링(polling) 방식의 파일 와처 (2초 간격). FilteredWalker가 하위 디렉토리로 내려가기 전에 .git, node_modules, zig-cache, __pycache__ 등을 제거(prunes)합니다.
Agents— 커서(cursors), 하트비트(heartbeats), 독점 파일 잠금(exclusive file locks)을 갖춘 일급 구조체(first-class structs). 오래된 에이전트는 30초 후 정리(reaped)됩니다.

스레드 (Thread)	역할 (Role)
Main	HTTP 수락 루프(accept loop) 또는 MCP 읽기 루프
...
모든 스레드는 shutdown: atomic.Value(bool)를 공유합니다.