🕸️ 技術調査 - GitNexus

概要

GitNexus は、ソースコードからナレッジグラフを構築し、AI エージェントにコードベースの構造的な理解を提供するコードインテリジェンスツールです。ライセンスは PolyForm Noncommercial 1.0.0 で、OSS 版は非商用利用に限られます。

AI コーディングアシスタントは、コードを編集する際に下流の影響範囲を把握できません。GitNexus は、依存関係・コールチェーン・実行フロー・機能クラスターをインデックス時に事前計算します。エージェントは単一のツール呼び出しで、完全な構造コンテキストを取得できます。

この記事の対象読者

• AI コーディングエージェント（Claude Code, Cursor 等）を日常的に利用している開発者
• コードベースの構造理解を自動化したいチームリーダー・アーキテクト
• MCP サーバーの活用事例を探しているエンジニア

位置づけ

関連技術との関係

特徴

GitNexus の主な特徴は以下のとおりです。

• ナレッジグラフによる構造化: コードベースを関数・クラス・モジュール・実行フローのグラフとして表現し、LadybugDB に永続化
• MCP ネイティブ統合: query, context, impact, detect_changes, rename, cypher, list_repos 等の MCP ツールを提供し、Cursor / Claude Code / Windsurf から直接利用可能
• ブラスト半径分析: 関数変更の影響範囲を confidence スコア付きで上流・下流方向にトレース
• デュアルデプロイ: CLI（Node.js + 永続化）とブラウザ UI（WASM + インメモリ）の両方で動作
• 15 言語以上のサポート: TypeScript, JavaScript, Python, Java, Go, Rust, C, C++, C#, PHP, Swift, Kotlin, Ruby, Dart, COBOL 等を Tree-sitter でパース
• ハイブリッド検索: BM25 + セマンティック検索を RRF で統合し、プロセスグルーピング付きで結果を返却
• マルチリポジトリ対応（Enterprise）: リポジトリグループ機能でクロスサービスのコールチェーンを横断分析。OSS 版は単一リポジトリ操作が基本
• Git diff 対応: ブランチ間の差分から影響を受けるプロセスと関数を特定

類似ツールとの比較

GitNexus はインデックス時に関係性を事前計算します。Sourcegraph はリアルタイム検索に強みを持ちますが、コールチェーン・実行フローの事前計算グラフは提供していません。GitHub Copilot / Codeium はコンテキストウィンドウベースのパターンマッチングであり、アプローチが異なります。aider は git 操作に特化したコーディングエージェントで、GitNexus とは補完関係にあります。

ユースケース別推奨

構造

システムコンテキスト図

コンテナ図

コンポーネント図

インデックスパイプライン

パイプライン各フェーズのデータフロー

Type Resolution の不動点ループは、Tarjan の強連結成分（SCC）アルゴリズムで循環依存グラフを分解し、各 SCC 内でシンボルの型情報を繰り返し伝播させます。収束条件を満たすまで最大 10 回ループし、型が確定しないシンボルには unknown を割り当てます。

MCP Server

Web UI

データ

概念モデル

グローバルレジストリ

リポジトリインデックス

グラフノード

実装上はこれら 8 種に加え、Route, Tool, Section, CodeElement, Struct, Enum, Trait, Impl, TypeAlias 等の追加ノード型が定義されています。

グラフリレーションシップ

主要リレーションシップの接続許容型

実装上はこれら 9 種に加え、HAS_PROPERTY, ACCESSES, OVERRIDES, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF 等の追加リレーション型が定義されています。

GraphRelationship の主要プロパティは以下のとおりです。

エージェント統合（エディタ設定、グラフ外）

Skill と Hook はナレッジグラフの永続データではありません。エディタ統合の外部設定ファイルです。

マルチリポジトリ管理（Enterprise 機能）

これらのエンティティは Enterprise 版に含まれる機能です。OSS 版の永続スキーマには含まれていない可能性があります。

情報モデル

構築方法

前提条件

インストール方法

グローバルインストール

npm install -g gitnexus

インストール後、gitnexus コマンドが利用できます。

npx による実行（インストール不要）

npx gitnexus analyze

最新版をインストールせずに実行します。

Web UI（ブラウザのみ、インストール不要）

• URL: https://gitnexus.vercel.app
• ZIP ファイルをドラッグ＆ドロップするか、GitHub リポジトリ URL を入力します
• ブラウザ内の WASM で完結するため、ローカルへのインストールは不要です

バージョン確認

gitnexus --version

初期セットアップ（エディタ統合）

gitnexus setup

• 実行は一回のみ必要です
• インストール済みのエディタを自動検出し、MCP 設定を書き込みます
• Claude Code では MCP サーバー・スキル・フック（PreToolUse / PostToolUse）が設定されます

デプロイモードの比較

利用方法

主要コマンドの必須パラメータ

リポジトリのインデックス操作

インデックス作成

gitnexus analyze [path]

