livewiki

livewiki

コードにアンカーされた、古くなったことが分かるドキュメントです。

livewiki はリポジトリを Markdown の wiki に変換し、コードへのすべての参照を、実際にインデックス化されたシンボルにアンカーします。文章は LLM が作成し、livewiki はページの計画、モデルが作成した内容に対する構造的なアンチハルシネーションチェック、アンカーされたシンボルの変更追跡、編集内容の保持といった決定論的な処理を担います。

wiki は、@livewiki/mcp によってあらゆるコーディングエージェントから利用できます。これは、wiki の読み取り、検索、安全な書き込みを行う 8 つのツールを備えた MCP（Model Context Protocol）サーバーです。

livewiki view は、wiki から自己完結型のオフラインサイトを構築します。グループ化されたサイドバー、オフライン検索、図表、ダークモードを利用できます。

livewiki が外部の Python リポジトリである MoneyPrinterTurbo-Plus 向けに生成した wiki の例です。

---

理由

技術ドキュメントは、コードが変更された瞬間に古くなります。livewiki は、それを気づかれないまま放置するのではなく、可視化して簡単に修正できるようにします。

• 決定論的なアンチハルシネーションチェック。 コードへのすべての参照は、実際にインデックス化されたシンボルを指している必要があります。livewiki verify はディスクから wiki を毎回読み込み、作り上げられたシンボル、壊れたアンカー、現在のシグネチャと一致しないシグネチャがあると失敗します。LLM が数秒前に作成した参照も対象です。事前に index を実行する必要はなく、トークンも消費しません。チェックの対象は構造であり、意味ではありません。その線引きについては以下のセクションを参照してください。
• 編集内容が優先されます。 owner: human とマークしたページは書き換えられず、lw:manual ブロックはバイト単位で保持されます。
• 負債を発見するのではなく、追跡します。 livewiki status は乖離した箇所を優先度順に表示します。GitHub Actions を使えば、トークンを消費せずに、ドキュメント負債がゼロであることをすべてのマージの条件にできます。
• 普段使っている環境で動作します。 利用中のコーディングエージェントを通じてセットアップと保守を行うか、完全自動のバッチ処理を実行できます。

verify がチェックすること — しないこと

アンチハルシネーション層は決定論的で、構造をチェックします。livewiki verify はディスクから wiki を毎回読み込むため、LLM が数秒前に作成したページも、事前に index を実行せずにチェックでき、以下に該当すると失敗します。

• 引用されたシンボルがコードに存在しない。
• シンボルの移動、名前の変更、削除によってアンカーが壊れている。
• 引用されたシグネチャがインデックス化されたシグネチャと一致しなくなっている。
• 内部リンクの参照先が解決できない。
• 参照された成果物がディスク上に存在しない。
• frontmatter またはページ構造がフォーマットの仕様に違反している。

これにより、架空の関数、実在したことのない API、気づかれないうちに古くなった参照といった、作り上げられたコンテンツの大きなカテゴリを、読者の目に触れる前に排除できます。トークンの消費はゼロです。チェックに失敗した内容はマージされず、却下されてロールバックされます。

ただし、文が真実であることを証明するものではありません。実在するコードについての、もっともらしくても誤った説明は、上記のすべてのチェックを通過します。これらのチェックが検証するのは、意味ではなく構造と同一性だからです。ここでいう「アンチハルシネーション」は、作り話の大きなカテゴリを機械的に排除し、文章の背後にあるコードが変更された時点で知らせる層と捉えてください。事実の正確性を保証するものではありません。説明自体をレビューするのは、引き続きあなたの役目です。

クイックスタート

Node.js 24 以降が必要です。

1. インストール

npm install -g @livewiki/cli

（グローバルインストールをしなくても、npx @livewiki/cli を使用できます。）

2. 初期化する

ドキュメント化するリポジトリのルートから、次を実行します。

livewiki init

コードをインデックス化し、livewiki/ に Wiki の骨格を作成するとともに、派生キャッシュを .livewiki/ に作成します（.gitignore に追加されます）。決定論的に処理されるため、LLM の呼び出しもトークンの消費もありません。

3. Wiki を一度だけ初期構築する

方法は 2 つあります。どちらかを選んでください。

方法 A — コーディングエージェント経由（API キー不要）：

livewiki install

インストーラーがエージェントを検出し、MCP サーバー、作業しながらドキュメントを作成するスキル、Git フックを設定します。次に、エージェントに Wiki の初期構築を依頼します。エージェントは livewiki_next_task からタスクを取得し、すでに利用しているモデルを使って livewiki_write_doc でページを送信します。

方法 B — 設定済みの LLM API（無人実行）：

livewiki config

ウィザードにプロバイダーの一覧が表示され、API キーの入力を求められます（入力内容は画面に表示されません）。キーは保存されます。設定されていないリポジトリで livewiki を実行すると、同じウィザードが起動します。

次に、以下を実行します。

livewiki init --batch

