Open Kioku

---

Primera victoria: 2 comandos

npm install -g open-kioku
ok setup agent cursor --repo . --apply

Usa claude en lugar de cursor para Claude Code. Un comando indexa el repositorio, escribe la configuración MCP y la guía del agente a nivel de repositorio, y verifica que el servidor local responda (ejecuta sin --apply para previsualizar; no se escribe nada). Luego pide evidencia sobre una tarea real:

ok context "reap the doctor's MCP probe child process" --format markdown

Esta es la salida real en este repositorio, recortada: … marca las líneas cortadas, y cada unidad primaria está colapsada a su rango de líneas y primera línea. El commit que hizo este cambio tocó exactamente un archivo, y es el primer resultado:

# Task: reap the doctor's MCP probe child process

## Confidence
- Overall: `Medium` (`0.74`)
- Caveats:
  - exact symbol/reference evidence is absent
  - runtime corroboration is absent
- Components:
  …
  - `exact_references` score `0.25`, weight `0.20`, contribution `0.05`
  …
  - `task_relevance` score `1.00`, weight `0.20`, contribution `0.20`
  …
## Retrieval
…
- Attempted: `lexical, document, exact_semantic, graph, validation, git_history, runtime`
- Succeeded: `lexical, document, exact_semantic, graph, validation, git_history`
…
- Exact-authority selections: `0`; ambiguity/unresolved signals: `0`
- Retrieval confidence: `Medium` (qualitative ContextPack confidence, not a calibrated probability)
- Caveats:
  - no runtime traces, logs, or incidents are ingested for this repository
  …
## Primary Context
### crates/open-kioku-cli/src/reports/status_setup_doctor.rs
Lines 1-107  `fn file_path_for_symbol(store: &dyn MetadataStore, symbol: &Symbol) -> anyhow::Result<PathBuf> {`
### crates/open-kioku-core/src/process.rs
Lines 66-180  `fn proc_status_peak_rss_bytes() -> Option<u64> {`
…

La etiqueta es Medium, no más alta, por una razón que el paquete declara: la tarea no nombra un identificador que el índice resuelva exactamente y este repositorio no tiene índice SCIP, por lo que exact_reference_count es 0 (exact_references puntúa 0.25; Exact-authority selections es 0), lo que limita la puntuación a 0.74 y la etiqueta a Medio. Los artefactos de ejecución también están ausentes; esa es la segunda advertencia, y baja la puntuación, no la banda. Exact está reservado para paquetes con al menos una selección de autoridad exacta; una coincidencia léxica, por buena que sea, no lo merece. La tarea está formulada como el asunto del commit de corrección, por lo que el historial de git corrobora el primer archivo junto con la coincidencia léxica. Cada paquete dice qué flujos de evidencia se ejecutaron, cuáles tuvieron éxito y qué falta. La evidencia faltante baja la confianza declarada; nunca se encubre.

Qué obtienes

ok plan "change token expiration" --format json > plan.json   # context, impact, tests, edit boundary, caveats
# ...edit with your normal agent or editor...
ok verify --plan plan.json --git                               # the real diff against the declared boundary

ok plan (o la herramienta MCP plan_change) devuelve contexto primario con procedencia, candidatos de impacto divididos en estructuralmente probados y heurísticos, objetivos de validación clasificados por evidencia, un límite de edición (rutas permitidas, con precaución, prohibidas) y advertencias explícitas. ok verify lee los archivos realmente modificados e informa, por ejemplo, [out_of_boundary] go/shipping/carrier.go: path is outside the saved plan boundary. Un código de salida verde de un ejecutor de pruebas no es prueba de que los archivos correctos cambiaron; esto lo es.

Por debajo: las definiciones exactas, referencias y rutas de dependencia del código fuente (y SCIP opcional) son autoritativas. Las señales léxicas, semánticas, de historial, de pruebas y de ejecución pueden reordenar la recuperación; no pueden sobrescribir la verdad del repositorio.

Qué cambió en 4.0.0

