Projekt-Code-Intelligenz

Repository-Intelligenz und Änderungssicherheits-Nachweise für Codierungsagenten.

Projekt-Code-Intelligenz (PCI) indexiert Git-Repositories und gibt Codierungsagenten strukturierte Nachweise für Recherche, Refactoring, Wartung und Sicherheitsarbeit. Agenten können nach Konzept oder Bezeichner suchen, Kandidatenbeziehungen untersuchen, den Auswirkungsbereich einer Änderung einschätzen, wiederholte Implementierungsmuster finden und Static-Analysis-Befunde abfragen, bevor sie Code bearbeiten.

PCI ist kein autonomer Reviewer und sein Graph ist kein Compiler-genauer Call-Graph. Er grenzt die Suche ein und liefert Nachweise; der Agent verifiziert wichtige Schlussfolgerungen weiterhin im Quellcode.

Wobei es hilft

Recherche und Orientierung

• Suche nach exakten Bezeichnern, Dateinamen, Konfigurationsschlüsseln und bekannten Zeichenfolgen.

• Suche nach Verhalten, wenn die relevanten Namen unbekannt sind.

• Untersuche Repository-Sprachen, Dateirollen, Snapshots, Parser-Abdeckung und Index-Frische.

• Rufe begrenzte Datensätze mit Pfaden, Zeilenbereichen, Metadaten und Quellcode-Ausschnitten ab.

• Arbeite über mehrere Repositories hinweg über benannte Sammlungen und Repository-Filter.

Sicherere Änderungen

• Finde Kandidaten für Aufrufer, Aufgerufene, Referenzen, Tests und Modul-Verdrahtung.

• Prüfe Nachweise zum Auswirkungsbereich, bevor du ein Symbol entfernst, umbenennst oder änderst.

• Hebe Einstiegspunkt-, Waisen- und Testabdeckungssignale hervor.

• Spritze nahegelegene Nachweise in unterstützte Codierungsagenten ein, wenn Definitionen hinzugefügt oder entfernt werden.

Wartung und Redundanz

• Finde Gruppen von Funktionen, die ein Aufrufstruktur-Motiv wiederholen.

• Bewerte Redundanzkandidaten nach Ähnlichkeit, geschätzten Abstraktionskosten und wahrscheinlichem Nettonutzen.

• Führe ein Repository-Audit für veraltete Indizes, doppelte Namen, Redundanz kandidaten und statische Befunde durch.

Related MCP server: Graft

Sicherheit und statische Analyse

• Nimm SARIF-Berichte zusammen mit Quellcode-Datensätzen auf.

• Suche normalisierte Befunde nach Tool, Regel, Ebene, Baseline-Status oder Pfad.

• Rufe Diagnosen, Code-Flows und Ausführungsmetadaten ab, ohne dass ein Agent rohe SARIF-Artefakte parsen muss.

So funktioniert es

pci index parst Repository-Dateien in begrenzte Datensätze, extrahiert Metadaten und Kandidatenbeziehungen und speichert Snapshots in Postgres/pgvector. Semantische Einbettungen sind optional: Lexikalische Suche und die meisten strukturellen Nachweise bleiben mit --no-embed verfügbar.

pci mcp stellt den Index über einen lokalen stdio-MCP-Server bereit. Codierungsagenten nutzen dessen filterorientierte Tools, um wahrscheinlich relevante Code-Stellen zu finden, und lesen und verifizieren dann den Live-Quellcode, bevor sie handeln.

Die Standardarchitektur für den lokalen Betrieb ist:

• Postgres/pgvector: Docker- oder Podman-Compose.

• Linux-Einbettungsdienste: Podman-Quadlet-Einheiten, die vom systemd des Benutzers verwaltet werden.

• Apple-Silicon-Einbettungen: ein nativer MLX-Dienst.

• Agentenintegration: ein stdio-MCP-Server mit optionalen Bearbeitungs-Nachweis-Hooks.

Remote-Postgres- und OpenAI-kompatible Einbettungsendpunkte werden unterstützt, wenn dieser Kompromiss beabsichtigt ist.

Schnellstart

Installiere die CLI aus einem Checkout:

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

Starte die gebündelte Datenbank und das beste verfügbare lokale Einbettungs-Backend:

pci doctor --start
pci doctor

Indexiere ein Git-Repository:

cd /path/to/repo
pci index .

Installiere die MCP-Konfiguration für deinen Codierungsagenten:

pci mcp install --target codex

Unterstützte Ziele sind claude, codex, opencode, pi, vscode, copilot, cline und zed. Siehe docs/MCP_SETUP.md für client-spezifische Einrichtung, Projektabgrenzung und Umgang mit Anmeldedaten.

Für lexikalische Suche ohne Einbettungen:

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

Kern-Agenten-Tools

Führe pci audit für einen Gesamtbaum-Nachweisbericht aus.

