livewiki

Documentación anclada al código que sabe cuándo está desactualizada.

livewiki convierte un repositorio en un wiki Markdown donde cada referencia de código está anclada a un símbolo indexado real. Un LLM escribe la prosa; livewiki hace el trabajo determinista — planificar las páginas, ejecutar comprobaciones estructurales anti-alucinación sobre lo que escribió el modelo, rastrear qué símbolos anclados cambiaron y preservar tus ediciones.

El wiki se expone a cualquier agente de código mediante @livewiki/mcp — un servidor MCP (Model Context Protocol) con ocho herramientas para leer, buscar y escribir el wiki de forma segura.

livewiki view genera un sitio offline autocontenido a partir del wiki — barra lateral agrupada, búsqueda offline, diagramas y modo oscuro:

Ejemplo de wiki generada por livewiki para MoneyPrinterTurbo-Plus, un repositorio Python externo.

Por qué

La documentación técnica se queda obsoleta en el momento en que cambia el código. livewiki lo hace visible y económico de corregir, en lugar de silencioso:

• Comprobaciones estructurales anti-alucinación. Cada referencia de código debe apuntar a un símbolo indexado real. livewiki verify lee el wiki directamente del disco y falla ante símbolos inventados, anclas rotas y firmas que ya no coinciden — incluidas referencias que el LLM escribió hace segundos, sin ejecutar index primero y sin gastar un token. Estructural, no semántico; la sección siguiente deja claro el límite.

• Tus ediciones prevalecen. Las páginas que marques como owner: human nunca se reescriben, y los bloques lw:manual se conservan byte a byte.

• La deuda se rastrea, no se descubre. livewiki status clasifica lo que se ha desviado; una GitHub Action puede bloquear cada merge si hay cero deuda de documentación, sin gastar tokens.

• Funciona donde ya trabajas. Inicia y mantén el wiki a través del agente de código que uses, o ejecuta un proceso por lotes totalmente automatizado.

Qué comprueba verify — y qué no

La capa anti-alucinación es determinista y estructural. livewiki verify lee el wiki directamente del disco — así que una página que un LLM escribió hace segundos se comprueba sin ejecutar index primero — y falla ante:

• un símbolo citado que no existe en el código;

• un ancla rota porque el símbolo se movió, se renombró o se eliminó;

• una firma citada que ya no coincide con la indexada;

• un enlace interno que no resuelve;

• un artefacto referenciado que falta en el disco;

• frontmatter o estructura de página que viola el contrato de formato.

Eso elimina clases enteras de contenido fabricado — la función inventada, la API que nunca existió, la referencia que se pudrió en silencio — antes de que un lector la vea, con coste de cero tokens. Todo lo que falla se rechaza y se revierte en lugar de fusionarse.

No demuestra que una frase sea verdadera. Una explicación plausible pero errónea de un código que realmente existe pasa todas las comprobaciones anteriores, porque todas ellas tratan sobre estructura e identidad, no sobre significado. Interpreta "anti-alucinación" aquí como una capa que elimina mecánicamente una gran clase de fabricación y te avisa en el momento en que el código se mueve bajo la prosa — no como una garantía de exactitud fáctica. Revisar la explicación en sí sigue siendo tu tarea.

Related MCP server: 50 First Tapes MCP Server

Inicio rápido

Requiere Node.js 24 o superior.

1. Instalar

npm install -g @livewiki/cli

(npx @livewiki/cli también funciona, sin instalación global.)

2. Inicializar

Desde la raíz del repositorio que quieras documentar:

livewiki init

Indexa el código y crea el esqueleto del wiki en livewiki/, además de una caché derivada en .livewiki/ (añadida a .gitignore). Determinista — sin llamadas a LLM, sin tokens.

3. Inicializar el wiki una vez

Tienes dos rutas — elige una.

Ruta A — a través de tu agente de código (sin necesidad de clave API):

livewiki install

El instalador detecta tu agente, conecta el servidor MCP, la habilidad de documentar sobre la marcha y los ganchos de git. Luego pide al agente que inicialice el wiki; este toma las tareas de livewiki_next_task y envía páginas con livewiki_write_doc usando el modelo que ya tiene.

