forensic-deepdive

forensic-deepdive

forensic-deepdive は、未知のコードベースを AI コーディングエージェントがフォレンジックに理解できるようにします — 永続的なナレッジグラフ、MCP サーバー、そして5つの永続的な Markdown 成果物により、エージェントがセッションのたびに同じアーキテクチャを一から再発見する必要がなくなります。

uv tool install forensic-deepdive && forensic extract /path/to/repo

他との違い： すべてのエッジと出力されるすべての主張に信頼度タグが付与されます — EXTRACTED（決定論的な事実）／INFERRED（ヒューリスティックによる推論が明確に確定）／AMBIGUOUS （複数の候補を表示し、推測しない） — そのため、エージェントは行動する前に何を信頼すべきかを把握できます。このカテゴリで信頼度をタグ付けするものは、ほかにありません。

GitNexus / CodeGraphContext / DeepWiki / Sourcegraph ではなく、なぜこれを選ぶのか

	forensic-deepdive	GitNexus	CodeGraphContext	DeepWiki	Sourcegraph
ライセンス	Apache-2.0	PolyForm Noncommercial	MIT	プロプライエタリ（オープン版：MIT）	一部
永続的なコードナレッジグラフ	✅ LadybugDB	✅ LadybugDB	一部	❌	一部
MCP サーバー	✅ 9つの複合ツール	✅ 16個のツール	一部	❌	❌
エッジごとの信頼度分類	✅ EXTRACTED / INFERRED / AMBIGUOUS	❌	❌	❌	❌
第一級レイヤーとしての Git の考古学的解析	✅	❌	❌	❌	一部
永続的なコミット可能な Markdown 成果物	✅ 5ファイル	一部	一部	✅（Wiki）	❌
エージェントのインサイトレイヤー（record_insight / recall_insights）	✅	❌	❌	❌	❌
マルチプラットフォーム向けスキルの出力	✅ 10個のシム	一部	一部	❌	❌
ローカルのみ（クラウド不要）	✅ 同等の機能	✅	✅	❌	❌

GitNexus はこのカテゴリで圧倒的なリーダーですが、PolyForm Noncommercial ライセンスにより、商用ユーザーは一切利用できません。 forensic-deepdive は Apache-2.0 の 代替製品です。永続グラフと MCP を組み合わせた同じ形に、明示的な信頼度タグ、Git の 考古学的解析、永続的なエージェントメモリ、そして MCP に対応しないエージェント向けの フォールバックとなる5つの Markdown 成果物を加え、勤務先の法務チームが実際に承認できる ライセンスで提供します。

---

生成されるもの

forensic-deepdive は任意のコードベース（9 言語、ポリグロット）を分析し、次のものを生成します。

1. 永続的な埋め込みグラフ（<repo>/.deepdive/graph.lbug） — File、Symbol、Module、Commit、Author、Endpoint、DbTable の各ノードに加え、DEFINES、MEMBER_OF、IMPORTS、CALLS、EXTENDS、IMPLEMENTS、TOUCHED_BY_COMMIT、AUTHORED_BY、CO_CHANGES_WITH、および境界をまたぐ HANDLES / CALLS_ENDPOINT / ROUTES_TO / INJECTS / PERSISTS_TO の各エッジを格納します。すべてのエッジに信頼度タグ（EXTRACTED / INFERRED / AMBIGUOUS）が付き、隠れたヒューリスティックはありません。単一の Endpoint 結合ノードが5 つの境界横断プロトコル（HTTP、MCP ツール、レジストリディスパッチ、gRPC、メッセージング/AMQP）を統合するため、フロントエンドの呼び出しからバックエンドのハンドラーまでを、スタック全体にわたる 1 つの ROUTES_TO エッジとして解決できます。
2. MCP サーバー（forensic serve） — Claude Code、Cursor、Codex、Continue、Cline、Windsurf、およびその他の MCP 対応エージェントから利用できる9 つの複合ツール（impact、context、archaeology、flow、query、record_insight、recall_insights、visualize、trace）を公開します。
3. <repo>/docs/codebase/ に生成される5 つの永続的な Markdown 成果物。抽出のたびにグラフから再生成されます。
   • MAP.md — 各要素の場所を、中心性の高い順に示します。
   • HOTPATHS.md — 依存関係のホットスポットを示します。行ごとに信頼度の内訳列があり、各シンボルがどれだけ明確に解決されているかを正確に確認できます。
   • ARCHAEOLOGY.md — コードが現在の形になった理由を示します（git の履歴、上位の著者とその割合、バスファクター、共同変更クラスター、欠陥との近接性）。
   • MENTAL_MODEL.md — 元の作者が新入社員のオンボーディング用に作成していたであろうドキュメントです。
   • AGENT_BRIEF.md — ルールごとの信頼度タグ付きで、明確な「決して〜しない」/「必ず〜する」ルールを 5 KB 以下にまとめています。任意のプロジェクトでそのまま使える CLAUDE.md です。
