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 opcional 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
# opcional, para sumar el grafo Graphify
pip install "klapcontext[graphify]"

La instalación base no requiere Graphify. Como alternativa para una CLI aislada: pipx install klapcontext o pipx install "klapcontext[graphify]".

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.

Graphify se descubre automáticamente por su ejecutable o módulo Python: no hace falta habilitarlo. Si está disponible, init 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. KlapContext no instala proveedores durante init. Se puede deshabilitar Graphify explícitamente con .klap/providers.json y {"providers":{"graphify":{"enabled":false}}}.

Serena se integra de forma independiente y opcional. Si serena está instalado o configurado, KlapContext descubre sus tools reales por MCP y ofrece símbolos, definiciones, referencias, implementaciones e impacto por consulta. No ejecuta esas búsquedas durante klap init, no instala Serena 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
├── mcp/                  # configuración local Graphify, cuando está disponible
└── graphify-out/         # grafo/informe opcionales de Graphify

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.