davidw-philips/cgraph

CodeGraph (codegraph)

codegraph は、コードベース内のすべてのシンボル、呼び出しエッジ、依存関係のローカルで自動同期する知識グラフ（SQLite）を構築・維持します。初期化後、エージェントは codegraph_explore MCPツールを介して、構造に関する質問にグラフから直接回答できます。わずか1回の呼び出しで、ファイル読み取りはゼロです。grep/readループは不要です。

使用するタイミング

• 「X はどのように動作するか？」「X から Y にどのように到達するか？」といった質問に答えたり、アクティブなリポジトリの未知の領域を調査する場合。
• 関数の呼び出し元/呼び出し先の検索、呼び出しパスの追跡、変更の影響範囲（ブラストラディウス）のスコープを特定する場合。
• CodeGraph バックグラウンドデーモンや環境プロセスの起動、管理、停止を行う場合。
• Git ブランチ、リベース、Git ワークツリー間でのグラフインデックスのナビゲートと保守を行う場合。
• 従来は grep や複数ファイルの読み取りで構造を手動で再構築していたような質問全般。

まだ .codegraph/ インデックスがないリポジトリ（最初に codegraph init を実行してください）や、ローカルにインデックスしていない外部/公開リポジトリには使用しないでください。そのような場合は deepwiki スキルを優先してください。

事前チェック

command -v codegraph || Get-Command codegraph

不足している場合は、INSTALL.md を参照するか、以下を使用して直接インストールしてください。

# macOS / Linux — Node.js は不要、独自ランタイムをバンドル
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) — Node.js は不要
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

ほとんどの環境ではこれで十分です。以下のワークフローと起動に進んでください。npm インストールパスや CodeGraph の Node ライブラリ API がどうしても必要な場合にのみ、バンドルされた scripts/（INSTALL.md を参照）を使用してください。

ワークフローと起動

1. マシンごとの初期セットアップ

CodeGraph をこのエージェントに組み込みます（変更前に確認を求めます）。

codegraph install

2. プロジェクトごとの初回セットアップ

アクティブなプロジェクトのグラフを構築します（.codegraph/codegraph.db を作成し、完全な初期インデックスを実行します）。

cd your-project
codegraph init

3. 日常的な起動（作業開始時）

作業を開始する前に、手動でデーモンやバックグラウンドサービスを起動する必要はありません。

• エージェントセッション (MCP): AI ホスト（VS Code Copilot、Claude Code など）は、codegraph serve --mcp を介して MCP サーバーを自動的に起動します。サーバーは、必要に応じてバックグラウンドデーモンに接続するか、デーモンを起動します。OS のファイルシステムウォッチャーも含まれます。
• ヘルスチェック: codegraph status を実行して、インデックスの健全性、シンボル数/エッジ数、保留中の同期項目を確認します。
• キャッチアップ同期: エージェントが閉じられている間にファイルが変更された場合（例：プルされたコミット）、codegraph sync を実行して即座に高速な増分更新を行います。

4. 構造のクエリ

エージェントは、一度組み込まれると、codegraph_explore MCP ツールを自身で呼び出します。同じ機能はシェルからも利用できます。

codegraph explore "X から Y への到達方法は?"
codegraph callers someFunction
codegraph callees someFunction
codegraph impact someSymbol

環境とデーモンのライフサイクル

CodeGraph はデフォルトでバックグラウンドデーモン（daemon mode）を実行するため、複数のクライアントセッションが単一のウォッチャー、キャッシュ、SQLite ハンドルを共有できます。

デーモンの停止

• インタラクティブ停止: codegraph daemon（または codegraph daemons）を実行します。プロジェクトのデーモンを選択するか（先頭に表示されます）、すべてのデーモンを停止するを選択します。
• スクリプト/非対話型停止: デーモンはその PID を <project_root>/.codegraph/daemon.pid に記録します。そのプロセス ID を直接終了するか（~/.codegraph/daemons/<hash>.json を調べてください）、停止します。
• 古いロックのクリア: プロセスがクラッシュしたり、強制終了された場合、以下のコマンドで古いロックや孤立したデーモンのアーティファクトをクリアします。

  codegraph unlock
  

環境トグル（デーモンとウォッチャー）