Nachweise, keine Urteile

PCI unterscheidet bewusst zwischen stärkeren indexierten Fakten und approximativen und heuristischen Nachweisen.

• Kandidatenbeziehungs-Kanten sind keine typgeprüften Call-Graph-Fakten.

• Der Ausblasbereich kann nicht beweisen, dass eine Änderung sicher ist.

• Redundanzbewertungen können nicht entscheiden, ob zwei Funktionen eine Abstraktion teilen sollten.

• Statische Befunde behalten die Einschränkungen ihres Ursprungsanalysators bei.

• Ein Index kann nach nicht committeten oder neu committeten Änderungen veraltet sein.

• Semantische Abfragen können relevante Code übersehen oder plausible Nachbarn zurückgeben.

Verifiziere wichtige Aufrufer und Befunde im Live-Quellcode. Verwende direkte Dateilesevorgänge für bekannte Pfade und kleine begrenzte Fragen; PCI ist am nützlichsten, wenn der Ort, der Name oder die Auswirkung noch nicht bekannt ist.

Installation

Python-CLI

Installiere für den aktuellen Benutzer mit uv:

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

Für eine bearbeitbare Entwicklungsinstallation:

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

Nix

Auf NixOS oder einem anderen Linux-Host mit aktivierten Flakes:

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

Installiere dauerhaft in das Benutzerprofil:

nix profile install .#project-code-intelligence

Die Nix-Closure enthält die CLI, den MCP-Server, Python-Abhängigkeiten und die gebündelten Compose- und Quadlet-Assets. Schwere Linux-Einbettungslaufzeiten bleiben in Podman Containern, anstatt host-native Nix-Abhängigkeiten zu werden.

Lokale Datenbank

Starte nur die gebündelte Postgres/pgvector-Datenbank:

pci doctor --start-db

Die installierte Compose-Datei wird in einen Benutzer-Cache materialisiert. Um eine benutzerdefinierte Kopie zu verwenden:

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

Lokaler Einbettungsdienst

Die CLI enthält die Dienstvorlagen; es gibt kein separates PCI-Einbettungspaket. Auf Linux installiere Podman und stelle sicher, dass systemctl --user funktioniert, dann führe aus:

pci doctor
pci doctor --start-embedding

PCI erkennt verfügbare Hardware, materialisiert nur das ausgewählte Backend unter ~/.config/containers/systemd/, lädt das Benutzer-systemd neu und startet es. Veraltete PCI Einheiten für andere Einbettungs-Backends werden gestoppt und entfernt. Bilder und Standardmodelle werden bei der ersten Verwendung heruntergeladen.

Wähle ein Backend explizit aus, wenn gewünscht:

# 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

Verfügbare Auswahlmöglichkeiten sind auto, fastembed, lemonade, rocm, cuda und apple. PCI lehnt ein angefragtes Backend ab, wenn die erforderliche Hardware oder Laufzeit nicht verfügbar ist. apple läuft nativ und nicht über Quadlet.

Um die Datenbank und ein explizites Backend zusammen zu starten:

pci doctor --start --embedding-backend rocm

Containerisierte Backends veröffentlichen standardmäßig einen OpenAI-kompatiblen Endpunkt unter http://127.0.0.1:18081/v1/embeddings. Führe jeweils nur ein lokales Backend aus, da sie diesen Endpunkt teilen.

Stoppe Einbettungsdienste, ohne die Datenbank zu berühren:

pci doctor --stop-embedding

Entferne generierte lokale Dienste, Caches und den gebündelten Datenbank-Volume:

pci doctor --clean

--clean ist destruktiv und fragt vor dem Entfernen von Daten nach.

Remote-Einbettungen

Starte nur die Datenbank und konfiguriere dann einen vertrauenswürdigen OpenAI-kompatiblen Anbieter:

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

Remote-Endpunkte erhalten quellabgeleiteten Text. Aktiviere sie nur, wenn das für die indexierten Repositories akzeptabel ist.

Repositories indexieren

Indexiere ein Repository:

pci index /path/to/repo

Indexiere mehrere Repositories als Arbeitsbereich:

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

PCI leitet Sammlungs- und Repository-Namen aus den Pfaden ab. MCP-Clients filtern nach diesen logischen Namen und nicht nach absoluten Dateisystempfaden. Die Indexierung ist inkrementell: unveränderte Dateien werden wiederverwendet, wenn kompatible Snapshots existieren.

SARIF-Berichte, die unter indexierten Repository-Pfaden gefunden werden, werden automatisch übernommen. Setze ein Repository zurück und baue es neu auf mit:

pci index --reset /path/to/repo

Verwende pci status, um Indexierungsläufe zu überprüfen, und pci index --help für Parser-, Einbettungs-, Sammlungs- und Datenbankoptionen.