4. 対象リポジトリに追加する 10 個のシム — エディター用ルールファイル 4 個（CLAUDE.md、AGENTS.md、.cursor/rules/codebase.mdc、.continue/rules/codebase.md）、目的を絞った Claude スキル 5 個（.claude/skills/codebase-{exploring,debugging,impact-analysis,refactoring,onboarding}/）、および .claude-plugin/plugin.json マニフェスト。いずれもファイルが存在しない場合にのみ書き込まれ、手動編集済みのファイルが上書きされることはありません。
5. エージェントインサイト層 — <repo>/.deepdive/insights.jsonl をデフォルトで使用する record_insight / recall_insights MCP ツール（依存関係なし、人間が読みやすく、git で扱いやすい）。オプションの [graphiti] エクストラを使うと、リポジトリサイズが 5 段階中 2 以上の場合に、時間情報を扱うナレッジグラフバックエンドへアップグレードされます。

抽出時には、境界横断グラフをシステムレベルで示す Mermaid ビュー（ROUTES_TO / INJECTS / PERSISTS_TO、信頼度をスタイルで表示）である ARCHITECTURE.md も再生成されます。これは人間が別途検証するためのビューであり、5 つの契約成果物には含まれません。forensic visualize や serve --ui と同様です。forensic diagram --repo <repo> を使えば、これ単独で再生成できます。グラフの妥当性確認に使ってください。ここに誤ったエッジがあれば、どこでも誤ったエッジです。

--emit-vault を追加すると、Obsidian で使いやすい Vault も <output>/vault/ に書き出されます。すべての成果物に summary:/tags: のフロントマターが付き、相互参照は [[wikilinks]] に変換され、成果物をまとめる INDEX.md MOC（.obsidian/ 設定付き）が生成されます。人間向け（グラフビュー、バックリンク）とエージェント向け（ファイルを開かずに summary: でトリアージできる、たどれるインデックス）のローカル優先セカンドブレインです。オプトインで、デフォルトでは無効です。

ステータス

v0.10.0「アップグレードへの道」 — 整合性リリースです。v0.9 は正しくリリースされましたが、その後の調査で、--refresh-shims は構造上、対象の半分を更新できないことが判明しました。それでもテストは909件すべて成功していました。原因は修正内容ではなく、テストスイートのすべてのテストが空のディレクトリに書き込んでいたため、テストされていたのは最初の実行だけだったことです。 新規ユーザーでない人は、誰もテストされていない経路を使っています。

そのため、0.10 では機能をほとんど追加していません。すでに掲げていた保証を実際のものにします。以前のリリースの出力がすでに存在するリポジトリで Deepdive を実行しても、確実に収束し（手作業で編集したファイルは確実にそのまま残り）、extract は生成済みのシムが古くなっていることを知らせるため、フラグの存在を知るまで待つ必要がありません。また、古くなった examples/ は、リリース中に目視で気づくのではなく、CI で失敗します。新機能として、forensic extract --timings でフェーズごとの実時間を確認できます。

また、中止された機能も含まれています。これが、より有益な経緯です。計画されていたパフォーマンス改善の対象は PageRank でした。これに着手する前に必要なプロファイル測定では、大規模な抽出における PageRank の処理時間は**0.04％で、すでにバッチ処理されていたストアへの書き込みは79～87％**でした。最適化は、コードを書く前に効果がないと判明しました。詳しくは docs/findings/v0.10/PROFILE.md をご覧ください。既知の手法が適用されていることの確認を、それが高速であることの確認と取り違えていました。

エンジン、グラフ、コントラクト層、および5アーティファクト＋9 MCP ツールのコントラクトは、0.9 から変更ありません。出力内容も、バージョンフッターを除いてバイト単位で同一です。