• ダイレクトモード（デーモンなし）: CODEGRAPH_NO_DAEMON=1 を設定すると、各 MCP および CLI セッションが共有デーモンに接続する代わりに、独立した自己完結型のプロセスとして実行されるよう強制します。
• ファイルウォッチャーの無効化: CODEGRAPH_NO_WATCH=1 を設定するか（または --no-watch フラグを使用）、ライブファイルシステムウォッチャーを無効にします。低速なファイルシステム（WSL2 の /mnt/ ドライブ、ネットワークマウント）やバッテリー駆動時間が制限されている環境で推奨されます。

廃止 / 初期化解除

• プロジェクトからの削除: codegraph uninit を実行すると、.codegraph/ インデックスが削除され、Git 同期フックも削除されます（--force で確認をスキップ）。
• マシンからの削除: codegraph uninstall を実行します（codegraph uninstall --keep-cli で CLI バイナリを保持）。

Git ブランチとワークツリーの操作

Git ブランチ切り替え（単一のワーキングツリー）

• ファイルシステムベースの同期: CodeGraph は git status ではなく、SQLite のファイルパスとコンテンツハッシュを追跡します。ブランチを切り替える（git switch <branch> または git checkout <branch>）と、ディスク上のファイルが変更されます。ファイルウォッチャーが変更を自動的に検出し、約 2 秒以内にインデックスを増分同期します。
• 手動同期: チェックアウト中にウォッチャーが無効または非アクティブだった場合は、codegraph sync を実行して高速な増分キャッチアップを行います。
• 大規模なリベース / 再構築: 大規模なリベースや競合の多いブランチマージの後は、以下でクリーンなインデックス再構築を強制します。

  codegraph index --force
  

• Git 同期フック（ウォッチャーオフ時）: CODEGRAPH_NO_WATCH=1 が設定されている場合、CodeGraph は post-commit、post-merge、post-checkout フックをインストールし、ブランチ切り替え後にバックグラウンドで codegraph sync を自動的に呼び出すことができます。

Git ワークツリーと「インデックスの借用」リスク

• インデックス検出: CodeGraph は、現在の作業ディレクトリから親ディレクトリをたどって .codegraph/ を検出します。
• リスク: Git ワークツリー（例：git worktree add ../feature-worktree feature）を使用する場合、ワークツリーに独自の .codegraph/ ディレクトリがないと、CodeGraph は親ディレクトリをたどってメインチェックアウトの .codegraph/ インデックスにバインドされます。ワークツリー内のクエリは、メインチェックアウトのブランチからのシンボルとソースを返すため、ワークツリー固有の変更が欠落します！
• 不一致検出: CodeGraph は detectWorktreeIndexMismatch をチェックし、git rev-parse --show-toplevel と git rev-parse --git-common-dir を介した indexRoot を比較します。ワークツリーがメインインデックスを借用している場合、CodeGraph は codegraph status および MCP クエリツールで警告を発行します。
• ワークツリーの黄金律: 各ワークツリーディレクトリ内で必ず codegraph init（または codegraph init -i）を実行してください。各ワークツリーは、そのブランチを独立してインデックス化するために、専用の .codegraph/ ディレクトリを持っている必要があります。
• カスタムディレクトリ分離: カスタムインデックスフォルダ命名や分離が必要な場合（例：Windows と WSL2 のチェックアウトを分離する場合）、CODEGRAPH_DIR（例：export CODEGRAPH_DIR=.codegraph-worktree）を設定します。

ルール

• グラフの結果を信頼してください。グラフはファイルウォッチャー（保存後 2 秒のデバウンス）を介して同期が保たれます。grep で再確認しないでください。
• codegraph_explore が返したソースはすでに読み取られたものとして扱い、Read ツールで同じファイルを開き直さないでください。
• .codegraph/ インデックスがあるプロジェクトに対してのみクエリを実行してください。インデックスがないパスは、代わりに組み込みツールを使用するように明確にガイダンスを返します。インデックス作成は意図的な決定であり、自動ではありません。
• Git ワークツリーでは、codegraph status を使用して、ワークツリーがメインツリーのインデックスを借用するのではなく、独自のローカルインデックスを持っていることを確認してください。
• より狭い範囲の隠しツール（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）よりも、codegraph_explore（または CLI からの codegraph explore）を優先してください。これらのツールが返すものはすべて、codegraph_explore にインラインで既に含まれています。

インストールオプションについては INSTALL.md を参照してください。これには、scripts/ 内のバンドルされた Node.js チェッカー/インストーラスクリプトが含まれており、npm インストールパスまたはライブラリ埋め込みにのみ必要です。