Publicado el 2026-09-11. Ejecuta ok index después de actualizar: el formato de almacenamiento del índice cambió, y un índice anterior a 4.0 retiene la evidencia de relaciones y lo dice (ok impact, ok plan, ok context, y las herramientas MCP sobre ellos se niegan con run ok index en lugar de responder desde un grafo vacío). La lista completa, con el commit y el método detrás de cada número, está en CHANGELOG.md.

• 16 herramientas MCP, antes 58. Cada una responde una pregunta que ninguna otra herramienta responde; un nombre retirado responde con dónde fue su capacidad. Seis descripciones que decían lo que sugerían sus nombres ahora dicen lo que hace la implementación, y structural_search desapareció porque no existía coincidencia estructural. docs/mcp-tools.md lleva la tabla de migración.
• regex_search hace regex. Antes despachaba a búsqueda léxica clasificada; ahora evalúa el patrón línea por línea sobre el texto indexado e informa archivos escaneados y paradas tempranas. ok search <pattern> --regex es el equivalente en CLI.
• El índice informa lo que no indexó. Cobertura por lenguaje con cada omisión atribuida a una razón de omisión, en ok index, ok doctor, ok status y repo_status. Una regla de ingesta había descartado silenciosamente 25 archivos fuente Java de un repositorio.
• Más de la región correcta. Las unidades seleccionadas cubrieron 3–22% de las líneas que un commit real cambió incluso cuando el archivo era correcto; los tres archivos principales ahora se amplían al símbolo contenedor y fragmentos adyacentes. Proporción de líneas cambiadas mostradas dentro de 8k tokens, 626 casos locales emparejados, ningún caso peor, aproximadamente tres veces los tokens: Java 0.216 → 0.248, Go 0.207 → 0.299, TypeScript 0.155 → 0.335, Python 0.130 → 0.203 (docs/ranking.md, benchmarks/commit-derived/region-widening-ab.json).
• Las palabras de la tarea llegan a los identificadores del repositorio. ChannelsUtils Tests llega a ChannelUtilsTests sin modelo, red ni re-indexación. Neutral en benchmarks de asuntos de commit por construcción; en 259 consultas perturbadas R@5 0.656 → 0.699, MRR +0.036 (IC 95% +0.015 a +0.062), un límite superior por diseño (docs/ranking.md).
• Aristas de archivos derivados. Un archivo generado y su origen, o una prueba y el módulo del que lleva el nombre, se unen al análisis de impacto como posibilidades etiquetadas: un origen declarado lleva su prueba, una convención de nombres está marcada como heurística (docs/graph-model.md).

Qué esperar

La recuperación se mide en la ruta de producción (ok context, el mismo constructor detrás de ok plan y la herramienta MCP build_context_pack) en cuatro repositorios reales, cada uno indexado en un commit base fijo. Cada caso es un commit posterior: la consulta es su línea de asunto, la respuesta son los archivos fuente que cambió. Los casos se dividen cronológicamente; ambas divisiones se controlan cada noche, y la tabla muestra la retención.

Corpus	Casos de retención	R@5	R@20	MRR
Java, ~10k archivos	113	0.566	0.708	0.516
Aplicación Go, ~800 archivos	84	0.690	0.821	0.539
TypeScript, ~900 archivos	167	0.826	0.880	0.683
Biblioteca Python, ~4k archivos	199	0.663	0.754	0.543

• R@5 — la proporción de tareas en las que al menos un archivo que el commit cambió está en los primeros cinco resultados.
• R@20 — lo mismo dentro de los primeros veinte resultados, aproximadamente todo el paquete de contexto.
• MRR — el promedio de 1 / rango del primer archivo correcto; 1.0 significa que siempre fue primero, 0.5 es lo que obtienes si el primer archivo correcto siempre fuera segundo, o primero la mitad del tiempo y nunca encontrado el resto.

Léelo claramente. En un repositorio Java de unos diez mil archivos, el archivo correcto está en los cinco primeros aproximadamente la mitad de las veces y en el paquete unas siete de cada diez; en un repositorio TypeScript de unos novecientos archivos, en el paquete casi nueve de cada diez y en los cinco primeros unas cuatro de cada cinco. Ese es el piso desde el que el agente comienza antes de haber mirado nada, y es el número a observar. Las búsquedas exactas (definiciones, referencias, rutas de dependencia) y el bucle plan → edición → verificación se sitúan encima.