⚠ 0.8.0 または 0.9.0 をインストールしていて、forensic serve が動かなくなった場合、その理由はこちらです。 これらの リリースでは、上限を設けずに mcp>=1.27.1 を宣言しています。mcp 2.0.0 では MCP サーバーがインポートする mcp.server.fastmcp が削除されたため、現在 0.8.0 または 0.9.0 を新規インストールすると、mcp 2.0.0 が解決され、インポート時に失敗します。開発用ロックファイルでは 1.27.1 に固定していたため、ローカルでのチェックはすべて 成功し、クリーンな環境での CI のホイールスモークテストでのみ問題を検出できました。対処方法：0.10.0 にアップグレードする （mcp<2 に上限を設定しています）か、ご自身で mcp<2 に固定してください。 これらのリリースに関するその他の点には影響ありません。

実証済みのことと、未実証のこと — 誠実な説明のセクションは docs/findings/HONEST.md に移動しました（内容に変更なし、DEC-119）。簡潔に言うと、 実際のエージェントによる自動検出で利用可能であることは実証済みですが、自律的な問題解決をエンドツーエンドで測定可能なほど高速化することは 実証されていません（ハードウェアに依存します）。これは分析支援ツールであり、それ以上のものとして過大に主張していません。

クイックスタート

# install from PyPI (puts `forensic` on PATH); or run ephemerally with uvx
uv tool install forensic-deepdive
forensic info            # banner + capability panel
forensic extract /path/to/repo

# …or from source for development:
git clone https://github.com/Dhevenddra/forensic-deepdive && cd forensic-deepdive
uv sync --all-extras

# what can it do? (banner + capability panel: artifacts, protocols, MCP tools, confidence legend)
uv run forensic info

# guided setup: analyze a repo, then wire it up as an MCP server
# (--yes takes every default: scriptable, and the one mode that needs no extra)
uv run forensic onboard --repo /path/to/repo

# run on any repo
uv run forensic extract /path/to/repo

# graph lands at <repo>/.deepdive/graph.lbug
# 5 markdown artifacts at <repo>/docs/codebase/
# 10 shims at <repo>/.claude/, .cursor/, .continue/, root

# trace a cross-stack feature slice (frontend call -> endpoint -> handler -> tail)
uv run forensic trace <symbol> --repo /path/to/repo

# interactive query REPL over one held-open store (needs the [interactive] extra)
# bare text = natural-language query (no LLM) · :cypher <q> = raw Cypher · :help · Ctrl-D exits
uv run forensic repl --repo /path/to/repo

# full-screen terminal graph browser — the loopback-free sibling of serve --ui
# 1/2/3 = Symbols/Files/Endpoints · type to filter · c/e/l = confidence/edge/language · Enter = context · i/f = impact/flow
uv run forensic browse --repo /path/to/repo

# the session shell: all of the above over ONE held-open graph, with history
# in-session: extract · query · trace · impact · flow · diagram · browse · onboard · serve
uv run deepdive --repo /path/to/repo

# query the graph as an MCP server (point it at the analyzed repo)
uv run forensic serve --repo /path/to/repo

# inspect every repo you've analyzed
uv run forensic list

PyPI からインストール

forensic-deepdive として公開されています — クローンは不要です。

uv tool install forensic-deepdive        # puts `forensic` on PATH
forensic extract /path/to/repo

# …or run ephemerally, no install:
uvx forensic-deepdive extract /path/to/repo

オプションの追加機能：uv tool install "forensic-deepdive[semantic]"（オフライン ONNX NL クエリ）、[interactive]（forensic repl クエリコンソール、forensic browse TUI グラフブラウザー、deepdive セッションシェル）、[openapi]（YAML 仕様の 解析）、[graphiti]（時間的インサイトのバックエンド）。

0.8 からのアップグレード

--refresh-shims を付けて extract を一度再実行してください。.claude/、.cursor/、.continue/ の下にある生成済みのシムとスキルは、 存在しない場合にのみ書き込まれます。そのため、通常の再抽出では 0.8 時代のコピーがそのまま残ります。また、スキルファイルのうち2つには、 0.9 で削除された内部決定 ID がまだ記載されています。

forensic extract /path/to/repo --force --refresh-shims

