Project Code Intelligence

Inteligencia de repositorios y evidencia de seguridad de cambios para agentes de codificación.

Project Code Intelligence (PCI) indexa repositorios Git y proporciona a los agentes de codificación evidencia estructurada para tareas de investigación, refactorización, mantenimiento y seguridad. Los agentes pueden buscar por concepto o identificador, inspeccionar relaciones candidatas, estimar el radio de impacto de un cambio, encontrar formas de implementación repetidas y consultar hallazgos de análisis estático antes de editar código.

PCI no es un revisor autónomo y su grafo no es un grafo de llamadas de nivel compilador. Acota el descubrimiento y aporta evidencia; el agente sigue verificando las conclusiones importantes en el código fuente.

Con Qué Ayuda

Investigación y orientación

• Buscar identificadores exactos, nombres de archivo, claves de configuración y cadenas conocidas.

• Buscar por comportamiento cuando los nombres relevantes son desconocidos.

• Inspeccionar lenguajes del repositorio, roles de archivos, instantáneas, cobertura del analizador y frescura del índice.

• Obtener registros acotados con rutas, rangos de líneas, metadatos y fragmentos de código fuente.

• Trabajar en varios repositorios mediante colecciones con nombre y filtros de repositorio.

Cambios más seguros

• Encontrar llamadores, llamados, referencias, pruebas y cableado a nivel de módulo candidatos.

• Comprobar la evidencia de radio de impacto antes de eliminar, renombrar o cambiar un símbolo.

• Exponer señales de puntos de entrada, código huérfano y cobertura de pruebas.

• Inyectar evidencia cercana en agentes de codificación compatibles cuando se añaden o eliminan definiciones.

Mantenimiento y redundancia

• Encontrar grupos de funciones que repiten un motivo de forma de llamada.

• Clasificar candidatos a redundancia por similitud, coste estimado de abstracción y valor neto probable.

• Ejecutar una auditoría del repositorio para índices obsoletos, nombres duplicados, candidatos a redundancia y hallazgos estáticos.

Seguridad y análisis estático

• Ingerir informes SARIF junto con los registros de código fuente.

• Buscar hallazgos normalizados por herramienta, regla, nivel, estado de línea base o ruta.

• Obtener diagnósticos, flujos de código y metadatos de ejecución sin que un agente tenga que analizar artefactos SARIF sin procesar.

Related MCP server: Graft

Cómo Funciona

pci index analiza los archivos del repositorio en registros acotados, extrae metadatos y relaciones candidatas, y almacena instantáneas en Postgres/pgvector. Los embeddings semánticos son opcionales: la búsqueda léxica y la mayor parte de la evidencia estructural siguen disponibles con --no-embed.

pci mcp expone el índice a través de un servidor MCP local por stdio. Los agentes de codificación usan sus herramientas orientadas a filtros para descubrir código probablemente relevante y luego leen y verifican el código fuente real antes de actuar.

La arquitectura local predeterminada es:

• Postgres/pgvector: Docker o Podman Compose.

• Servicios de embeddings en Linux: unidades Podman Quadlet gestionadas por systemd de usuario.

• Embeddings en Apple Silicon: un servicio MLX nativo.

• Integración con agentes: un servidor MCP por stdio, con ganchos opcionales de evidencia de edición.

Se admiten endpoints remotos de Postgres y de embeddings compatibles con OpenAI cuando esa compensación es intencionada.

Inicio Rápido

Instala la CLI desde un clon del repositorio:

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

Inicia la base de datos incluida y el backend de embeddings local más adecuado disponible:

pci doctor --start
pci doctor

Indexa un repositorio Git:

cd /path/to/repo
pci index .

Instala la configuración de MCP para tu agente de codificación:

pci mcp install --target codex

Los destinos compatibles incluyen claude, codex, opencode, pi, vscode, copilot, cline y zed. Consulta docs/MCP_SETUP.md para la configuración específica de cada cliente, el ámbito de proyecto y el manejo de credenciales.

Para búsqueda léxica sin embeddings:

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

Herramientas Principales del Agente

Ejecuta pci audit para obtener un informe de evidencia de todo el árbol.

