KlapContext

Understand an unfamiliar codebase before changing it.

KlapContext convierte evidencia de código en un modelo del sistema: puntos de entrada, flujos, automatizaciones, integraciones y sus incertidumbres. Graphify puede funcionar como proveedor estándar de análisis técnico; Serena puede sumar navegación semántica on demand por MCP; KlapContext conserva analizadores locales y transforma toda evidencia mediante contratos desacoplados para personas y agentes de IA.

Agent Intelligence

KlapContext planifica el mínimo contexto relevante antes de que un agente empiece a cambiar código. Según la intención —entender, modificar, depurar, probar, refactorizar o medir impacto— selecciona capacidades y proveedores necesarios, sin acoplarse a una herramienta externa ni cargar archivos enteros por defecto. La compilación de Task Context llegará en los siguientes sprints.

KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un portal estático para personas y un briefing compacto para agentes de IA. Puede usar Graphify como motor local de grafo, pero klap init sigue funcionando con proveedores nativos si no está.

Repositorio → KlapContext → Contexto de ingeniería
                              ├── Portal humano
                              └── Contexto para agentes

Instalación

pip install klapcontext

La instalación base no incorpora proveedores en el intérprete de KlapContext. El primer klap init los prepara en entornos aislados bajo .klap/provider-runtime/.

Primer uso

cd mi-proyecto
klap init
klap open

klap init ejecuta los proveedores disponibles, escribe artefactos locales bajo .klap/ y prepara un AGENTS.md privado para que los agentes descubran el contexto progresivamente. Ambos se agregan a .git/info/exclude; KlapContext nunca modifica tu .gitignore.

klap init prepara Graphify y Serena con versiones fijadas si no encuentra una instalación compatible. Si una preparación falla, los analizadores nativos siguen generando contexto y el resumen registra el motivo. Graphify ejecuta una extracción real y usa .klap/graphify-out/graph.json en context.json, el portal y la configuración MCP. Si no está instalado o falla, los analizadores nativos siguen generando un contexto útil y el reporte queda PARTIAL, con proveedores detectados, ejecutados y omitidos (incluido el motivo). context.json.analysis conserva la cobertura, trazas y contribuciones combinadas con procedencia. Se puede deshabilitar Graphify explícitamente con .klap/providers.json y {"providers":{"graphify":{"enabled":false}}}.

Serena se integra de forma independiente y intercambiable. Si falta una instalación compatible, Serena 1.7.0 se prepara en el runtime local; KlapContext descubre sus tools reales por MCP y ofrece símbolos, definiciones, referencias, implementaciones e impacto por consulta. Durante klap init sólo ejecuta una comprobación acotada de overview sobre un archivo elegible para verificar MCP; no realiza búsquedas semánticas amplias, y nunca llama sus tools de escritura, shell, onboarding o memorias. Ver instalación, configuración, seguridad, compatibilidad y límites.

Para compartir las instrucciones de onboarding con el equipo:

klap init --shared

El modo compartido genera un AGENTS.md versionable, sin rutas personales ni secretos. Si el archivo ya existe, KlapContext preserva su contenido y sólo administra el bloque entre KLAPCONTEXT:START y KLAPCONTEXT:END. Un archivo versionado nunca se modifica silenciosamente en modo privado.

El portal incluye un árbol navegable de archivos y símbolos extraídos del grafo, recorridos de llamadas y cambios recientes de Git. El contexto del agente y klap context usan las mismas rutas y símbolos. El indicador de cobertura cuenta archivos de código con al menos un nodo en Graphify: no mide exhaustividad de funciones ni garantiza que se hayan resuelto rutas dinámicas. Los recorridos son caminos del grafo, no afirmaciones de que una ruta HTTP los ejecuta; sus ramas pueden requerir inspección del código original.

Antes de invocar Graphify, KlapContext calcula un Index Scope central desde Git, manifests y reglas por stack. Excluye dependencias, caches, builds, minificados y recursos binarios, pero permite excepciones locales en .klap/scope.json. Revisalo con:

klap scope
klap scope --json

Comandos

Salidas

.klap/
├── context.json          # modelo técnico, de sistema y humano
├── agent-context.md      # briefing para agentes de IA
├── index.html            # portal humano, sin servidor
├── state.json            # metadatos de freshness
├── archify-state.json    # estado separado del renderer
├── flows/                # IR reproducible + HTML interactivo por flujo
├── renderer-runtime/     # Archify fijado y aislado por proyecto
├── mcp/                  # configuración local Graphify, cuando está disponible
└── graphify-out/         # grafo/informe opcionales de Graphify

Diagramas de flujos con Archify

klap init y klap update preparan Archify 3.1.0 automáticamente y proyectan los flujos reconstruidos por Klap a diagramas workflow. Archify sólo renderiza: no analiza el repositorio ni participa del registro de proveedores. El paquete oficial se descarga desde el release fijado, se verifica con SHA-256 y se guarda en .klap/renderer-runtime/archify; requiere Node.js 18 o superior.

La sección Flujos del portal permite seleccionar el diagrama, revisar evidencia y limitaciones, y abrir cada HTML autocontenido con file://. Si Node, la descarga, la validación o el render fallan, el contexto y el resto del portal se generan igualmente y archify-state.json conserva el motivo. Para deshabilitarlo en el proyecto creá .klap/archify.json con {"enabled": false}. El mismo archivo acepta max_flows, max_nodes, max_depth y timeout_seconds.

Los recorridos son relaciones reconstruidas por análisis estático; no son trazas observadas en producción. El IR se conserva junto al HTML para depurar y reproducir resultados. Archify se distribuye bajo licencia MIT; su runtime incluye LICENSE y THIRD_PARTY_NOTICES.md originales.

klap agent genera ejemplos locales para Codex, Claude Code, Cursor y clientes MCP genéricos. No instala agentes ni modifica configuraciones globales. Usá klap doctor --agent --probe-mcp realiza un handshake MCP real, descubre tools y ejecuta una consulta mínima graph_stats; falla si alguna etapa no se puede comprobar.

El servidor MCP propio de KlapContext expone además búsquedas de símbolos, definiciones, referencias, implementaciones, dependencias, impacto y flujos/endpoints. Así, un cliente sólo necesita conectarse a KlapContext; el adapter mantiene una sesión Serena reutilizable cuando está disponible. El portal HTML sigue siendo estático y muestra únicamente datos precompilados: no simula consultas semánticas dinámicas.

Las afirmaciones incluyen evidencia y confianza. Las consultas de proveedores distinguen OK, NO_RESULTS, UNSUPPORTED, PROVIDER_ERROR y UNKNOWN; si KlapContext no puede determinar algo, lo expone en lugar de inventarlo. Ver arquitectura y guía de adapters.

Desarrollo

python -m pip install -e ".[dev]"
python -m pytest

Publicación

El workflow de GitHub Actions publica tags v* mediante PyPI Trusted Publishing. Antes del primer tag, configurá el publisher de PyPI para este repositorio y workflow. No se necesitan tokens de PyPI en el repositorio.

El repositorio ya incluye .github/workflows/publish-pypi.yml: al publicar un tag vX.Y.Z, GitHub construye el paquete y lo publica con ese publisher.

Licencia

Apache-2.0. Ver LICENSE.