Deepdive が生成したファイルのみが書き換えられます。手作業で編集したシムには、決して触れません。 uv を使っていない場合は、pip install forensic-deepdive でもインストールできます。

MCP サーバーとして使用する

forensic serve は、MCP に対応するあらゆるエージェント（Claude Code、Cursor、VS Code/Copilot、Codex、Continue、Cline、Windsurf）に 9 つの複合ツールを公開する stdio MCP サーバーです。まずグラフを一度構築し（forensic extract <repo>）、その後サーバーを接続します。方法は 3 つあります。簡単な順に紹介します。

1. Claude Code プラグイン（セルフホスト型マーケットプレイス — PyPI の手順不要）：

/plugin marketplace add Dhevenddra/forensic-deepdive
/plugin install forensic-deepdive@dhevenddra

2. MCP Registry から — io.github.Dhevenddra/forensic-deepdive としてインデックス化されているため、レジストリ対応クライアントやディスカバリーハブ（PulseMCP、MCPJungle、VS Code の @mcp インデックス）から直接検索してインストールできます。

3. 手動設定 — forensic mcp-config でクライアント設定スニペットを生成するか、次の内容を貼り付けてください。

{
  "mcpServers": {
    "forensic-deepdive": {
      "command": "uvx",
      "args": ["forensic-deepdive", "serve", "--repo", "."]
    }
  }
}

クライアント別のコピー＆ペースト用ブロック（Cursor、VS Code、Codex、uvx が見つからない場合の GUI 特有の注意点）は、docs/install.md にあります。

対応する 9 言語

Python、C、Dart、Swift、TypeScript、JavaScript、Java、Go、Rust。

9 つの MCP ツール

ツール	機能
impact(symbol, depth, direction, min_confidence)	CALLS エッジをたどる、深さごとに分類され、信頼度でフィルタリング可能な影響範囲の BFS です。
context(symbol)	定義、呼び出し元、呼び出し先、親／兄弟／メンバー、拡張／実装、最近のコミット、主要な作成者、最近のインサイトをまとめて取得する単一呼び出しの総合ツールです。
archaeology(file_or_symbol)	変更頻度、上位の作成者と割合、バスファクター、共同変更クラスター、欠陥との近接性、最近のコミットを取得します。
flow(entry_point, max_depth)	サイクル検出付きで CALLS をたどる DFS です。
query(cypher | natural_language)	Cypher の直接指定、またはハイブリッド NL 検索（FTS5/BM25 + 構造グラフシグナル + オプトインのオフラインセマンティック検索を RRF で統合して整形）を実行し、各ヒットの出典情報と信頼度を返します。
record_insight(symbol, claim, evidence, verified_by)	検証済みの学習内容を保存します。
recall_insights(symbol, since, limit)	保存されたインサイトから、新しい順に部分一致で検索します。
visualize(target, format, depth, max_nodes, ...)	シンボル／ファイル周辺（または central）の範囲を制限した Mermaid 図を生成します。エッジの破線スタイルは信頼度を表します。
trace(symbol, direction, max_depth)	Endpoint の結合ノードを介して、スタックをまたぐ機能のスライスをたどります。downstream はフロントエンドの呼び出し → CALLS_ENDPOINT → エンドポイント → HANDLES → ハンドラー → CALLS の末尾をたどります。upstream は「このエンドポイントを呼び出しているのは誰か」を示します。

ツールの説明はそれぞれ 200 トークン以下であり、9 ツール分の合計が Anthropic のターンごとのスキルメタデータ予算に十分収まります。

信頼度の分類

すべてのエッジと出力されるすべての主張には、EXTRACTED／INFERRED／AMBIGUOUS のいずれかが付与されます。

• EXTRACTED — AST または git log から決定論的に得られた情報です。事実を表します。
• INFERRED — ヒューリスティックによって明確に解決された情報です（インポートグラフの探索、レシーバー型の推論、ファイルをまたいだ同名候補が 1 つの場合）。信頼性は高いものの、導出された情報です。
• AMBIGUOUS — 複数の候補が見つかり、解決処理で区別できなかった情報です。候補はすべて表示され、黙って推測されることはありません。

HOTPATHS では行ごとに信頼度の内訳列が表示されるため、Logger（EXTRACTED が 4 件、INFERRED が 1458 件 — ほとんどが明確）と ChatToolResponse（AMBIGUOUS が 449 件 — ファイルをまたいだ同名の衝突）をひと目で見分けられます。

