Project Code Intelligence

コーディングエージェントのためのリポジトリインテリジェンスと変更安全性のエビデンス。

Project Code Intelligence (PCI) は Git リポジトリをインデックス化し、調査、リファクタリング、保守、セキュリティ作業のための構造化されたエビデンスをコーディングエージェントに提供します。エージェントは、概念や識別子で検索し、候補となる関係を調査し、変更の影響範囲 (blast radius) を見積もり、繰り返される実装パターンを見つけ、コードを編集する前に静的解析の結果を照会できます。

PCI は自律的なレビューアではなく、そのグラフはコンパイラ級のコールグラフでもありません。探索範囲を絞り込み、エビデンスを提供するものであり、重要な結論はエージェントがソース上で検証します。

役立つ用途

調査とオリエンテーション

• 正確な識別子、ファイル名、設定キー、既知の文字列を検索します。

• 関連する名前が不明な場合は、動作で検索します。

• リポジトリの言語、ファイルの役割、スナップショット、パーサーのカバレッジ、インデックスの鮮度を確認します。

• パス、行範囲、メタデータ、ソーススニペットを含む上限付きレコードを取得します。

• 名前付きコレクションとリポジトリフィルターを使用して、複数のリポジトリにわたって作業します。

より安全な変更

• 候補となる呼び出し元、呼び出し先、参照、テスト、モジュールレベルの配線を見つけます。

• シンボルを削除、名前変更、または変更する前に、影響範囲のエビデンスを確認します。

• エントリーポイント、孤立コード、テストカバレッジのシグナルを明らかにします。

• 定義が追加または削除されたときに、サポートされているコーディングエージェントに近傍のエビデンスを注入します。

保守と冗長性

• 呼び出し形状のモチーフを繰り返す関数グループを見つけます。

• 冗長性の候補を、類似度、推定される抽象化コスト、推定される正味の価値でランク付けします。

• 古いインデックス、重複する名前、冗長性の候補、静的解析の結果についてリポジトリ監査を実行します。

セキュリティと静的解析

• ソースレコードとともに SARIF レポートを取り込みます。

• 正規化された検出結果を、ツール、ルール、レベル、ベースライン状態、またはパスで検索します。

• エージェントに生の SARIF アーティファクトを解析させることなく、診断情報、コードフロー、実行メタデータを取得します。

Related MCP server: Graft

仕組み

pci index はリポジトリのファイルを上限付きレコードに解析し、メタデータと候補となる関係を抽出し、スナップショットを Postgres/pgvector に保存します。セマンティック埋め込みはオプションです。--no-embed を使用しても、字句検索とほとんどの構造的エビデンスは引き続き利用できます。

pci mcp は、ローカルの stdio MCP サーバーを通じてインデックスを公開します。コーディングエージェントは、そのフィルター指向のツールを使用して関連性の高いコードを発見し、行動する前にライブソースを読んで検証します。

デフォルトのローカルアーキテクチャは次のとおりです。

• Postgres/pgvector: Docker または Podman Compose。

• Linux 埋め込みサービス: ユーザー systemd で管理される Podman Quadlet ユニット。

• Apple Silicon 埋め込み: ネイティブの MLX サービス。

• エージェント統合: オプションの編集エビデンスフックを備えた stdio MCP サーバー。

意図的なトレードオフがある場合、リモートの Postgres および OpenAI 互換の埋め込みエンドポイントがサポートされます。

クイックスタート

チェックアウトから CLI をインストールします:

uv tool install /path/to/project-code-intelligence
export PATH="$HOME/.local/bin:$PATH"

バンドルされたデータベースと、利用可能な最良のローカル埋め込みバックエンドを起動します:

pci doctor --start
pci doctor

Git リポジトリをインデックス化します:

cd /path/to/repo
pci index .

コーディングエージェント用の MCP 設定をインストールします:

pci mcp install --target codex

サポートされているターゲットには、claude、codex、opencode、pi、vscode、copilot、cline、zed が含まれます。クライアント固有のセットアップ、プロジェクトのスコープ設定、資格情報の処理については、docs/MCP_SETUP.md を参照してください。

埋め込みなしの字句検索の場合:

pci doctor --start-db
pci index --no-embed .

コアエージェントツール

ツリー全体のエビデンスレポートについては、pci audit を実行してください。

エビデンスであって、判定ではない

PCI は、より強力なインデックス化された事実と、近似的かつヒューリスティックなエビデンスを意図的に区別しています。

• 候補となる関係エッジは、型チェックされたコールグラフの事実ではありません。

• 影響範囲は、変更が安全であることを証明できません。

