Claude Code Codegraph Harness

Un gateway de codegraph local sin conexión, adaptadores de doble cliente, un ejecutor de evaluaciones y un sistema de empaquetado multiplataforma para Claude Code y Codex.

Estado: v0.2.0-rc.1, candidato de release public-fixture. El runtime funciona, pero las condiciones de codegraph con Codex medidas aumentaron los tokens de entrada en un 48–52%, y el uso forzado de codegraph con Claude aumentó la entrada efectiva en un 58–112%. El código fuente de la empresa sigue bloqueado hasta que se apruebe la evidencia de aislamiento empresarial en Windows/macOS. Este release no afirma reducir tokens.

Para una explicación orientada a usuarios de negocio y administradores en japonés, comienza con このハーネスの仕組み. Los mismos bytes se incluyen como HOW-IT-WORKS-JA.md en cada ZIP sin conexión generado.

Qué está implementado

• un gateway stdio de Go, propiedad de la empresa, que expone cinco herramientas acotadas y de solo análisis;

• soporte nativo del binario Codebase-Memory v0.10.8 detrás de ese gateway;

• construcciones de índices administrativas explícitas, generaciones inmutables, punteros atómicos al índice actual, estado ligado al repositorio y comprobaciones de frescura por consulta;

• Plugin/Rule para Claude Code y una Skill de usuario para Codex con una única directiva de enrutamiento canónica;

• instaladores para macOS y Windows que generan paquetes de tiempo de ejecución para arm64 y x86_64;

• paquetes ZIP internos deterministas y con suma de verificación, tanto solo de adaptador como para las cuatro plataformas;

• un ejecutor de evaluación de herramientas de código abierto que registra uso de tokens, latencia, resultados acotados de oráculo y nombres de herramientas, sin retener prompts ni respuestas del modelo.

El gateway expone únicamente:

• codegraph_status

• codegraph_search

• codegraph_neighbors

• codegraph_impact

• codegraph_architecture

La indexación, la mutación, las consultas arbitrarias al grafo, la recuperación del cuerpo del código fuente, las URLs y las herramientas MCP ascendentes no pueden ser invocadas por el modelo.

Related MCP server: codebase-rag

Arquitectura del runtime

Claude Code Plugin + Rule ----\
                               > registered local stdio gateway
Codex user Skill -------------/              |
                                              v
                                  pinned Codebase-Memory native binary
                                              |
                                              v
                              private repository-bound graph generations

administrator command -> gateway index build -> validate -> atomic activation

Claude Code y Codex comparten exactamente el mismo gateway, backend, índice, modelo de frescura y contrato de cinco herramientas. El Plugin y la Skill contienen solo guías de enrutamiento; nunca inician un backend upstream directamente.

Decisión de adopción actual

Graphify v0.9.48 es rechazado para el código de la empresa porque el MCP upstream bloqueado incluye herramientas de PR conectadas a GitHub y rutas externas de LLM. Codebase-Memory v0.10.8 es el backend consumidor nativo seleccionado porque su ruta nativa de producción no muestra dependencia externa de red observable, puede desactivar UI/watch/auto-index y se distribuye para los cuatro conjuntos de plataforma operativa/CPU compatibles. Sus invocadores de instalación npm, PyPI, Go y upstream están restringidos porque realizan descargas desde GitHub.

El gateway y el backend se probaron en un fixture público desechable dentro de una sandbox de macOS que denegaba el acceso a la red externa. Se obtuvo 759 nodos y 1.760 aristas con cero archivos omitidos, parciales o no indexados; búsqueda, análisis de impacto, arquitectura y validación de esquema terminaron correctamente, junto con el rechazo de configuraciones obsoletas y raíz.

La comparación repetida con Codex no mostró ahorros:

Claude Code también usó el gateway correctamente, pero no mostró ahorros:

El tratamiento de Claude invocó exactamente una herramienta servida por el gateway en cada consulta y luego verificó el resultado. Una sonda de convergencia forzada no eligió ninguna herramienta MCP, por lo que la selección automática de herramientas no está establecida. OAuth/keychain requería el modo común sin ventana; los controles y limitaciones exactos se registran en evaluación de Claude Code.

Por lo tanto, el codegraph se considera una capacidad de navegación estructural opt-in, no una optimización de costos siempre activa. Véase también la evaluación de Codex.

Frontera de no salida de código

Los instaladores del endpoint no contienen una llamada a un descendente o a un administrador de paquetes. El gateway produce la ejecución de binarios locales (backend) y de Git con hash fijado, con un directorio personal sintético privado y un entorno mínimo. El estado se encuentra fuera del repositorio de código. Los resultados de las herramientas contienen rutas relativas acotadas y evidencias de grafo, no el cuerpo del fuente fuente.

Estos controles no son una sandbox empresarial. El uso de stdio no impide que un proceso secundario abra DNS o HTTTTP. La instalación de tiempo de ejecución requiere un flag removido explícito --allowed-root/-AllowedRoot, y cada gateway de lanzamiento de candidato se compila con una referencia de contenido exacto del fixture público limpio de código. Una etiqueta, un checkout diferente, un archivo de desconsideración u otro repositorio no pueden habilitarlo. Este release sigue siendo exclusivamente para fixture público. Antes del uso con código de empresa, el endpoint/AppSec debe imponer y documentar la denegación de red a nivel proceso, el ciclo de proceso y el aislamiento de registro de archivos/credenciales para los binarios reales en cada arquitectura Windows y macOS soportada.