中断後に再開できるパイプラインが、実際のページ単位で計画を立て、各ソースファイルとフォルダーにつき 1 ページずつ作成します。さらに、フロー、概念トピック、図、そして統合した understanding.md も作成します。処理を中断した場合は、livewiki batch resume <runId> で再開できます。

4. 検証して閲覧する

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

コーディングエージェントに対応

livewiki install は、MCP 経由で 13 種類のエージェントを自動検出して設定します（エージェントが対応している場合は、スキルとフックも設定します）。

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

手動で設定する場合も、stdio MCP クライアントであれば利用できます。

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

このサーバーは、io.github.eduardoabreu81/livewiki として公式 MCP レジストリにも公開されています。そのため、レジストリからサーバーを検索するクライアントは、上記の設定例を使わずに名前で見つけることができます。

言語

言語	シンボルに紐づくドキュメント（シンボルを抽出）
TypeScript	✅ .ts
JavaScript	✅ .js .mjs .cjs
TSX / JSX	✅ .tsx .jsx
Python	✅ .py
Go	✅ .go
Rust	✅ .rs
Java	✅ .java
その他すべて	文章としての最低限の対応 — すべてのテキストファイルを走査し、シンボルなしの文章としてドキュメント化します

シンボルに紐づくページでは実際のシンボルを参照します。文章としての最低限の対応でも、すべてのファイルに Wiki 内の場所が作成されます。パターンが確立されるにつれて、Tier 1 の言語対応が拡大します（Go、Rust、Java はいずれもこの方法で追加されました）。

プロバイダー

livewiki config では、次の 17 種類のプリセットを確認できます。それぞれが専用の API キー環境変数を読み込みます。livewiki config show は、プリセットが必要とする環境変数を表示しますが、キーの値を表示することはありません。

プロバイダー	プリセット	環境変数
Anthropic	anthropic	ANTHROPIC_API_KEY
OpenAI	openai	OPENAI_API_KEY
OpenRouter	openrouter	OPENROUTER_API_KEY
DeepSeek	deepseek	DEEPSEEK_API_KEY
Kimi (Moonshot)	kimi	MOONSHOT_API_KEY
MiniMax	minimax	MiniMax_API_KEY
Google Gemini	gemini	GEMINI_API_KEY
NVIDIA	nvidia	NVIDIA_API_KEY
Ollama (ローカル)	ollama	OLLAMA_API_KEY (任意)
LM Studio (ローカル)	lmstudio	LMSTUDIO_API_KEY (任意)
Fireworks	fireworks	FIREWORKS_API_KEY
Novita	novita	NOVITA_API_KEY
GMI	gmi	GMI_API_KEY
StepFun	stepfun	STEPFUN_API_KEY
Hugging Face	huggingface	HF_TOKEN
xAI	xai	XAI_API_KEY
Alibaba (DashScope)	alibaba	DASHSCOPE_API_KEY

ollama と lmstudio は、ローカルサーバーの場合、キーは不要です。CI やヘッドレス自動化では、環境変数を直接設定してください。保存済みのキーより環境変数が優先されます。

生成されるページの例

このリポジトリ自体の 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 }[]>
```

文章では実装について説明し、lw:anchors マーカーでセクションを実際にインデックス化されたシンボルに紐づけます。そのため、古くなった情報や無効な参照を機械的に検出できます。

仕組み

• 決定論的レイヤー — CLI はモデルを使わずに、ソースをインデックス化し、シンボルを抽出し、陳腐化の度合いを計算し、作業を計画し、負債を追跡して検証します。
• 執筆レイヤー — 接続されたエージェント（または API を利用したバッチ処理）が、使用を許可されたシンボルキーの一覧に基づいて文章を作成します。
• ハルシネーション防止レイヤー — 決定論的かつ構造的に検証します。コードアンカー、引用されたシグネチャ、内部リンク、アーティファクト、ページ構造をすべてディスク上の内容と照合し、無効な書き込みはロールバックします。排除するのは捏造された参照や古くなった参照であり、意味上の誤りではありません。
• 人間による所有 — owner: human のページは書き換えず、lw:manual ブロックはバイト単位でそのまま保持します。
• 移植可能なベースライン — ドキュメントに関する各義務の承認済み状態は、バージョン管理された livewiki/.baseline.json に保存されます。そのため、実際のベースラインに照らして負債を確実に管理でき、ローカルキャッシュが削除されても Wiki は維持されます。

ドキュメント負債は、LLM の呼び出しやトークンを使わずに、CI であらゆるマージのゲートとして設定できます。GitHub Actions テンプレートを参照してください。

過去との比較方法と日付付きの結果は、ベンチマークにアーカイブされています。

パッケージ

パッケージ	目的
@livewiki/cli	livewiki コマンド
@livewiki/mcp	stdio に対応した MCP クライアント向けの MCP サーバー
@livewiki/core	ライブラリ：インデクサー、アンカー、台帳、パイプライン

ドキュメント

• SPEC.md — 動作と形式の契約
• VISION.md — プロダクトの目的と対象外の事項
• docs/ROADMAP.md — 承認済みのバックログと実行順序

ライセンス

MIT — LICENSEを参照してください。

---