codeindex - AI coding agent のための local code knowledge graph

AI coding agent の大きな無駄の一つは、毎回「repository を読み直す」ところから始まりやすいことです。Function を探すために grep し、file の影響範囲を知るためにまた grep し、最近の refactor を確認するために Git log を読む。小さな project なら問題は小さいですが、repository が大きくなると token、時間、誤判断が積み重なります。

今日紹介する scheidydude/codeindex は、この問題に向いた tool です。Repository を local に query できる code knowledge graph に変換し、人間や AI tool が symbol、dependency、history、impact radius から context を取れるようにします。

公開時点の GitHub search result では、およそ 257 stars、35 forks。主な言語は Python です。Repository は 2026-05-20 に作成され、最新 push は 2026-06-08。Shallow clone で確認した現在の project version は 0.3.1、license は Apache-2.0、最新 Git tag は v0.3.1 です。CHANGELOG では v0.3.1 の日付が 2026-06-07 と記録されています。

プロジェクト概要

項目	内容
Repository	scheidydude/codeindex
位置づけ	Local repository dependency graph、symbol index、impact analysis tool
Stars	約 257
Forks	35
主な言語	Python
License	Apache-2.0
Latest tag	v0.3.1

codeindex.json を生成するだけではない

codeindex の入口はかなり素直です。

pip install codeindex
codeindex analyze ./myapp
codeindex symbols ./myapp
codeindex impact src/auth.py

ただし、中心にあるのは static JSON を一つ作ることだけではありません。README では、analyze が repository 内に .codeindex/index.db を作り、SQLite に dependency graph を保存すると説明されています。同時に、互換性のため codeindex.json も出力されます。

この設計は実用的です。多くの code analysis tool は一回きりの report に近いです。実行し、結果を読み、忘れる。codeindex はそれよりも、小さな local index service に近いです。繰り返し更新し、ある file の blast radius を query し、高リスク file を探し、MCP 経由で agent に呼ばせることができます。

Blast radius は「この file は重要」より具体的

Engineering では、よく「この file は core だ」と言います。しかし、どれくらい core なのかは経験で判断されがちです。codeindex はこの問題を direct dependents と transitive dependents に分け、blast score を出します。

たとえば codeindex impact src/auth.py のような command は、その file に直接依存する file と、より長い chain で影響を受ける file を示します。README にある formula は次の通りです。

direct + (0.5 x transitive)

完璧な risk model ではありません。それでも「なんとなく危険そう」よりはかなり具体的です。AI coding agent にとっては、変更前に high-impact area を知れるという追加の価値があります。Test が壊れた後に core path を触っていたと気づくより、先に影響範囲を確認できます。

私はこれを軽量な engineering guardrail と見ます。Test や human review の代替ではありませんが、「まず impact を見る」を executable command にできます。

Symbol index は context location の問題を解く

README では symbolindex.json が強調されています。Function、class、struct、interface などの symbol がどの file の何行目にあるかを記録する index です。人間には quick lookup であり、AI には不要な file scan を減らす仕組みになります。

よくある agent flow では、user が「processPayment はどこで定義されているか」と聞くと、agent は rg processPayment を実行し、複数 file を開き、どれが definition か判断します。中規模 repository でも、この時点でかなり context を使うことがあります。

codeindex では先に次を実行できます。

codeindex symbols .
codeindex lookup process_payment

MCP に接続すれば、agent は lookup_symbol を直接呼べます。--claude-md を使えば、圧縮された symbol summary を CLAUDE.md に書き込むこともできます。README は同時に、これは base context を増やすので、symbol lookup が頻繁な repository に向くと説明しています。

この tradeoff は大事です。よい tool は「もっと多くを context に入れよう」とだけ言うのではなく、いつ query し、いつ preload し、いつ軽く保つかを選ばせるべきです。

Git history が graph に時間軸を加える

v0.3.0 以降、codeindex は one-shot dependency analyzer から temporal code knowledge graph へ進んでいます。CHANGELOG では、file、edge、symbol に first_seen_commit / last_seen_commit を記録し、次の command を提供すると説明されています。

• codeindex history: Git history から temporal graph を backfill する。
• codeindex changed-since <ref>: commit、branch、tag 以降に追加・削除された file と dependency edge を見る。
• codeindex impact <file> --as-of <ref>: historical point の blast radius を query する。

これは review に向いています。Risk は current snapshot だけから来るわけではありません。「なぜこの file が急に high-impact になったのか」を知りたいことがあります。最近の commits で module が新しい dependency を吸い込み続けているなら、HEAD だけを見ても trend は分かりません。Time dimension を持つ graph は、人間や agent が具体的な history point へ戻る助けになります。

注意点もあります。changed-since は history backfill に依存します。v0.3.1 の fix でも、codeindex history をまだ実行していない場合は明確な warning を出すようになったと記録されています。不完全な結果を信じ込ませないための修正です。

MCP によって AI workflow へ入りやすい

codeindex は stdio MCP server を公開しています。README に載っている tools は次の通りです。

• analyze_repo
• get_impact
• get_dependencies
• get_high_blast_files
• build_symbol_index
• lookup_symbol
• semantic_search
• temporal_impact
• graph_query
• changed_since

この tool set の意味は、agent を魔法のように賢くすることではありません。Agent が変更前に、より具体的な質問をできるようにすることです。この symbol はどこか。この file は何に依存しているか。誰がこの file に依存しているか。この変更は何 file に波及しそうか。ある release 以降、dependency edge はどう変わったか。

Team がすでに Claude Code、Codex、または MCP 対応 tool で作業しているなら、codeindex は local context layer になります。Repository を third-party service に upload する必要はありません。新しい database service も不要です。Default では SQLite と Python stdlib で動き、semantic search や file watch は optional dependency として提供されます。

対応範囲は広いが、期待値は校正したい

README にある supported languages は広いです。Python、JavaScript / TypeScript、Vue、Go、Ruby、Rust、Java / Kotlin、PHP、CSS / SCSS / Less、Docker、CI/CD、SQL / Prisma などが並びます。Visualization UI もあり、2D / 3D graph、dependency matrix、treemap、infrastructure graph を表示できます。

これは魅力的ですが、採用時は慎重でよいです。Cross-language dependency analysis は完全に正確にするのが難しい領域です。Dynamic import、framework convention、code generation、monorepo alias、runtime config が絡むと、どの tool でも限界があります。codeindex は「query できる engineering map」として扱い、絶対的な真実とは見ないほうが安全です。

最初に試すなら、私は次の三つに絞ります。

1. codeindex analyze . と codeindex symbols . を実行し、主要 language と core symbols を正しく拾えるか見る。
2. codeindex high-blast --threshold 5 で high-impact files を出し、team の経験と照らし合わせる。
3. AI tool に MCP を接続し、high-risk file を変更する前に get_impact と get_dependencies を呼ぶようにする。

この三つが安定して説明可能な結果を返すなら、history backfill、semantic search、visualization を追加で試す価値があります。

まとめ

scheidydude/codeindex が面白いのは、AI coding の問題を「別の model に変える」話にしていないからです。もっと下の context 問題を扱っています。Repository structure、symbol location、dependency relation、history change、impact radius を local に query できるようにする tool です。

人間の developer にとっては軽量な code map です。AI agent にとっては、より抑制された context entry point になります。これからの AI coding workflow は、毎回 full repository scan から始まるべきではありません。先に構造化された質問をし、本当に関連する file だけを開くべきです。codeindex は、その方向を示す小さくても実用的な project です。