Estas líneas base se congelaron el 2026-09-25 a partir de una ejecución de matriz de un runner Linux alojado del commit bd5d06ab, y una segunda ejecución del mismo commit produjo puntuaciones idénticas (aparte de los tiempos). .github/workflows/commit-derived-bench.yml las re-deriva cada noche; el trabajo falla cuando una métrica vigilada cae más de 0.03 por debajo de su línea base congelada, o cuando una familia de tareas enrutada de 34 o más casos cuya membresía de casos no cambia cae más de max(0.03, 2/n) por debajo de la suya. Las consultas son asuntos de commit, no texto de issue, por lo que los números no son comparables con benchmarks publicados que usan texto de issue. Descripciones del corpus, ambas divisiones, los scripts y la política de regresión: docs/retrieval-benchmark.md; líneas base congeladas: benchmarks/commit-derived/.

Dos hechos medidos más:

• Cuando la tarea no tiene respuesta. En el fixture congelado de 30 casos, ninguna de las cinco tareas sin gold se presenta como respuesta: la tasa de falsos positivos sin gold es 0.0 (el techo del IC es 0.25), y la estrategia de paquete de contexto enrutado asesorada en la misma ejecución (cc4:routed_contextpack) no devuelve ninguna por encima de Low. Un paquete de baja confianza aún lista candidatos; le dice al llamador que no confíe en ellos en lugar de devolver nada. benchmarks/retrieval-baseline.json
• Embeddings neurales locales opcionales. El perfil neural local predeterminado (un modelo int8 de 149M de parámetros, fijado por digest) mejoró cada métrica en los corpus Go y TypeScript contra un control del mismo día, en aproximadamente +0.025 MRR, en runners alojados de 4 vCPU / 16 GB. Real pero modesto; las correcciones de clasificación léxica que llegaron el mismo día valieron aproximadamente cuatro veces más. docs/embedding-providers.md

Medido a escala

Las afirmaciones de rendimiento son observaciones vinculadas a una compilación identificable, publicadas con método y advertencias. El registro de escala de extremo a extremo más reciente valida el linaje de lanzamiento 3.1.0 en el commit fuente 3959fdfb6ca27d0c279b635fca7fc1b7935d4889 en un repositorio Java grande, en el mismo host y protocolo que el registro público anterior. 4.0.0 cambió el formato de almacenamiento del índice y no se ha vuelto a ejecutar en este corpus; la tabla describe 3.1.0. Los cambios medidos propios de 4.0.0 se enumeran con sus commits y métodos en CHANGELOG.md.

Medición (linaje v3.1.0, extremo a extremo)	Resultado
Archivos fuente rastreados / archivos Java	16,537 / 12,580
Archivos / símbolos / fragmentos indexados	13,607 / 247,499 / 248,107
Nodos / aristas del grafo	402,844 / 1,522,135
Índice estructural en frío	19m 28s
Búsqueda exacta de clase, proceso nuevo	0.02–0.05s
Referencias exactas / búsqueda léxica, proceso nuevo	0.74s / 0.24s
Construcción semántica plana exacta	495,606 vectores en 58.8s; 0 fallos
Construcción HNSW persistente	495,606 vectores en 10m 19s; 0 fallos

Contra main en c96f61a en el corpus y host idénticos (metodología): inicio por comando ~14s → sub-segundo, búsqueda exacta de clase 13.9s (devolviendo un symbol not found incorrecto) → 0.02s con la clase correcta, índice estructural en frío 40m 40s → 19m 28s. El índice repetido reprodujo totales idénticos y cuatro lectores de grafo paralelos completaron con cero fallos de bloqueo. La identidad del repositorio se omite, por lo que esto es un registro de escala más que un corpus reproducible: evidencia legible por máquina · metodología · registro anterior: evidencia v3.0.4.

