Codeix

codeix

codeix.dev · AI エージェント向けの高速なセマンティックコード検索 — あらゆるコードベースからシンボル、参照、呼び出し元を見つけます。

codeix                 # start MCP server, watch for changes
codeix build           # parse source files, write .codeindex
codeix -r ~/project build  # build from a specific directory

その理由

AI コーディングエージェントは、コードに取り組む前に、コードを見つけるためにトークン予算の大半を費やします。grep で検索し、ファイルを読み、また grep で検索し、行き戻りします。大規模なコードベースでは、適切な関数を見つけるだけでエージェントが数千トークンを消費することがあります。さらに悪い場合は、関数を完全に見逃して幻覚を起こします。

Codeix は、コードベースの事前構築済みマップをエージェントに提供します。 1 回の構造化クエリで、シンボル名、ファイル、行の範囲、シグネチャ、親を返します。スキャンも推測も不要です。

既存ツールの問題点

問題	現状
構造がない	grep が見つけるのはテキストの一致であり、シンボルではありません。エージェントは、関数の定義と、その関数に言及するコメントを区別できません。
再解析が遅い	Python ベースのインデクサーは、起動時にすべてを再解析します。大規模なコードベースでは待ち時間が発生します。
共有できない	インデックスはローカルキャッシュで、一時的かつマシンごとに存在します。新しい開発者や CI ランナーは、最初からやり直す必要があります。
組み合わせられない	10 個のパッケージがあるモノレポや、便利な API を持つ依存関係があっても、境界を越えてクエリする方法がありません。
散文が見えない	TODO、ドキュメント文字列、エラーメッセージは grep で検索できますが、選択的には検索できません。コードに一致させずにコメントだけを検索することはできません。

codeix の独自の特徴

• Git にコミット可能 — インデックスは、コードと一緒にコミットする .codeindex ディレクトリです。リポジトリをクローンすれば、インデックスはすでにあります。再インデックスは不要です。
• 共有可能 — ライブラリの作者は、npm／PyPI／crates.io パッケージに .codeindex を同梱できます。利用者は依存関係をすぐにナビゲートできます。
• 組み合わせ可能 — MCP サーバーが依存関係のインデックスを自動検出してマウントします。コードと依存関係を 1 か所でクエリできます。
• LLM 向けに構造化 — シンボルには種類、シグネチャ、親子関係、行の範囲があります。エージェントは、生テキストから情報をつなぎ合わせる代わりに、1 回のツール呼び出しで必要な情報を正確に取得できます。
• 散文検索 — search --scope text は、コメント、ドキュメント文字列、文字列リテラルを対象に検索します。TODO を探す、ユーザーから報告されたエラーメッセージを探す、関数のドキュメント文字列の内容を確認するといった検索を、コードによるノイズなしで実行できます。
• 高速 — ビルドは数秒、クエリは数ミリ秒で完了します。内部では Rust、tree-sitter、インメモリ SQLite FTS5 を使用しています。

.codeindex 形式

構造化コードインデックスのための、オープンでポータブルな形式です。コードと一緒にコミットするプレーンな JSONL ファイルなので、Git に適した差分を確認でき、grep や jq で読み取れます。バイナリの塊もありません。

.codeindex/
  index.json        # manifest: version, name, languages
  files.jsonl       # one line per source file (path, lang, hash, line count)
  symbols.jsonl     # one line per symbol (functions, classes, imports, with signatures)
  texts.jsonl       # one line per comment, docstring, string literal

JSON を解析できるツールなら、どれでも .codeindex を利用できます。Codeix は tree-sitter を使ってインデックスを構築し、AI エージェントは MCP（Model Context Protocol）を通じてクエリします。

例 — symbols.jsonl：

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

パッケージにインデックスを同梱する

パッケージに .codeindex を含めると、依存しているすべての開発者が、セットアップや再インデックスなしですぐに API をナビゲートできます。

Git リポジトリ、npm、PyPI、crates.io に対応しています。

MCP ツール

7 つのツールをセットアップ不要で利用できます。エージェントはすぐにクエリできます。初期化、設定、更新は不要です。