El repositorio público y el release nunca contienen código original de una empresa, prompts, resultados, rutas internas, políticas administradas, claves de firma, gráficos generados ni binarios nativos de terceros.

Public ZIP solo de adaptadores

El release público es deliberadamente pequeño y contiene únicamente los adaptadores, instaladores, contratos y documentación:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
codegraph-harness bundle \
  --version 0.2.0-rc.1 \
  --profile packaging/profiles/public.json \
  --output dist/codegraph-harness-0.2.0-rc.1.zip

Instalar este ZIP no habilita código de runtime.

ZIP interno de tiempo de ejecución

El proceso de creación de artefactos construye el gateway para cuatro destinos y añade los cuatro ejecutables exactos de Codebase-Memory desde su evaluación de repositorio. Luego se realiza el reemplazo de tokens de metadatos en runtime-matrix.json.in y se ejecuta:

codegraph-harness bundle \
  --version COMPANY_RELEASE_VERSION \
  --profile /approved/input/runtime-matrix.json \
  --vendor-dir /approved/input/native \
  --output /approved/output/codegraph-harness-COMPANY_RELEASE_VERSION.zip

El proceso de construcción lee solo los archivos enumerados explícitamente, verifica cada SHA-256, rechaza symlinks/traversal/colisiones y genera un ZIP determinista, además del manifiesto de runtime, manifiesto del paquete y SHA256SUMS. El ZIP de prueba actual para las cuatro plataforma mide 172 MB comprimido y 1.1 GB descomprimido; un endpoint instala únicamente su par de gateway/backend correspondiente.

Los endpoints corporativos no necesitan GitHub, npm, PyPI, Go registry ou servidor vendor. Solo necesitan el ejecutable de Git administrado por la organización, registrado en el momento de ejecutar la instalación.

Comandos del endpoint

Para un ZIP público solo de adaptadores:

./install.sh --dry-run
./install.sh

powershell.exe -NoProfile -File .\install.ps1 -DryRun
powershell.exe -NoProfile -File .\install.ps1

Para un ZIP de runtime, un administrador debe restringirlo al checkout exacto del fixture público compilado en ese binario concreto del gateway:

./install.sh --dry-run --allowed-root /absolute/approved/public-fixtures
./install.sh --allowed-root /absolute/approved/public-fixtures

powershell.exe -NoProfile -File .\install.ps1 -DryRun -AllowedRoot C:\Approved\PublicFixtures
powershell.exe -NoProfile -File .\install.ps1 -AllowedRoot C:\Approved\PublicFixtures

Durante el ensamblado, el constructor de paquetes verifica que la lista-blanca de fixtures incrustada en cada gateway coincida con el perfil de runtime de esa versión. En el endpoint, el instalador valida cada entrada extraída contra SHA256SUMS, selecciona la localidad de sistema operativo/CPU, instala la Rule de Claude y la Skill de Codex sin sobrescribir archivos de los que no es dueño, opcional instala el Plugin del marketplace local de Claude, registra el mismo gateway en ambos clientes instalados y escribe un ticket de fallo. Los fallos parciales revierten la operación.

La desinstalación conserva el estado de codegraph por defecto para evitar pérdida de datos no deseada. Usa --purge-graph-state o -PurgeGraphState en el comando de desinstalación original cuando requiere política de eliminación.

Antes de descomprimir, verifica el ZIP completo contra una firma o un SHA-256 obtenido por un canal separado del ZIP. El SHA256SUMS presente en el archivo HTML detecta una sustitución parcial, pero no es una raíz de confianza para un archivo reemplazado por completo.

Ejecutor de evaluación

El ejecutor acepta únicamente fixtures públicos y rechaza company-source antes de leer el archivo de condiciones JSON o abrir un proceso. Soporta condiciones de línea base/gateway para Claude y Codex, además de los identificadores legados de comparación de candidatos. La print salida completa se calcula un hash, pero no se guarda salvo petición explícita.

Véase Protocolo de evaluación. Un archivo de condiciones es configuración ejecutable y debe tratarse como código de confianza.

Verificación

La verificación local incluye más de 85 pruebas de Python, Black, simple, mypy estricto, checks de Go (unittest/vet/race), compiled activemente para destinos de Go, validación estricta del Plugin de Claude, tests de sumas/archivos y una prueba real de instalar→indexar→MCP→desinstalar en macOS arm64. Los ejecutables de Windows se compilan de forma chanada cruzada y el flujo de PowerShell se ejecuta en GitHub Actions; la instalación nativa de Codebase-Memory en Windows y pruebas de EDR para empresa siguen siendo bloqueos de liberación para el código de la empresa.

Más información

• Arquitectura

• Integración con el harness

• Distribución sin conexión

• Modelo de amenazas

• ADR de selección de backend

• ADR de empaquetado vs ubicación

• ADR de runtime con doble cliente

• Auditoría de flujo de candidatos

• Evidencia de runtime

Licencia

Repository (código repositario) toca Apache-2.0. Codebase-Memory remains and merges receives additional risk- reviewing release; the software remains subject to MIT License and tha distribution only via the internal reviewed bundle and its agreements.