{
  "markdown": "# livewiki\n\n**Code-anchored documentation that knows when it is stale.**\n\nlivewiki turns a repository into a Markdown wiki whose every code reference is\n*anchored* to a real indexed symbol. An LLM writes the prose; livewiki does the\ndeterministic work — planning the pages, running **structural\nanti-hallucination checks** on what the model wrote, tracking which anchored\nsymbols changed, and preserving your edits.\n\nThe wiki is exposed to any coding agent by\n**[`@livewiki/mcp`](packages/mcp)** — an **MCP (Model Context Protocol)\nserver** with eight tools for reading, searching, and safely writing the wiki.\n\n[![npm @livewiki/cli](https://img.shields.io/npm/v/@livewiki/cli?label=cli)](https://www.npmjs.com/package/@livewiki/cli)\n[![npm @livewiki/mcp](https://img.shields.io/npm/v/@livewiki/mcp?label=mcp)](https://www.npmjs.com/package/@livewiki/mcp)\n[![CI](https://github.com/eduardoabreu81/livewiki/actions/workflows/cross-platform-ci.yml/badge.svg)](https://github.com/eduardoabreu81/livewiki/actions/workflows/cross-platform-ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n`livewiki view` builds a self-contained offline site from the wiki — grouped\nsidebar, offline search, diagrams, and dark mode:\n\n![livewiki viewer showing a generated quickstart page](docs/assets/viewer-quickstart.jpg)\n\n*Example wiki generated by livewiki for MoneyPrinterTurbo-Plus, an external\nPython repository.*\n\n---\n\n## Why\n\nTechnical docs go stale the moment the code changes. livewiki makes that\nvisible and cheap to fix instead of silent:\n\n- **Deterministic anti-hallucination checks.** Every code reference must point\n  at a real indexed symbol. `livewiki verify` reads the wiki fresh from disk and\n  fails on invented symbols, broken anchors, and signatures that no longer match\n  — including references the LLM wrote seconds ago, without running `index`\n  first, and without spending a token. Structural, not semantic; the section\n  below draws the line.\n- **Your edits win.** Pages you mark `owner: human` are never rewritten, and\n  `lw:manual` blocks are preserved byte-for-byte.\n- **Debt is tracked, not discovered.** `livewiki status` ranks what drifted;\n  a GitHub Action can gate every merge on zero documentation debt, without\n  spending tokens.\n- **Works where you already work.** Bootstrap and maintain through the coding\n  agent you use, or run a fully automated batch.\n\n### What `verify` checks — and what it doesn't\n\nThe anti-hallucination layer is deterministic and structural. `livewiki verify`\nreads the wiki fresh from disk — so a page an LLM wrote seconds ago is checked\nwithout running `index` first — and fails on:\n\n- a cited symbol that does not exist in the code;\n- an anchor that broke because the symbol moved, was renamed, or was deleted;\n- a cited signature that no longer matches the indexed one;\n- an internal link that does not resolve;\n- a referenced artifact that is missing from disk;\n- frontmatter or page structure that violates the format contract.\n\nThat removes whole classes of fabricated content — the invented function, the\nAPI that never existed, the reference that quietly rotted — before a reader\never sees it, at zero token cost. Anything that fails is rejected and rolled\nback rather than merged.\n\nIt does **not** prove that a sentence is true. A plausible but wrong\nexplanation of code that really does exist passes every check above, because\nevery check above is about structure and identity, not meaning. Read\n\"anti-hallucination\" here as a layer that mechanically eliminates a large class\nof fabrication and tells you the moment code moves under the prose — not as a\nguarantee of factual accuracy. Reviewing the explanation itself is still your\njob.\n\n## Quick start\n\nRequires **Node.js 24 or newer**.\n\n### 1. Install\n\n```bash\nnpm install -g @livewiki/cli\n```\n\n(`npx @livewiki/cli` works too, without installing globally.)\n\n### 2. Initialize\n\nFrom the root of the repository you want documented:\n\n```bash\nlivewiki init\n```\n\nIndexes the code and creates the wiki skeleton under `livewiki/`, plus a\nderived cache under `.livewiki/` (added to `.gitignore`). Deterministic — no\nLLM call, no tokens.\n\n### 3. Bootstrap the wiki once\n\nYou have two routes — pick one.\n\n**Route A — through your coding agent (no API key needed):**\n\n```bash\nlivewiki install\n```\n\nThe installer detects your agent, wires the MCP server, the\ndocument-as-you-go skill, and git hooks. Then ask the agent to bootstrap the\nwiki; it pulls tasks from `livewiki_next_task` and submits pages with\n`livewiki_write_doc` using the model it already has.\n\n**Route B — a configured LLM API (unattended):**\n\n```bash\nlivewiki config\n```\n\nThe wizard lists the providers, asks for your API key (typed without echo),\nand saves it. Bare `livewiki` on an unconfigured repo starts the same wizard.\nThen:\n\n```bash\nlivewiki init --batch\n```\n\nThe resumable pipeline plans real page units and writes one page per source\nfile and folder, plus flows, concept topics, diagrams, and an\n`understanding.md` synthesis. Interrupt it and resume with\n`livewiki batch resume <runId>`.\n\n### 4. Verify and browse\n\n```bash\nlivewiki verify   # validate code references, internal links, and artifacts\nlivewiki view     # build an offline site with search, Mermaid, and dark mode\n```\n\n## Works with your coding agent\n\n`livewiki install` auto-detects and wires **13 agents** over MCP (with skills\nand hooks where the agent supports them):\n\nClaude Code · Codex · Cursor · Kimi · Gemini CLI · OpenCode · OpenClaw ·\nCline · Kiro · Qwen · Warp · Zed · Hermes\n\nPrefer manual wiring? Any stdio MCP client works:\n\n```json\n{\n  \"mcpServers\": {\n    \"livewiki\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@livewiki/mcp\", \"--repo\", \"/path/to/repo\"]\n    }\n  }\n}\n```\n\nThe server is also published to the [official MCP\nRegistry](https://registry.modelcontextprotocol.io) as\n`io.github.eduardoabreu81/livewiki`, so a client that resolves servers from the\nregistry can find it by name instead of using the snippet above.\n\n## Languages\n\n| Language | Anchored docs (symbols extracted) |\n| --- | --- |\n| TypeScript | ✅ `.ts` |\n| JavaScript | ✅ `.js` `.mjs` `.cjs` |\n| TSX / JSX | ✅ `.tsx` `.jsx` |\n| Python | ✅ `.py` |\n| Go | ✅ `.go` |\n| Rust | ✅ `.rs` |\n| Java | ✅ `.java` |\n| **Everything else** | Prose floor — every text file is walked and documented as prose, no symbols |\n\nAnchored pages cite real symbols; the prose floor still gives every file a\nplace in the wiki. Tier-1 language support grows as the pattern is proven\n(Go, Rust, and Java each landed this way).\n\n## Providers\n\n`livewiki config` lists these 17 presets. Each reads its own API-key\nenvironment variable; `livewiki config show` prints the one your preset\nexpects without ever showing the value.\n\n| Provider | Preset | Env var |\n| --- | --- | --- |\n| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |\n| OpenAI | `openai` | `OPENAI_API_KEY` |\n| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |\n| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |\n| Kimi (Moonshot) | `kimi` | `MOONSHOT_API_KEY` |\n| MiniMax | `minimax` | `MiniMax_API_KEY` |\n| Google Gemini | `gemini` | `GEMINI_API_KEY` |\n| NVIDIA | `nvidia` | `NVIDIA_API_KEY` |\n| Ollama *(local)* | `ollama` | `OLLAMA_API_KEY` *(optional)* |\n| LM Studio *(local)* | `lmstudio` | `LMSTUDIO_API_KEY` *(optional)* |\n| Fireworks | `fireworks` | `FIREWORKS_API_KEY` |\n| Novita | `novita` | `NOVITA_API_KEY` |\n| GMI | `gmi` | `GMI_API_KEY` |\n| StepFun | `stepfun` | `STEPFUN_API_KEY` |\n| Hugging Face | `huggingface` | `HF_TOKEN` |\n| xAI | `xai` | `XAI_API_KEY` |\n| Alibaba (DashScope) | `alibaba` | `DASHSCOPE_API_KEY` |\n\n`ollama` and `lmstudio` need no key for a local server. For CI and headless\nautomation, set the env var directly — it takes precedence over the saved key.\n\n## What a generated page looks like\n\nExcerpt from this repository's own\n[`livewiki/core-src/verify.md`](livewiki/core-src/verify.md):\n\n````markdown\n## Discovery: walking the wiki from disk\n\nThe 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.\n\n<!-- lw:anchors packages/core/src/verify.ts#collectWikiPages packages/core/src/verify.ts#collectWikiArtifactPaths -->\n\n```ts\nasync function collectWikiPages(absRoot: string): Promise<{ relPath: string }[]>\n```\n````\n\nThe prose explains the implementation; the `lw:anchors` marker ties the section\nto real indexed symbols, so staleness and invalid references are detected\nmechanically.\n\n## How it works\n\n- **Deterministic layer** — the CLI indexes source, extracts symbols, computes\n  staleness, plans work, tracks debt, and verifies — without a model.\n- **Writing layer** — a connected agent (or an API-backed batch) writes the\n  prose, from a closed list of allowed symbol keys.\n- **Anti-hallucination layer** — deterministic and structural: code anchors,\n  cited signatures, internal links, artifacts, and page structure are all\n  checked against disk; invalid writes are rolled back. It eliminates fabricated\n  and rotted references, not semantic mistakes.\n- **Human ownership** — `owner: human` pages are never rewritten; `lw:manual`\n  blocks are preserved byte-for-byte.\n- **Portable baseline** — the accepted state of every documentation obligation\n  lives in a versioned `livewiki/.baseline.json`, so debt is enforced against a\n  real baseline and the wiki survives a deleted local cache.\n\nDocumentation debt can gate every merge in CI, without LLM calls or tokens —\nsee the [GitHub Actions template](packages/cli/templates/github-actions/docs-debt.yml).\n\nHistorical comparison methodology and dated results are archived in\n[Benchmarks](docs/BENCHMARKS.md).\n\n## Packages\n\n| Package | Purpose |\n| --- | --- |\n| [`@livewiki/cli`](https://www.npmjs.com/package/@livewiki/cli) | The `livewiki` command |\n| [`@livewiki/mcp`](https://www.npmjs.com/package/@livewiki/mcp) | MCP server for stdio-capable MCP clients |\n| [`@livewiki/core`](https://www.npmjs.com/package/@livewiki/core) | Library: indexer, anchors, ledger, pipeline |\n\n## Documentation\n\n- [SPEC.md](SPEC.md) — behavior and format contracts\n- [VISION.md](VISION.md) — product rationale and non-goals\n- [docs/ROADMAP.md](docs/ROADMAP.md) — approved backlog and execution order\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 10407,
  "sha": "6dc12cf4e47475cc21547e59cbf3ed0c0f1a9a027e8b790bcfd28ed0c652cbc8",
  "repo_slug": "eduardoabreu81/livewiki",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_eduardoabreu81_livewiki_0fffac75/readme"
}