Livewiki

livewiki

Code-anchored documentation that knows when it is stale.

livewiki turns a repository into a Markdown wiki whose every code reference is anchored to a real indexed symbol. An LLM writes the prose; livewiki does the deterministic work — planning the pages, running structural anti-hallucination checks on what the model wrote, tracking which anchored symbols changed, and preserving your edits.

The wiki is exposed to any coding agent by @livewiki/mcp — an MCP (Model Context Protocol) server with eight tools for reading, searching, and safely writing the wiki.

livewiki view builds a self-contained offline site from the wiki — grouped sidebar, offline search, diagrams, and dark mode:

Example wiki generated by livewiki for MoneyPrinterTurbo-Plus, an external Python repository.

Why

Technical docs go stale the moment the code changes. livewiki makes that visible and cheap to fix instead of silent:

• Deterministic anti-hallucination checks. Every code reference must point at a real indexed symbol. livewiki verify reads the wiki fresh from disk and fails on invented symbols, broken anchors, and signatures that no longer match — including references the LLM wrote seconds ago, without running index first, and without spending a token. Structural, not semantic; the section below draws the line.
• Your edits win. Pages you mark owner: human are never rewritten, and lw:manual blocks are preserved byte-for-byte.
• Debt is tracked, not discovered. livewiki status ranks what drifted; a GitHub Action can gate every merge on zero documentation debt, without spending tokens.
• Works where you already work. Bootstrap and maintain through the coding agent you use, or run a fully automated batch.

What verify checks — and what it doesn't

The anti-hallucination layer is deterministic and structural. livewiki verify reads the wiki fresh from disk — so a page an LLM wrote seconds ago is checked without running index first — and fails on:

• a cited symbol that does not exist in the code;
• an anchor that broke because the symbol moved, was renamed, or was deleted;
• a cited signature that no longer matches the indexed one;
• an internal link that does not resolve;
• a referenced artifact that is missing from disk;
• frontmatter or page structure that violates the format contract.

That removes whole classes of fabricated content — the invented function, the API that never existed, the reference that quietly rotted — before a reader ever sees it, at zero token cost. Anything that fails is rejected and rolled back rather than merged.

It does not prove that a sentence is true. A plausible but wrong explanation of code that really does exist passes every check above, because every check above is about structure and identity, not meaning. Read "anti-hallucination" here as a layer that mechanically eliminates a large class of fabrication and tells you the moment code moves under the prose — not as a guarantee of factual accuracy. Reviewing the explanation itself is still your job.

Quick start

Requires Node.js 24 or newer.

1. Install

npm install -g @livewiki/cli

(npx @livewiki/cli works too, without installing globally.)

2. Initialize

From the root of the repository you want documented:

livewiki init

Indexes the code and creates the wiki skeleton under livewiki/, plus a derived cache under .livewiki/ (added to .gitignore). Deterministic — no LLM call, no tokens.

3. Bootstrap the wiki once

You have two routes — pick one.

Route A — through your coding agent (no API key needed):

livewiki install

The installer detects your agent, wires the MCP server, the document-as-you-go skill, and git hooks. Then ask the agent to bootstrap the wiki; it pulls tasks from livewiki_next_task and submits pages with livewiki_write_doc using the model it already has.

Route B — a configured LLM API (unattended):

livewiki config

The wizard lists the providers, asks for your API key (typed without echo), and saves it. Bare livewiki on an unconfigured repo starts the same wizard. Then:

livewiki init --batch

The resumable pipeline plans real page units and writes one page per source file and folder, plus flows, concept topics, diagrams, and an understanding.md synthesis. Interrupt it and resume with livewiki batch resume <runId>.

4. Verify and browse

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

Works with your coding agent

livewiki install auto-detects and wires 13 agents over MCP (with skills and hooks where the agent supports them):

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

Prefer manual wiring? Any stdio MCP client works:

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

The server is also published to the official MCP Registry as io.github.eduardoabreu81/livewiki, so a client that resolves servers from the registry can find it by name instead of using the snippet above.

Languages

Anchored pages cite real symbols; the prose floor still gives every file a place in the wiki. Tier-1 language support grows as the pattern is proven (Go, Rust, and Java each landed this way).

Providers

livewiki config lists these 17 presets. Each reads its own API-key environment variable; livewiki config show prints the one your preset expects without ever showing the value.

ollama and lmstudio need no key for a local server. For CI and headless automation, set the env var directly — it takes precedence over the saved key.

What a generated page looks like

Excerpt from this repository's own livewiki/core-src/verify.md:

## 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.

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

The prose explains the implementation; the lw:anchors marker ties the section to real indexed symbols, so staleness and invalid references are detected mechanically.

How it works

• Deterministic layer — the CLI indexes source, extracts symbols, computes staleness, plans work, tracks debt, and verifies — without a model.
• Writing layer — a connected agent (or an API-backed batch) writes the prose, from a closed list of allowed symbol keys.
• Anti-hallucination layer — deterministic and structural: code anchors, cited signatures, internal links, artifacts, and page structure are all checked against disk; invalid writes are rolled back. It eliminates fabricated and rotted references, not semantic mistakes.
• Human ownership — owner: human pages are never rewritten; lw:manual blocks are preserved byte-for-byte.
• Portable baseline — the accepted state of every documentation obligation lives in a versioned livewiki/.baseline.json, so debt is enforced against a real baseline and the wiki survives a deleted local cache.

Documentation debt can gate every merge in CI, without LLM calls or tokens — see the GitHub Actions template.

Historical comparison methodology and dated results are archived in Benchmarks.

Packages

Documentation

• SPEC.md — behavior and format contracts
• VISION.md — product rationale and non-goals
• docs/ROADMAP.md — approved backlog and execution order

License

MIT — see LICENSE.

☕ Ko-fi