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 で書かれた軽量で依存関係のないサーバーであり、ローカルコードベースの豊富なインデックス（3文字語素全文検索、逆引き単語、シンボルアウトライン、コールグラフ、依存関係グラフなど）を構築します。これらのインデックスは Model Context Protocol (MCP) を通じて公開されます。MCP は JSON-RPC-over-stdio によるインターフェースであり、AI駆動のコーディングアシスタント（Claude Code、Cursor、Gemini CLI、Codex など）がコードに関する高速で構造化されたコンテキストを取得するために呼び出すことができます。codedb はファイルの編集を行いません。編集はユーザーの通常のエディタに任されます。

主な機能

複数の言語（Zig、C/C++、Python、Rust、Go など）向けの構造的インデックスと、他の言語向けの軽量アウトライン。
3文字語素加速検索と O(1) 単語検索。
シンボル検索、コールサイト発見、コールパス計算。
依存関係グラフ（インポートまたは markdown リンク）と最近の変更追跡。
AIエージェントが1回のRPC呼び出しで実行できる MCPツール（22の組み込みコマンド）。
HTTPモード（codedb serve）：MCP以外のクライアント向け。
ファイルウォッチャー により、インデックスが増分的に最新化されます（単一ファイルの再インデックス化は2ms未満）。

AIエージェントにとってなぜ重要か – エージェントは簡潔でトークン効率の良いコンテキストを必要とします。codedb は関連するシンボル、呼び出し元、スニペットのみを含む構造化されたJSON（またはプレーンテキスト）を返すため、従来の grep/ripgrep 出力と比べてトークン使用量を数百〜数千倍削減できます。ベンチマークでは、従来のツールのCLI起動時間（約55ms）や1回の検索時間（5〜7ms）と比較して、1ミリ秒未満のクエリ遅延（約0.05ms）を達成しています。

インストール

macOS / Linux – 1行スクリプトで適切な署名付きバイナリをダウンロードし、対応する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" → 3文字語素高速全文検索。
コール元 / コールパス – codedb_callers または codedb_callpath で使用経路を追跡。

これらのすべては、HTTP（curl localhost:7719/...）またはAIアシスタントが使用するMCP JSON-RPCチャネル経由で呼び出せます。

アーキテクチャ（概要）

インデクサ – サーバー起動時に一度だけ実行され、対応する言語を解析し、以下を構築：
- 3文字語素インデックス（整数ドキュメントID、バッチマージ）：高速な曖昧なテキスト検索用。
- 逆引き単語インデックス：O(1) の識別子検索用。
- 構造的アウトライン（関数、構造体、インポート）：ファイルごとに保存。
- 依存関係グラフ：インポートまたは markdown リンクをリンク。
スナップショット – インデックス全体を codedb.snapshot にシリアライズ可能。即時デーモン再起動が可能。
MCPサーバー – stdio 上の軽量な JSON-RPC 2.0レイヤー。各ツールは1つのRPCメソッドであり、あらかじめ構築されたインデックスを組み合わせます。
ファイルウォッチャー – フィルタリングされたディレクトリ走査により、メモリ内インデックスを増分的に更新。1ファイルの変更コストは <2ms。
クロスプラットフォーム – macOS（ARM & Intel）、Linux（ARM & x86_64）、Windows 用ネイティブバイナリ。

データとプライバシー

ローカルのみで動作；オプションの DeepWiki リモート MCP を有効にしない限り、ネットワークトラフィックは発生しません（GitHubの公開リポジトリ向け）。
HTTPサーバーはデフォルトで localhost にバインド；認証層は提供されません。
敏感なファイル（.env、キーなど）はインデックスから自動的にブロックされます。

だれが使うべきか？

AIコーディングアシスタントを開発している開発者：高速でトークン効率の良いコードコンテキストが必要な場合。
Claude Code、Cursor、Gemini CLI、または同様のエージェントを運用しているチーム：即座に使えるローカル知識ベースが必要な場合。
RAG（リトリーバー・オーガナイズド・ジェネレーション）をコードに実験している研究者。

現在の状態

アルファ – APIは安定化中。コア機能（MCPツール、3文字語素検索、単語インデックス、構造的アウトライン、依存関係グラフ）はプロダクションで使用可能で、毎日利用されています。
継続中の作業：より深いパーサー対応、増分セグメントベースインデックス、WASMターゲット、マルチプロジェクト対応、mmapバックド3文字語素インデックス。

結論 – codedb は、重いツールを導入せずにAIエージェントにコードベースの高速で構造化されたビューを提供します。ミリ秒未満のクエリ時間と極めて小さなトークンフットプリントにより、LLM駆動のコーディングワークフローの実用的な基盤となります。