Más artefactos: escala semántica local, 51,349 vectores, HNSW persistente auto-seleccionado, construcción nueva en 21.70s, 0 vectores obsoletos / 0 fallidos (demo/proof/ann-50k-dogfood.json); plan → edición → validación → verificación a través del runner con política, 2 aprobados, 0 violaciones de límite, veredicto final warn porque faltaba evidencia más fuerte (demo/proof/verification-dogfood.json); una auditoría de repositorio público, 4,600+ archivos, 46,000+ símbolos, 8,900+ pruebas indexadas en 33.1s (docs/large-repo-proof.md).

Estos son tiempos de estación de trabajo local, no garantías universales.

Instalación

Canal	Cómo
npm (recomendado)	npm install -g open-kioku — el wrapper extrae @open-kioku/{darwin-arm64,linux-x64,linux-arm64,win32-x64} (fuentes bajo packages/)
crates.io	cargo install open-kioku-cli o cargo binstall open-kioku-cli
Lanzamientos de GitHub	Binarios con SHA256SUMS, SBOM.cargo-metadata.json, PROVENANCE.json y atestaciones de procedencia de compilación de GitHub (docs/release-trust.md)
Plugin de Claude Code	claude_plugin.json y .claude-plugin/
Plugins de Cursor / Codex	.cursor-plugin/ · .codex-plugin/
Directorios MCP	Glama (glama.json) · Smithery (smithery.yaml)
Desde el código fuente	git clone https://github.com/shivyadavus/open-kioku.git && cargo install --path open-kioku/crates/open-kioku-cli

Conecta un agente

ok setup agent claude --repo . --apply    # Claude Code: index + .mcp.json + managed skill, then a live MCP check
ok setup agent cursor --repo . --apply    # Cursor: index + .cursor/mcp.json + managed rule
ok mcp install codex  --repo .            # Codex: prints the TOML server entry
ok mcp install gemini --repo .            # Gemini CLI: prints the JSON server entry

ok setup agent --apply está conectado para claude y cursor; cualquier otro cliente listado por ok mcp install --help recibe un fragmento de configuración de solo lectura de ok mcp install <client>. El servidor MCP es local, de solo lectura y utiliza stdio. Anuncia 16 herramientas — una por pregunta que nada más responde — cada una con guía de uso, esquemas de entrada/salida, anotaciones de seguridad y categorías de enrutamiento, y una prueba de regresión de metadatos rechaza herramientas nuevas que omitan cualquiera de estos elementos. Las herramientas de memoria y errores en tiempo de ejecución solo aparecen una vez que esas funciones están configuradas; las capacidades de arquitectura, historial y propiedad se incluyen en la CLI (ok architecture …, ok history …, ok contract show).

Guías paso a paso: Claude Code · Cursor · Codex · Gemini CLI · CI: open-kioku-action (docs/github-action.md)

Cada cliente ok mcp install, con su forma de configuración generada y cómo confirmar la conexión: docs/guides/cross-harness-setup.md

Por Qué Local

• Sin índice alojado ni carga de código fuente: todo vive bajo el directorio .ok/ del repositorio, y ok prove comparte conteos y puntuaciones sin fragmentos de código fuente.
• MCP es de solo lectura por defecto; las ediciones del código fuente permanecen en tu editor habitual o en el entorno del agente.
• La ejecución de comandos y las descargas de modelos están restringidas por políticas, las rutas tipo secreto están bloqueadas, y la denegación de red falla de forma cerrada en lugar de degradarse silenciosamente.

docs/security-model.md · SECURITY.md · docs/release-trust.md

Cómo Se Mide

• Corpus derivados de commits en repositorios reales, re-ejecutados cada noche: docs/retrieval-benchmark.md (derivar con scripts/commit-derived-cases.py, puntuar con scripts/score-context-cases.py, comparar con scripts/compare-commit-derived-report.py).
• El conjunto fijo congelado de 30 casos con una división reservada y umbrales de CI: ok retrieval-bench . --cases-file benchmarks/retrieval-cases.json --min-cases 30.
• Suites de flujo de trabajo, relaciones y contratos: docs/workflow-benchmarks.md · docs/relationship-benchmark.md · docs/contract-benchmarks.md.
• Registros de escala y dogfood: docs/proof.md y demo/proof/.