• 冗長性スコアは、2つの関数が抽象化を共有すべきかどうかを決定できません。

• 静的解析の検出結果には、元のアナライザーの限界が引き継がれます。

• 未コミットまたは新しくコミットされた変更の後、インデックスが古くなる可能性があります。

• セマンティック検索は、関連するコードを見逃したり、もっともらしい近傍を返したりする可能性があります。

重要な呼び出し元と検出結果は、ライブソースで検証してください。既知のパスや小さな範囲の質問には、直接のファイル読み取りを使用してください。PCI は、場所、名前、または影響がまだ不明な場合に最も役立ちます。

インストール

Python CLI

uv を使用して現在のユーザーにインストールします:

uv tool install /path/to/project-code-intelligence

編集可能な開発インストールの場合:

cd /path/to/project-code-intelligence
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Nix

NixOS または flakes が有効な別の Linux ホスト上で:

nix build
nix run . -- doctor --skip-db --embedding skip
nix develop

ユーザープロファイルに永続的にインストールします:

nix profile install .#project-code-intelligence

Nix クロージャには、CLI、MCP サーバー、Python 依存関係、バンドルされた Compose および Quadlet アセットが含まれます。重量級の Linux 埋め込みランタイムは、ホストネイティブの Nix 依存関係になるのではなく、Podman コンテナ内に残ります。

ローカルデータベース

バンドルされた Postgres/pgvector データベースのみを起動します:

pci doctor --start-db

インストールされた Compose ファイルはユーザーキャッシュに具体化されます。代わりにカスタムコピーを使用するには:

export PCI_COMPOSE_FILE=/path/to/docker-compose.yml
pci doctor --start-db

ローカル埋め込みサービス

CLI にはサービステンプレートが含まれています。別個の PCI 埋め込みパッケージはありません。Linux では、Podman をインストールし、systemctl --user が機能することを確認してから、次を実行します:

pci doctor
pci doctor --start-embedding

PCI は利用可能なハードウェアを検出し、選択されたバックエンドのみを ~/.config/containers/systemd/ の下に具体化し、ユーザー systemd をリロードして起動します。他の埋め込みバックエンド用の古い PCI ユニットは停止され、削除されます。イメージとデフォルトモデルは初回使用時にダウンロードされます。

必要に応じてバックエンドを明示的に選択します:

# AMD GPU
pci doctor --start-embedding --embedding-backend rocm

# NVIDIA GPU
pci doctor --start-embedding --embedding-backend cuda

# Portable CPU fallback
pci doctor --start-embedding --embedding-backend fastembed

# AMD Ryzen AI NPU (experimental)
pci doctor --start-embedding --embedding-backend lemonade

利用可能なセレクターは、auto、fastembed、lemonade、rocm、cuda、apple です。PCI は、要求されたバックエンドの必要なハードウェアまたはランタイムが利用できない場合、そのバックエンドを拒否します。apple は Quadlet 経由ではなくネイティブで実行されます。

データベースと明示的なバックエンドを一緒に起動するには:

pci doctor --start --embedding-backend rocm

コンテナ化されたバックエンドは、デフォルトで http://127.0.0.1:18081/v1/embeddings に OpenAI 互換のエンドポイントを公開します。このエンドポイントを共有するため、ローカルバックエンドは一度に1つだけ実行してください。

データベースに触れずに埋め込みサービスを停止します:

pci doctor --stop-embedding

生成されたローカルサービス、キャッシュ、バンドルされたデータベースボリュームを削除します:

pci doctor --clean

--clean は破壊的であり、データを削除する前にプロンプトを表示します。

リモート埋め込み

データベースのみを起動し、信頼できる OpenAI 互換プロバイダーを設定します:

pci doctor --start-db
export PCI_ALLOW_REMOTE_EMBEDDING=1
export PCI_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
export PCI_EMBEDDING_ENDPOINT_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
pci doctor

リモートエンドポイントはソース由来のテキストを受け取ります。インデックス化されるリポジトリにとってそれが許容される場合にのみ有効にしてください。

リポジトリのインデックス化

1つのリポジトリをインデックス化します:

pci index /path/to/repo

複数のリポジトリをワークスペースとしてインデックス化します:

cd /path/to/workspace
pci index service-api web-ui shared-lib

PCI はパスからコレクション名とリポジトリ名を推測します。MCP クライアントは、絶対ファイルシステムパスではなく、これらの論理名でフィルタリングします。インデックス化は増分的です。互換性のあるスナップショットが存在する場合、変更されていないファイルは再利用されます。