MCP- und Agenten-Hooks

Erstelle projektspezifische schreibgeschützte Datenbank-Anmeldedaten und drucke eine MCP-Konfiguration:

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

Installiere oder entferne die MCP-Konfiguration ohne Neuindexierung:

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

Die generierte Client-Konfiguration enthält kein Datenbank-Passwort. Anmeldedaten werden unter dem PCI-Konfigurationsverzeichnis des Benutzers mit Modus 0600 gespeichert. Pi verwendet eine projektlokale .pi/extensions/-MCP-Brücke. Cline erfordert --config-path, da seine Einstellungsdatei benutzerbezogen ist.

Optionale Hooks können einen Agenten an die Verwendung des Index erinnern und Nachweise in die Nähe von Bearbeitungen einfügen, die Definitionen hinzufügen oder entfernen:

pci hook install --target codex

Die Hook-Unterstützung und Installationsdetails variieren je nach Client. Hooks sind eine Hilfe, kein Durchsetzungs- oder Korrektheitsmechanismus. Siehe docs/MCP_SETUP.md und docs/SYSTEM_PROMPT.md.

Datenschutz und Sicherheit

Der lokale Standard hält quellabgeleitete Datensätze und Einbettungen auf der Maschine. Das macht nicht jedes Artefakt sicher zu veröffentlichen.

Commite oder verteile keine Datenbank-Dumps, Wiederherstellungs-Artefakte, SARIF-Ausgaben, Einbettungs-Caches, Modelldateien, Vektorindizes, generierte Daten aus privaten Repositories oder lokale MCP-Anmeldedateien. Sie können Quellcode-Ausschnitte, Pfade, Symbole, Befunde, Metadaten und aus Quellcode abgeleitete Einbettungen enthalten.

Sammlungen organisieren Repositories, sind aber keine Sicherheitsgrenze. Verwende separate Datenbanken oder Datenbankbenutzer, wenn Repositories eine stärkere Isolierung erfordern. Projektspezifische MCP-Anmeldedaten schränken den normalen Zugriff ein, ersetzen aber nicht die Host- und Datenbanksicherheit.

Wann PCI gut passt

PCI hilft tendenziell, wenn:

• das Repository oder der Arbeitsbereich groß oder unbekannt ist;

• Bezeichner zu Beginn einer Aufgabe unbekannt sind;

• generierte Dateien breite Lesevorgänge teuer oder verrauscht machen;

• ein Refactoring Aufrufer-, Test- und Verdrahtungsnachweise benötigt;

• Wartungsarbeiten die Entdeckung wiederholter Muster erfordern;

• statische Befunde mit dem Quellcode korreliert werden müssen;

• mehrere Repositories über eine Schnittstelle durchsucht werden müssen.

Es kann für ein kleines vertrautes Repository, eine bekannte Datei und einen Zeilenbereich oder eine Frage, die durch einen begrenzten rg- oder Dateilesevorgang beantwortet wird, wenig Mehrwert bieten. Das Ziel ist nicht, Standard-Entwicklerwerkzeuge zu ersetzen; es ist, die unsicheren Entdeckungs- und Änderungsplanungsschritte um sie herum zu verbessern.

Token- und Kostenreduzierung kann ein nützlicher Nebeneffekt sein, aber PCI verspricht sie nicht. Miss, ob der Index echte Sitzungen verbessert, mit docs/EVALUATING_VALUE.md und dem Sitzungs-Retrospektiv-Prompt.

Entwicklung

Der MCP-Server verwendet stdio; Docker Compose ist für die lokale Datenbank, nicht für das Hosten des MCP-Prozesses. Führe das vollständige Entwicklungs-Gate aus mit:

nix develop
make check

Für Änderungen am Ingest, an der Datenbank oder am MCP-Verhalten führe auch aus:

docker compose up -d pgvector
make integration-smoke

Siehe CONTRIBUTING.md und AGENTS.md für Projektkonventionen und Veröffentlichungsschutzmaßnahmen.

Dokumentation

• docs/MCP_SETUP.md — MCP-Clients, Scopes, Anmeldedaten und Sicherheitsmodell

• docs/PUBLIC_API.md — CLI-, Umgebungs-, MCP- und Python-Kompatibilitätsoberflächen

• docs/EVALUATING_VALUE.md — Bewertung von PCI anhand realer Coding-Sitzungen

• docs/SYSTEM_PROMPT.md — Agentenanweisungen zur Verwendung von PCI

• docs/SYSTEM_PROMPT_RATIONALE.md — Begründung des Prompt-Designs

• docs/SESSION_RETROSPECTIVE_PROMPT.md — Evaluations-Prompt am Ende der Sitzung

• .env.example — Referenz zur Umgebungskonfiguration

• CONTRIBUTING.md — Entwicklungsworkflow

Lizenz

MIT. Siehe LICENSE.