Evidencia, No Veredictos

PCI distingue deliberadamente los hechos indexados más sólidos de la evidencia aproximada y heurística.

• Las aristas de relaciones candidatas no son hechos de grafo de llamadas verificados por tipos.

• El radio de impacto no puede probar que un cambio sea seguro.

• Las puntuaciones de redundancia no pueden decidir si dos funciones deberían compartir una abstracción.

• Los hallazgos estáticos conservan las limitaciones de su analizador de origen.

• Un índice puede estar desactualizado después de cambios sin confirmar o recién confirmados.

• La recuperación semántica puede omitir código relevante o devolver vecinos plausibles.

Verifica los llamadores y hallazgos importantes en el código fuente real. Usa lecturas directas de archivos para rutas conocidas y preguntas pequeñas y acotadas; PCI es más útil cuando la ubicación, el nombre o el impacto aún no se conocen.

Instalación

CLI de Python

Instala para el usuario actual con uv:

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

Para una instalación de desarrollo editable:

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

Nix

En NixOS u otro host Linux con flakes habilitados:

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

Instala de forma persistente en el perfil de usuario:

nix profile install .#project-code-intelligence

El cierre de Nix contiene la CLI, el servidor MCP, las dependencias de Python y los recursos Compose y Quadlet incluidos. Los tiempos de ejecución pesados de embeddings en Linux permanecen en contenedores Podman en lugar de convertirse en dependencias Nix nativas del host.

Base de datos local

Inicia solo la base de datos Postgres/pgvector incluida:

pci doctor --start-db

El archivo Compose instalado se materializa en la caché del usuario. Para usar una copia personalizada en su lugar:

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

Servicio de embeddings local

La CLI incluye las plantillas de servicio; no hay un paquete de embeddings PCI separado. En Linux, instala Podman y asegúrate de que systemctl --user funcione; luego ejecuta:

pci doctor
pci doctor --start-embedding

PCI detecta el hardware disponible, materializa solo el backend seleccionado en ~/.config/containers/systemd/, recarga el systemd de usuario y lo inicia. Las unidades PCI obsoletas de otros backends de embeddings se detienen y eliminan. Las imágenes y los modelos predeterminados se descargan en el primer uso.

Elige un backend explícitamente cuando lo desees:

# 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

Los selectores disponibles son auto, fastembed, lemonade, rocm, cuda y apple. PCI rechaza un backend solicitado cuando su hardware o tiempo de ejecución requerido no está disponible. apple se ejecuta de forma nativa en lugar de mediante Quadlet.

Para iniciar la base de datos y un backend explícito juntos:

pci doctor --start --embedding-backend rocm

Los backends contenedorizados publican un endpoint compatible con OpenAI en http://127.0.0.1:18081/v1/embeddings de forma predeterminada. Ejecuta un solo backend local a la vez porque comparten este endpoint.

Detén los servicios de embeddings sin tocar la base de datos:

pci doctor --stop-embedding

Elimina los servicios locales generados, las cachés y el volumen de base de datos incluido:

pci doctor --clean

--clean es destructivo y solicita confirmación antes de eliminar datos.

Embeddings remotos

Inicia solo la base de datos y luego configura un proveedor compatible con OpenAI de confianza:

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

Los endpoints remotos reciben texto derivado del código fuente. Habilítalos solo cuando eso sea aceptable para los repositorios que se están indexando.

Indexación de Repositorios

Indexa un repositorio:

pci index /path/to/repo

Indexa varios repositorios como un espacio de trabajo:

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

PCI infiere los nombres de colección y repositorio a partir de las rutas. Los clientes MCP filtran por estos nombres lógicos en lugar de por rutas absolutas del sistema de archivos. La indexación es incremental: los archivos sin cambios se reutilizan cuando existen instantáneas compatibles.

Los informes SARIF encontrados en las rutas de repositorio indexadas se ingieren automáticamente. Restablece y reconstruye un repositorio con:

pci index --reset /path/to/repo

Usa pci status para inspeccionar las ejecuciones de indexación y pci index --help para las opciones de analizador, embeddings, colección y base de datos.