インデックス化されたリポジトリパスの下にある SARIF レポートは自動的に取り込まれます。1つのリポジトリをリセットして再構築するには:

pci index --reset /path/to/repo

インデックス実行を検査するには pci status を、パーサー、埋め込み、コレクション、データベースのオプションについては pci index --help を使用してください。

MCP とエージェントフック

プロジェクトスコープの読み取り専用データベース資格情報を作成し、MCP 設定を出力します:

pci index --init-db --mcp-config codex .

再インデックス化せずに MCP 設定をインストールまたは削除します:

pci mcp install --target codex
pci mcp install --target codex --uninstall

生成されたクライアント設定にはデータベースパスワードは含まれません。資格情報は、ユーザーの PCI 設定ディレクトリの下にモード 0600 で保存されます。Pi はプロジェクトローカルの .pi/extensions/ MCP ブリッジを使用します。Cline は設定ファイルがユーザースコープであるため、--config-path が必要です。

オプションのフックは、エージェントにインデックスの使用を促し、定義を追加または削除する編集の近くにエビデンスを注入できます:

pci hook install --target codex

フックのサポートとインストールの詳細はクライアントによって異なります。フックは支援であり、強制や正当性を保証するメカニズムではありません。docs/MCP_SETUP.md と docs/SYSTEM_PROMPT.md を参照してください。

プライバシーとセキュリティ

ローカルのデフォルトでは、ソース由来のレコードと埋め込みはマシン上に保持されます。しかし、すべてのアーティファクトが公開しても安全であるとは限りません。

データベースダンプ、リストアアーティファクト、SARIF 出力、埋め込みキャッシュ、モデルファイル、ベクターインデックス、プライベートリポジトリから生成されたデータ、ローカル MCP 資格情報ファイルをコミットまたは配布しないでください。これらには、ソース由来のソーススニペット、パス、シンボル、検出結果、メタデータ、埋め込みが含まれる可能性があります。

コレクションはリポジトリを整理しますが、セキュリティ境界ではありません。リポジトリにより強力な分離が必要な場合は、別のデータベースまたはデータベースユーザーを使用してください。プロジェクトスコープの MCP 資格情報は通常のアクセスを制限しますが、ホストとデータベースのセキュリティを置き換えるものではありません。

PCI が適している場合

PCI は次の場合に役立ちます:

• リポジトリまたはワークスペースが大規模または不慣れな場合;

• タスクの開始時に識別子が不明な場合;

• 生成されたファイルにより広範な読み取りが高コストまたはノイズが多い場合;

• リファクタリングに呼び出し元、テスト、配線のエビデンスが必要な場合;

• 保守作業に繰り返しパターンの発見が必要な場合;

• 静的解析の検出結果をソースと関連付ける必要がある場合;

• 複数のリポジトリを1つのインターフェースで検索する必要がある場合。

小さく馴染みのあるリポジトリ、既知のファイルと行範囲、または範囲を限定した1回の rg 検索やファイル読み取りで答えられる質問には、ほとんど価値を追加しないかもしれません。目標は標準的な開発者ツールを置き換えることではなく、その周辺の不確実な発見と変更計画のステップを改善することです。

トークンとコストの削減は有用な副次効果になり得ますが、PCI はそれを保証しません。docs/EVALUATING_VALUE.md と セッション振り返りプロンプト を使用して、インデックスが実際のセッションを改善するかどうかを測定してください。

開発

MCP サーバーは stdio を使用します。Docker Compose はローカルデータベース用であり、MCP プロセスをホストするためではありません。完全な開発ゲートを実行するには:

nix develop
make check

取り込み、データベース、または MCP の動作変更の場合は、次も実行します:

docker compose up -d pgvector
make integration-smoke

プロジェクトの規約と公開の保護策については、CONTRIBUTING.md と AGENTS.md を参照してください。

ドキュメント

• docs/MCP_SETUP.md — MCPクライアント、スコープ、認証情報、セキュリティモデル

• docs/PUBLIC_API.md — CLI、環境、MCP、Python互換性のサーフェス

• docs/EVALUATING_VALUE.md — 実際のコーディングセッションでのPCIの評価

• docs/SYSTEM_PROMPT.md — PCIを使用するためのエージェント指示

• docs/SYSTEM_PROMPT_RATIONALE.md — プロンプト設計の根拠

• docs/SESSION_RETROSPECTIVE_PROMPT.md — セッション終了時の評価プロンプト

• .env.example — 環境設定のリファレンス

• CONTRIBUTING.md — 開発ワークフロー

ライセンス

MIT。 LICENSE を参照。