• .gitignore と .gitnexusignore を尊重してファイルツリーを走査します
• Tree-sitter AST で 15 以上の言語をパースします
• AGENTS.md と CLAUDE.md をリポジトリルートに生成します
• インデックスデータは .gitnexus/ に保存されます
• グローバルレジストリ ~/.gitnexus/registry.json に登録されます

オプション:

インデックス一覧表示

gitnexus list

インデックス状態確認

gitnexus status

インデックス削除

gitnexus clean

MCP サーバー操作

MCP サーバー起動（stdio）

gitnexus mcp

AI エージェントが stdio 経由でグラフインテリジェンスにアクセスします。

HTTP サーバー起動（Web UI 用）

gitnexus serve
gitnexus serve --port 4747

エディタ別の MCP 設定

Claude Code

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows の場合
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Cursor

設定ファイル: ~/.cursor/mcp.json

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Codex

codex mcp add gitnexus -- npx -y gitnexus@latest mcp

TOML 形式（~/.codex/config.toml）での設定も可能です:

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

OpenCode

設定ファイル: ~/.config/opencode/config.json

{
  "mcp": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

エディタ別のサポート範囲

MCP ツール仕様

query（ハイブリッド検索）

context（360 度シンボルビュー）

呼び出し元・呼び出し先・所属コミュニティ・参加プロセスを一覧で返します。

impact（ブラスト半径分析）

レスポンスは深度（depth）でグルーピングされます。

各リレーションシップの confidence 値は、解決段階で付与されたスコアがそのまま伝播します。minConfidence パラメータで閾値を設定し、低信頼度の依存をフィルタできます。

detect_changes（Git-diff 影響分析）

rename（マルチファイルリネーム）

レスポンス例:

status: success
files_affected: 5
total_edits: 8
graph_edits: 6     (high confidence)
text_search_edits: 2  (review carefully)

グラフベースの編集（high confidence）とテキスト検索ベースの編集（要レビュー）を区別して返します。

cypher（生グラフクエリ）

レスポンス例:

{
  "markdown": "| name | file | confidence |\n| --- | --- | --- |\n| handleLogin | src/api/auth.ts | 0.9 |",
  "row_count": 2
}

代表的なクエリ例:

-- 関数の呼び出し元を検索
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name AS name, caller.filePath AS file, r.confidence AS confidence
ORDER BY r.confidence DESC

-- コミュニティのメンバーを表示
MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
WHERE c.heuristicLabel = "Authentication"
RETURN s.name AS symbol, labels(s)[0] AS type, s.filePath AS file
LIMIT 20

-- プロセスのステップをトレース
MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
WHERE p.heuristicLabel = "LoginFlow"
RETURN s.name AS symbol, r.step AS step, s.filePath AS file
ORDER BY r.step

list_repos（リポジトリ一覧）

パラメータはありません。グローバルレジストリに登録された全リポジトリの名前・パス・最終インデックス日時・統計情報を返します。

検索・分析操作

ハイブリッド検索

gitnexus query "authentication"

BM25 + セマンティック + RRF の複合検索を実行します。

シンボルの 360 度ビュー

gitnexus context login

指定シンボルの定義・呼び出し元・呼び出し先を一覧表示します。

ブラスト半径分析

gitnexus impact updateUser

指定シンボルを変更した場合の影響範囲を解析します。

MCP ツール経由の場合:

gitnexus_impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
});

実務活用シナリオ:

1. PR マージ前の影響確認: gitnexus_impact で影響を受ける関数一覧を取得し、PR 説明に記載
2. リファクタリング前の範囲見積もり: downstream 方向で下流の依存を把握し、テスト対象を特定
3. テストカバレッジの確認: includeTests: true を指定し、影響を受ける関数に対応するテストの有無を確認

Git 差分による影響分析

Git 差分の影響分析は MCP ツール経由で利用します（CLI サブコマンドとしては提供されていません）:

gitnexus_detect_changes({ scope: "compare", base_ref: "main" });

マルチリポジトリグループ操作（Enterprise）

マルチリポジトリのグループ操作は Enterprise 版の機能です。OSS 版の CLI には group サブコマンドは含まれていません。

Enterprise 版では以下の操作が提供されます。

• グループ作成・リポジトリ追加
• グループ間のコントラクト抽出（group sync）
• グループ横断検索（group query）

group sync の内部処理（Enterprise）:

1. グループ内の各リポジトリのインデックスを読み込む
2. GroupConfig.links に定義されたシンボルパターンでクロスリポジトリマッチングを実行
3. マッチしたシンボル間に CrossLink を生成し、ContractRegistry に登録
4. リポジトリ間の API コントラクト（呼び出し関係）が可視化される

ドキュメント生成

gitnexus wiki [path]
gitnexus wiki --model <model>
gitnexus wiki --base-url <url>

MCP リソース（AI エージェント向け）

設定ファイル

.gitnexusignore

リポジトリルートに配置します。.gitignore と同じ書式でインデックス対象外ファイルを指定します。

node_modules/
dist/
*.min.js

大規模リポジトリのヒープ拡張

NODE_OPTIONS="--max-old-space-size=8192" gitnexus analyze