Los cambios de umbral son cambios de producto y se revisan como tales; un umbral nunca se reduce para que la CI pase.

Más De Un Repositorio

La recuperación semántica es opcional y local (ok --repo . semantic index, luego ok search "authorization expiry" --hybrid); la adquisición de modelos requiere consentimiento explícito y se rechaza bajo denegación de red (docs/semantic-search.md, docs/vector-index.md). Indexa proyectos individualmente y vincúlalos en un espacio de trabajo (ok index --mode cross-project --workspace <dir>, ok architecture fleet). Exporta e importa índices conocidos y válidos para reutilización en equipo y CI (ok --repo . snapshot export --quality best, ok --repo . index --from-snapshot auto); la memoria personal se excluye de las instantáneas compartidas por defecto. Detecta arquitectura, verifica políticas y crea contratos de cambio acotados (ok --repo . architecture detect, ok --repo . contract create "update API boundary"). El historial de Git está activado por defecto con una ventana acotada; los rastros de ejecución y los informes de cobertura son entradas locales opcionales que nunca superan la verdad exacta del código fuente.

Soporte De Idiomas

El análisis con Tree-sitter y la extracción de símbolos cubren Rust, Python, TypeScript/TSX, JavaScript/JSX, Go y Java. YAML y JSON se analizan estructuralmente; la indexación de archivos/fragmentos también cubre TOML, SQL, Markdown, Terraform y otro texto del repositorio. La resolución consciente del idioma añade semántica de alcance, importación, receptor/tipo, contención y herencia donde se admite.

Definiciones y referencias exactas de Java desde un índice scip-java: docs/guides/java-scip.md

Comandos Útiles

ok --repo . search "token expiration handler"
ok --repo . symbol definition PolicyGate
ok --repo . symbol refs PolicyGate
ok --repo . impact --file src/auth.rs
ok --repo . tests --changed src/auth.rs
ok --repo . context "change token expiration" --format markdown
ok --repo . plan "change token expiration" --format markdown
ok --repo . verify --plan /tmp/plan.json --git
ok --repo . history similar --task "change token expiration" --path src/auth.rs
ok prove . --task "change token expiration"

Todos los 38 comandos de nivel superior

Comandos de nivel superior actuales (38): init, index, snapshot, watch, status, doctor, setup, demo, search, semantic, symbol, explain, impact, path, tests, context, retrieve-context, plan, preflight, verify-boundary, verify, contract, bench, workflow-bench, retrieval-bench, relationship-bench, contract-bench, eval, prove, adr, ui, architecture, history, patch, memory, mcp, scip y graph.

Referencia completa de herramientas MCP: docs/mcp-tools.md

Estructura Del Repositorio

Este es un espacio de trabajo Cargo de 43 crates con una dirección de dependencia descendente estricta: CLI / MCP → inteligencia del agente (context, impact, tests, plan, patch, actions) → núcleo de inteligencia de código (ingest, parse, tree-sitter, resolution, graph, architecture) → almacenamiento y búsqueda (storage-sqlite, search-tantivy). open-kioku-core contiene los contratos de evidencia, grafo e informes; las integraciones opcionales (scip, lsp, semantic, vector, qdrant, sentry) devuelven diagnósticos explícitos de deshabilitado/no compatible en lugar de degradarse silenciosamente.

Arquitectura: docs/architecture.md · Mapa de crates: docs/crate-map.md · Almacenamiento: docs/storage-model.md

Desarrollo

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
scripts/validate-docs.sh
ok retrieval-bench . --cases-file benchmarks/retrieval-cases.json --min-cases 30
ok workflow-bench . --cases-file benchmarks/workflow-cases.json --limit 10

Liderado por mantenedores y con código fuente disponible bajo Elastic-2.0; consulta CONTRIBUTING.md antes de abrir una solicitud de extracción.

---