MCP y Ganchos de Agente

Crea credenciales de base de datos de solo lectura con ámbito de proyecto y muestra una configuración MCP:

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

Instala o elimina la configuración de MCP sin reindexar:

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

La configuración de cliente generada no contiene contraseña de base de datos. Las credenciales se almacenan en el directorio de configuración de PCI del usuario con modo 0600. Pi usa un puente MCP local al proyecto en .pi/extensions/. Cline requiere --config-path porque su archivo de configuración tiene ámbito de usuario.

Los ganchos opcionales pueden recordar a un agente que use el índice e inyectar evidencia cerca de las ediciones que añaden o eliminan definiciones:

pci hook install --target codex

El soporte de ganchos y los detalles de instalación varían según el cliente. Los ganchos son una ayuda, no un mecanismo de aplicación forzosa o de corrección. Consulta docs/MCP_SETUP.md y docs/SYSTEM_PROMPT.md.

Privacidad y Seguridad

La opción local predeterminada mantiene los registros y embeddings derivados del código fuente en la máquina. Eso no hace que todos los artefactos sean seguros de publicar.

No confirmes ni distribuyas volcados de base de datos, artefactos de restauración, salida SARIF, cachés de embeddings, archivos de modelo, índices vectoriales, datos generados a partir de repositorios privados ni archivos locales de credenciales MCP. Pueden contener fragmentos de código fuente, rutas, símbolos, hallazgos, metadatos y embeddings derivados del código fuente.

Las colecciones organizan repositorios, pero no son una frontera de seguridad. Usa bases de datos o usuarios de base de datos separados cuando los repositorios requieran un aislamiento más estricto. Las credenciales MCP con ámbito de proyecto restringen el acceso normal, pero no sustituyen la seguridad del host y de la base de datos.

Cuándo PCI Es Adecuado

PCI tiende a ser útil cuando:

• el repositorio o espacio de trabajo es grande o desconocido;

• los identificadores son desconocidos al comienzo de una tarea;

• los archivos generados hacen que las lecturas amplias sean costosas o ruidosas;

• una refactorización necesita evidencia de llamadores, pruebas y cableado;

• el trabajo de mantenimiento necesita descubrimiento de patrones repetidos;

• los hallazgos estáticos deben correlacionarse con el código fuente;

• varios repositorios deben buscarse a través de una única interfaz.

Puede aportar poco valor para un repositorio pequeño y conocido, un archivo y rango de líneas conocidos, o una pregunta respondida con una búsqueda rg acotada o una lectura de archivo. El objetivo no es reemplazar las herramientas estándar de desarrollo; es mejorar los pasos inciertos de descubrimiento y planificación de cambios en torno a ellas.

La reducción de tokens y costes puede ser un efecto secundario útil, pero PCI no lo promete. Mide si el índice mejora sesiones reales usando docs/EVALUATING_VALUE.md y el prompt de retrospectiva de sesión.

Desarrollo

El servidor MCP usa stdio; Docker Compose es para la base de datos local, no para alojar el proceso MCP. Ejecuta la compuerta de desarrollo completa con:

nix develop
make check

Para cambios de ingesta, base de datos o comportamiento de MCP, ejecuta también:

docker compose up -d pgvector
make integration-smoke

Consulta CONTRIBUTING.md y AGENTS.md para conocer las convenciones del proyecto y las salvaguardas de publicación.

Documentación

• docs/MCP_SETUP.md — clientes MCP, alcances, credenciales y modelo de seguridad

• docs/PUBLIC_API.md — superficies de compatibilidad de CLI, entorno, MCP y Python

• docs/EVALUATING_VALUE.md — evaluación de PCI en sesiones de codificación reales

• docs/SYSTEM_PROMPT.md — instrucciones del agente para usar PCI

• docs/SYSTEM_PROMPT_RATIONALE.md — justificación del diseño del prompt

• docs/SESSION_RETROSPECTIVE_PROMPT.md — prompt de evaluación de fin de sesión

• .env.example — referencia de configuración del entorno

• CONTRIBUTING.md — flujo de trabajo de desarrollo

Licencia

MIT. Ver LICENSE.