生成ファイルの役割

運用

インデックス更新

コードを変更した後、インデックスは自動更新されません。以下のコマンドで手動更新します。

# 通常の増分再解析
gitnexus analyze

# 強制フルリビルド
gitnexus analyze --force

# 埋め込み生成あり（セマンティック検索を維持する場合）
gitnexus analyze --embeddings

埋め込みの状態は .gitnexus/meta.json の stats.embeddings フィールドで確認できます。--embeddings を省略すると既存の埋め込みが削除されます。

インデックス鮮度チェック

gitnexus status
gitnexus list

gitnexus status はリポジトリ名・インデックス日時・インデックス時コミット SHA・現在のコミット SHA・ステータス（fresh / stale）を出力します。

マルチリポジトリ管理

グローバルレジストリ（~/.gitnexus/registry.json）が全インデックス済みリポジトリを管理します。単一の MCP サーバーで複数のプロジェクトを提供できます。

グループ操作（group create, group add, group sync, group status）は Enterprise 版の機能です。OSS 版では個別リポジトリのインデックス管理（analyze, list, status, clean）が利用できます。

ログ確認・詳細出力

gitnexus analyze --verbose
NODE_ENV=development gitnexus analyze

MCP サーバーライフサイクル

HTTP ブリッジモードのセッションは 30 分間非アクティブで自動タイムアウトします。5 分ごとに期限切れセッションのクリーンアップが実行されます。

ベストプラクティス

CI/CD 連携

Claude Code では PreToolUse フックと PostToolUse フックが自動設定されます。

• PreToolUse: grep / glob / bash の全呼び出しにグラフコンテキストを付加
• PostToolUse: git commit / git merge 後にインデックスを自動再構築

gitnexus setup が Claude Code に自動設定するフック定義（.claude/settings.json）:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Bash",
        "command": "node \"~/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
        "timeout": 10000,
        "statusMessage": "Enriching with graph context..."
      }
    ],
    "PostToolUse": [
      {
        "matcher": "git_commit|git_merge",
        "command": "gitnexus analyze --skip-embeddings --skip-agents-md",
        "timeout": 60000,
        "statusMessage": "Reindexing after commit..."
      }
    ]
  }
}

matcher のツール名は大文字始まり（Grep, Glob, Bash）です。コマンドは gitnexus-hook.cjs スクリプトを経由して実行されます。

gitnexus setup が生成するスキルファイル（.claude/skills/gitnexus-*.md）は、AI エージェントがナレッジグラフを活用するためのガイドを提供します。4 種類のスキルが自動インストールされます。

• gitnexus-explore: 未知のコードベースをグラフ経由で探索する手順
• gitnexus-debug: コールチェーンを辿ってバグの原因を特定する手順
• gitnexus-impact-analysis: 変更前にブラスト半径を確認する手順
• gitnexus-refactor: 依存グラフを参照して安全にリファクタリングする手順

CI パイプラインへの組み込み:

git clone <repo-url>
gitnexus analyze --skip-embeddings --skip-agents-md
gitnexus mcp

--skip-agents-md を指定すると、カスタマイズ済みの AGENTS.md / CLAUDE.md を上書きしません。

コミット前の変更影響確認:

gitnexus_detect_changes({ scope: "compare", base_ref: "main" })
gitnexus_impact({ target: "symbolName", direction: "upstream" })

大規模リポジトリ対応

gitnexus analyze --skip-embeddings
NODE_OPTIONS="--max-old-space-size=16384" gitnexus analyze

.gitnexusignore で不要なディレクトリを除外します。Web UI のブラウザメモリ制限（約 5000 ファイル）を超えるリポジトリには Bridge Mode を使います。

gitnexus serve

セキュリティ

インデックス管理

gitnexus clean
gitnexus clean --all --force
npx kuzu .gitnexus/lbug

トラブルシューティング

頻出エラーと解決手順

診断コマンド一覧

gitnexus status
gitnexus list
gitnexus clean
gitnexus clean --all --force
NODE_ENV=development gitnexus analyze
npx kuzu .gitnexus/lbug
cat ~/.gitnexus/registry.json
ls -la .gitnexus/

まとめ

GitNexus は、ソースコードからナレッジグラフを事前構築し、AI エージェントが構造的なコード理解に基づいて安全に変更を加えられるようにするツールです。MCP ネイティブ統合・ブラスト半径分析・ハイブリッド検索といった機能により、コーディングエージェントの「影響範囲を把握できない」課題を解決します。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • GitNexus README.md
  • GitNexus CLAUDE.md
  • GitNexus Troubleshooting - Mintlify
• GitHub
  • GitHub - abhigyanpatwari/GitNexus
• 記事
  • abhigyanpatwari/GitNexus | DeepWiki
  • GitNexus Data Model - DeepWiki
  • GitNexus Operations and Configuration - DeepWiki
  • GitNexus Turns Your Codebase Into a Knowledge Graph
  • GitNexus: The Zero-Server Code Intelligence Engine - Big Hat Group