正直モード（純粋な静的解析、LLM 不使用、ネットワーク不使用）

forensic extract は、ANTHROPIC_API_KEY も OPENAI_API_KEY も Ollama もネットワークも不要で、最初から最後まで動作します。Graphiti は [graphiti] の PyPI extra によるオプトインで、リポジトリサイズの 5 つの基準のうち 2 つを満たす必要があります（≥50 k LOC、≥25 人のコントリビューター、作成から ≥18 か月、過去 12 か月で ≥200 PR、議論のある issue が ≥100 件）。JsonlInsightStore は常に利用できる基本機能です。

（GitNexus／CodeGraphContext／DeepWiki／Sourcegraph の比較表は上部にあります。これは脚注ではなく、主な比較です。）

ローカル開発

git clone https://github.com/Dhevenddra/forensic-deepdive
cd forensic-deepdive
uv sync --all-extras
uv run forensic --version
uv run pytest -x          # 1000+ tests at v0.10.0
uv run ruff check src/ tests/
uv run forensic extract tests/fixtures/tiny_fixture

変更を加える前に、CLAUDE.md、DECISIONS.md（有効な DEC が 81 件）、PROGRESS.md を読んでください。このリポジトリでは、自らのパターンを実践しています。すべてのセッションは CLAUDE.md のプロトコルから始まり、すべてのアーキテクチャ上の選択は DEC-N エントリーとして記録され、アーティファクト名の契約（MAP、HOTPATHS、ARCHAEOLOGY、MENTAL_MODEL、AGENT_BRIEF）は公開 API の一部です。

謝辞

• PageRank と Tree-sitter を使ったリポジトリマップのパターンを提供してくれた Aider（Paul Gauthier）に感謝します。アルゴリズムは謝辞を明記して移植しています。パッケージとしての aider には依存していません。
• EXTRACTED / INFERRED / AMBIGUOUS の確信度分類を提供してくれた Graphify（safishamsi）に感謝します。DEC-015 で、すべてのエミッターにわたってプロダクト化しました。
• マルチリポジトリレジストリのパターン（~/.deepdive/registry.json、DEC-018）、複合 MCP ツールの構成、そしてこのプロジェクトの Apache-2.0 による差別化を重要なものにするライセンス上の優位性を提供してくれた GitNexus（abhigyanpatwari）に感謝します。
• 組み込みグラフエンジンを提供してくれた Kuzu（現在は Apple によりアーカイブ済み）と、v0.2 が採用する現行のコミュニティフォークを提供してくれた LadybugDB（DEC-013）に感謝します。
• 上記のしきい値を超えたインサイトのバックエンドを支える時間的ナレッジグラフ Graphiti を提供してくれた Zep / getzep（DEC-019）に感謝します。
• このプロダクトの形を可能にする Skills 形式、Claude Code、MCP プロトコルを提供してくれた Anthropic に感謝します。
• uv と ruff を提供してくれた Astral に感謝します。
• 元の v0.1 のリポジトリをフラット化するパターンを提供してくれた Repomix（yamadashy）に感謝します。このパターンは現在 --legacy-repomix に格下げされていますが（DEC-017）、レガシーなユースケース向けに引き続き利用できます。

貢献

貢献を歓迎します。開発環境のセットアップ、検証ゲート、アーキテクチャ上の不変条件（5 アーティファクトの契約、要となる Endpoint、確信度分類）については、CONTRIBUTING.md をご覧ください。貢献することで、あなたの成果物が Apache-2.0 の下でライセンスされることに同意したものとみなされます。

ライセンス

Apache-2.0 です。詳細は LICENSE をご覧ください。

このプロジェクトを再配布、変更、または基にして何かを作成する場合は、Apache-2.0 の条件が適用されます。著作権表示、LICENSE のテキスト、NOTICE ファイルを保持し、加えた変更を明記する必要があります（ライセンス第 4 条）。帰属表示が必要です。このプロジェクトの著作権者は Dhevenddra です（2026 年、NOTICE を参照）。LICENSE の付録にある定型ヘッダー（Copyright [yyyy] [name of copyright owner]）は、ソースファイルにライセンスを適用するためのテンプレートであり、それ自体は必須要件ではありません。また、LICENSE ファイルは、公式の Apache-2.0 テキストとして一字一句そのまま保持されています。