Ruta B — una API de LLM configurada (sin supervisión):

livewiki config

El asistente lista los proveedores, pide tu clave API (escrita sin eco) y la guarda. livewiki sin argumentos en un repositorio no configurado inicia el mismo asistente. Luego:

livewiki init --batch

El pipeline reanudable planifica unidades de página reales y escribe una página por cada archivo de origen y carpeta, además de flujos, temas conceptuales, diagramas y una síntesis understanding.md. Interrúmpelo y reanúdalo con livewiki batch resume <runId>.

4. Verificar y explorar

livewiki verify   # validate code references, internal links, and artifacts
livewiki view     # build an offline site with search, Mermaid, and dark mode

Funciona con tu agente de código

livewiki install detecta automáticamente y conecta 13 agentes a través de MCP (con habilidades y ganchos donde el agente los soporta):

Claude Code · Codex · Cursor · Kimi · Gemini CLI · OpenCode · OpenClaw · Cline · Kiro · Qwen · Warp · Zed · Hermes

¿Prefieres conexión manual? Cualquier cliente MCP con stdio funciona:

{
  "mcpServers": {
    "livewiki": {
      "command": "npx",
      "args": ["-y", "@livewiki/mcp", "--repo", "/path/to/repo"]
    }
  }
}

Lenguajes

Las páginas ancladas citan símbolos reales; el suelo de prosa sigue dando a cada archivo un lugar en el wiki. El soporte de lenguajes de nivel 1 crece a medida que el patrón se demuestra (Go, Rust y Java llegaron así).

Proveedores

livewiki config lista estos 17 ajustes preestablecidos. Cada uno lee su propia variable de entorno de clave API; livewiki config show imprime la que espera tu ajuste sin mostrar nunca el valor.

ollama y lmstudio no necesitan clave para un servidor local. Para CI y automatización sin interfaz, define la variable de entorno directamente — tiene prioridad sobre la clave guardada.

Cómo es una página generada

Extracto del propio livewiki/core-src/verify.md de este repositorio:

## Discovery: walking the wiki from disk

The verifier never trusts the index for which pages exist — a doc freshly written by an LLM must be caught without first running `index`. Two walkers enumerate the `livewiki/` directory from disk; both skip hidden directories but keep dot-prefixed files.

<!-- lw:anchors packages/core/src/verify.ts#collectWikiPages packages/core/src/verify.ts#collectWikiArtifactPaths -->

```ts
async function collectWikiPages(absRoot: string): Promise<{ relPath: string }[]>
```

La prosa explica la implementación; el marcador lw:anchors une la sección a símbolos indexados reales, de modo que la desactualización y las referencias no válidas se detectan mecánicamente.

Cómo funciona

• Capa determinista — la CLI indexa el código fuente, extrae símbolos, calcula la desactualización, planifica el trabajo, rastrea la deuda y verifica — sin un modelo.

• Capa de escritura — un agente conectado (o un lote respaldado por API) escribe la prosa, a partir de una lista cerrada de claves de símbolos permitidas.

• Capa anti-alucinación — determinista y estructural: anclas de código, firmas citadas, enlaces internos, artefactos y estructura de página se comprueban contra el disco; las escrituras no válidas se revierten. Elimina referencias fabricadas y podridas, no errores semánticos.

• Propiedad humana — las páginas owner: human nunca se reescriben; los bloques lw:manual se conservan byte a byte.

• Línea base portátil — el estado aceptado de cada obligación de documentación vive en un livewiki/.baseline.json versionado, de modo que la deuda se aplica contra una línea base real y el wiki sobrevive a una caché local eliminada.

La deuda de documentación puede bloquear cada merge en CI, sin llamadas a LLM ni tokens — consulta la plantilla de GitHub Actions.

La metodología de comparación histórica y los resultados fechados están archivados en Benchmarks.

Paquetes

Documentación

• SPEC.md — contratos de comportamiento y formato

• VISION.md — justificación del producto y no objetivos

• docs/ROADMAP.md — backlog aprobado y orden de ejecución

Licencia

MIT — consulta LICENSE.