livewiki

コードにアンカーされた、陳腐化を自動検知するドキュメンテーション。

livewiki はリポジトリを Markdown ウィキに変換します。そこではすべてのコード参照が、実際にインデックス化されたシンボルに アンカー されています。散文は LLM が書き、livewiki は決定論的な作業を担います — ページの計画、モデルが書いた内容に対する構造的な反ハルシネーションチェックの実行、変更されたアンカー付きシンボルの追跡、そしてあなたの編集の保持です。

ウィキは、@livewiki/mcp を通じてあらゆるコーディングエージェントに公開されます。これは、ウィキの読み取り、検索、安全な書き込みのための8つのツールを備えた MCP (Model Context Protocol) サーバーです。

livewiki view はウィキから自己完結型のオフラインサイトを構築します — グループ化されたサイドバー、オフライン検索、ダイアグラム、ダークモード:

livewiki が外部の Python リポジトリ MoneyPrinterTurbo-Plus 用に生成したウィキの例。

なぜ

技術ドキュメントは、コードが変わった瞬間に陳腐化します。livewiki はそれを黙らせるのではなく、可視化し、低コストで修正できるようにします:

• 決定論的な反ハルシネーションチェック。 すべてのコード参照は、実際にインデックス化されたシンボルを指していなければなりません。livewiki verify はディスクからウィキを新たに読み取り、存在しないシンボル、壊れたアンカー、一致しなくなったシグネチャを検出して失敗させます — これには LLM が数秒前に書いた参照も含まれ、先に index を実行する必要も、トークンを消費することもありません。意味論ではなく構造のチェックです。その線引きは以下のセクションで説明します。

• あなたの編集が優先されます。 owner: human とマークしたページは決して書き換えられず、lw:manual ブロックはバイト単位でそのまま保持されます。

• 負債は「発見」ではなく「追跡」されます。 livewiki status は乖離した箇所をランク付けします。GitHub Action を使えば、トークンを消費せずに、ドキュメント負債ゼロをすべてのマージのゲートにできます。

• すでに使っている環境で動作します。 使用中のコーディングエージェントを通じてブートストラップとメンテナンスを行うか、完全自動のバッチを実行します。

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

反ハルシネーションレイヤーは決定論的かつ構造的です。livewiki verify はディスクからウィキを新たに読み取るため、LLM が数秒前に書いたページも、先に index を実行することなくチェックされ、以下の場合に失敗します:

• コードに存在しない引用シンボルがある場合;

• シンボルの移動、名前変更、削除によってアンカーが壊れた場合;

• 引用されたシグネチャがインデックス化されたものと一致しなくなった場合;

• 解決できない内部リンクがある場合;

• 参照されたアーティファクトがディスク上にない場合;

• フォーマット契約に違反する frontmatter またはページ構造がある場合。

これにより、読者が目にする前に、捏造されたコンテンツのクラス全体 — 存在しない関数、実在しなかった API、静かに腐敗した参照 — がトークンコストゼロで排除されます。失敗したものはマージされず、拒否されてロールバックされます。

ただし、これは文が真実であることを証明するものではありません。実際に存在するコードに対するもっともらしいが誤った説明は、上記のすべてのチェックを通過します。上記のチェックはすべて、意味ではなく構造と同一性に関するものだからです。ここでの「反ハルシネーション」は、捏造の大きなクラスを機械的に排除し、散文の下でコードが動いた瞬間を知らせるレイヤーとして読んでください — 事実の正確さの保証としてではありません。説明自体のレビューは依然としてあなたの仕事です。

Related MCP server: wiki-helper

クイックスタート

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

1. インストール

npm install -g @livewiki/cli

(グローバルインストールしなくても npx @livewiki/cli が使えます。)

2. 初期化

ドキュメント化したいリポジトリのルートで実行します:

livewiki init

コードをインデックス化し、livewiki/ の下にウィキのスケルトンを、.livewiki/ の下に派生キャッシュを作成します (.gitignore に追加されます)。決定論的です — LLM 呼び出しもトークンも不要です。

3. ウィキを一度ブートストラップする

ルートは2つあります — どちらかを選択してください。

ルート A — コーディングエージェント経由 (API キー不要):

livewiki install

インストーラーはエージェントを検出し、MCP サーバー、document-as-you-go スキル、git フックを配線します。その後、エージェントにウィキのブートストラップを依頼します。エージェントは 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"]
    }
  }
}

言語

アンカー付きページは実際のシンボルを引用します。散文フロアは、それでもすべてのファイルにウィキ内の居場所を与えます。Tier-1 言語サポートは、パターンが実証されるにつれて拡大します (Go、Rust、Java はそれぞれこの方法で追加されました)。

プロバイダー

livewiki config はこれらの17のプリセットを一覧表示します。各プリセットは独自の API キー環境変数を読み取ります。livewiki config show は、プリセットが期待する環境変数名を、値を表示することなく出力します。

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.

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

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

散文は実装を説明し、lw:anchors マーカーはセクションを実際にインデックス化されたシンボルに結び付けます。そのため、陳腐化や無効な参照は機械的に検出されます。

仕組み

• 決定論的レイヤー — CLI はモデルを使わずに、ソースのインデックス化、シンボルの抽出、陳腐化の計算、作業の計画、負債の追跡、検証を行います。

• ライティングレイヤー — 接続されたエージェント (または API を利用したバッチ) が、許可されたシンボルキーのクローズドリストから散文を書きます。

• 反ハルシネーションレイヤー — 決定論的かつ構造的: コードアンカー、引用されたシグネチャ、内部リンク、アーティファクト、ページ構造がすべてディスクと照合され、無効な書き込みはロールバックされます。捏造された参照と腐敗した参照を排除しますが、意味論的な誤りは排除しません。

• 人間による所有 — owner: human のページは決して書き換えられず、lw:manual ブロックはバイト単位でそのまま保持されます。

• ポータブルなベースライン — すべてのドキュメント義務の承認済み状態は、バージョン管理された livewiki/.baseline.json に保存されます。そのため、負債は実際のベースラインに対して強制され、ローカルキャッシュが削除されてもウィキは失われません。

ドキュメント負債は、LLM 呼び出しやトークンを必要とせずに、CI のすべてのマージをゲートできます — GitHub Actions テンプレート を参照してください。

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

パッケージ

ドキュメント

• SPEC.md — 動作とフォーマットの契約

• VISION.md — 製品の根拠と非目標

• docs/ROADMAP.md — 承認済みバックログと実行順序

ライセンス

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