ツール	説明
explore	プロジェクト構造を探索します。メタデータ、サブプロジェクト、ディレクトリごとにグループ化されたファイルを取得します
search	シンボル、ファイル、テキストを対象に、スコープ／種類／パス／プロジェクトのフィルターに対応した統合全文検索（FTS5、BM25 順位付け）を実行します
get_file_symbols	ファイル内のすべてのシンボルを一覧表示します
get_children	クラス／モジュールの子要素を取得します
get_callers	シンボルを呼び出す、または参照するすべての箇所を見つけます
get_callees	関数／メソッドが呼び出すすべてのシンボルを見つけます
flush_index	保留中のインデックス変更をディスクに書き込みます

プロジェクトの検出

任意のディレクトリから codeix を起動できます。下位ディレクトリをたどり、.git/ を含む各ディレクトリを個別のプロジェクトとして扱います。それぞれに専用の .codeindex が作成されます。

単一リポジトリ、モノレポ、兄弟リポジトリ、Git サブモジュールのいずれでも同じように機能します。設定は不要です。

言語

Tree-sitter 文法は、コンパイル時に機能フラグで有効化します。

言語	機能フラグ	デフォルト	拡張子
Python	lang-python	はい	.py .pyi .pyw
Rust	lang-rust	はい	.rs
JavaScript	lang-javascript	はい	.js .mjs .cjs .jsx
TypeScript	lang-typescript	はい	.ts .mts .cts .tsx
Go	lang-go	はい	.go
Java	lang-java	はい	.java
C	lang-c	はい	.c .h
C++	lang-cpp	はい	.cpp .cc .cxx .hpp .hxx
Ruby	lang-ruby	はい	.rb .rake .gemspec
C#	lang-csharp	はい	.cs
Markdown	lang-markdown	はい	.md .markdown

Markdown のサポート

Markdown ファイルを解析し、見出し（ATX # 形式と Setext の下線形式の両方）を階層的な親子関係を持つ section シンボルとしてインデックス化します。これにより、目次の抽出やドキュメント構造のナビゲーションが可能になります。

フェンス付きコードブロックは code テキストエントリとして抽出され、内包するセクションの子として登録されます。

埋め込みスクリプト

HTML、Vue、Svelte、Astro ファイルは前処理され、埋め込みの <script> ブロックが抽出されます。その後、JavaScript または TypeScript の文法で解析されます。

形式	拡張子	スクリプトの検出方法
HTML	.html .htm	<script> タグ。オプションで lang="ts" を指定できます
Vue	.vue	<script> および <script setup>。オプションで lang="ts" を指定できます
Svelte	.svelte	<script>。オプションで lang="ts" を指定できます
Astro	.astro	--- フロントマター（常に TypeScript）＋オプションの <script> タグ

インデックス内の行番号は、抽出されたスクリプトブロックではなく元のファイルを指します。

インストール

# npm / npx — run without installing
npx codeix

# pip / uvx — run without installing
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# Or build from source
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

どの配布チャネルからインストールしても、同じ単一バイナリがインストールされます。ランタイム依存関係はありません。

使い方

# Build the index for the current project
codeix build

# Build from a specific directory (discovers all git repos below)
codeix -r ~/projects build

# Start MCP server (default command, watches for changes)
codeix

# Or explicitly
codeix serve
codeix serve --no-watch

# Serve from a specific directory
codeix -r ~/projects serve

MCP クライアントの設定

MCP クライアントの設定（例：Claude Desktop、Cursor）に追加します。

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

設計原則

• ローカルのみ — ネットワークや API キーは不要で、オフラインおよびエアギャップ環境でも動作します
• 決定論的 — 同じソースからは常に同じインデックスが生成されます（差分がクリーンになります）
• 組み合わせ可能 — 依存関係のインデックスは自動検出され、クエリ時にマウントされます
• 最小限のインターフェース — クエリツールは 7 個で、管理用の仕組みはありません

アーキテクチャ

アーキテクチャ決定記録の全一覧は、docs/architecture.md を参照してください。

ライセンス

MIT OR Apache-2.0