pwiki-cli 0.3.3

Karpathy's LLM Wiki, brew-install ready. Sync, query, and graph any repo's wiki into your Obsidian Vault.

pwiki

English | 中文

Karpathy's LLM Wiki, one pip install away. Turn any folder into a self-maintaining knowledge base your LLM can actually reason over — at the same depth a senior engineer would write.

"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." — Andrej Karpathy, LLM Wiki Gist, April 2026

---

What is pwiki

Karpathy's LLM Wiki pattern — turn raw notes and code wikis into structured markdown an LLM can navigate, query, and grow. pwiki packages that pattern as a CLI you can install in 10 seconds and a Vault layout that just works.

You point it at a wiki/ directory generated by Claude Code (or any LLM that produces markdown). pwiki copies it into your Obsidian Vault, adds frontmatter, builds a JSON Canvas knowledge graph across every repo you've ingested, and gives you a daily morning brief that surfaces what's due for review and what cross-repo concepts collided overnight.

It's the unopinionated middleware between (your code) and (your second brain).

Install

pip install -U pwiki-cli     # PyPI (the `pwiki` name was taken; CLI command is still `pwiki`)
# or, from source:
git clone https://github.com/zxs1633079383/pwiki && cd pwiki && pip install -e .

Requires Python 3.10+ and a folder you want to use as your Obsidian Vault (default: ~/Documents/Obsidian Vault).

Quick Start (one command + one phrase)

cd ~/your-project
pip install -U "pwiki-cli[rag,serve]"
pwiki init                  # 1. counts your LOC, recommends a page count tier
                            # 2. detects 5 AI tools (CLAUDE.md / AGENTS.md / .cursor/rules / GEMINI.md / .clinerules)
                            # 3. injects Karpathy's full LLM Wiki pattern into each
                            # 4. bootstraps docs/wiki/ scaffold

What you'll see (real output on a 50K-LOC project):

🐦 pwiki init  (v0.3.1)
  project root: /Users/you/your-project
  language    : javascript  (git: yes)
  scale       : 52,431 LOC across 14 modules → recommend 35-50 wiki pages
  arch docs   : ARCHITECTURE.md, docs/CONVENTIONS.md
✓ AI instructions written:
   updated  CLAUDE.md   (Claude Code)
   updated  AGENTS.md   (Codex CLI)
   updated  GEMINI.md   (Gemini CLI)
✅ pwiki init complete

Now open Cursor / Claude Code / Codex / Gemini CLI in your project and say:

"fill the wiki" / "帮我填 wiki" / "scan my code and write the wiki"

Your AI already has the full 0.3.1 protocol loaded:

• Scale-aware page count — your project's LOC determines target page count (5-8 / 10-15 / 20-30 / 35-50)
• 6 page types — Entity / Concept / Operation / Comparison / Synthesis / Summary
• Mandatory 6-section page structure — TL;DR + ≥2 content sections + Source Anchors table (≥3 rows with line numbers) + ≥2 Q&A pairs + ≥2 wikilink cross-references
• Citation density target — ≥3 source-path citations per page, with line numbers (src/foo.ts:123)
• Quality bar — 400-800 words/page; stub pages are rejected output

The AI reads your README + source tree, writes the pages, runs pwiki sync + pwiki aliases + pwiki canvas, and reports back. You don't type any other pwiki commands.

Real example — Angular 20 + Tauri 2 desktop client, ~50K LOC: the scale signal flags the 50K+ tier → recommend 35-50 pages. Each page lands with a 源码锚点 table that anchors every claim back to specific src-tauri/... and src/... files at line numbers, so a new contributor can verify the wiki against the source before touching a PR.

Manual mode (60 seconds, if you prefer to drive)

# 1. Ingest a wiki/ directory into your Vault as repos/<name>/
pwiki sync ./my-project/docs/wiki my-project

# 2. Resolve [[english-slug]] wikilinks against Chinese/non-stem filenames
#    (handles the common "wiki uses slug, files use prose-name" pattern)
pwiki aliases my-project

# 3. Render every synced repo as a JSON Canvas graph (open in Obsidian)
pwiki canvas

# 4. Build today's morning brief (Ebbinghaus-due review queue + cross-repo signals)
pwiki brief

# 5. (Sundays) Roll up the week's self-evolution entries
pwiki evolution

# 6. Search the Vault — grep mode (zero deps)
pwiki query "blast radius"

# 7. Search semantically — RAG mode (multilingual, fully local)
pip install 'pwiki-cli[rag]'         # adds fastembed (~120MB ONNX model on first use)
pwiki query --rag --rebuild "warmup"      # build index once
pwiki query --rag "how do I detect cross-repo impact"
pwiki query --rag "怎么判断改一个接口会炸到下游哪些服务"   # mixed-language works

Python 3.14 note: the [rag] extra requires onnxruntime, which currently ships wheels for Python 3.10–3.13 only. If you're on 3.14, run pwiki in a 3.13 venv: python3.13 -m venv ~/.pwiki-venv && ~/.pwiki-venv/bin/pip install 'pwiki-cli[rag]'.

# 8. Browse the Vault in a local web UI (with D3 Canvas viewer)
pip install 'pwiki-cli[serve]'
pwiki serve --port 8080 --open
# → http://127.0.0.1:8080/
#   home  /         repos list + recent dailies + opportunities
#   /repo/<name>/   notes by category
#   /note/<path>    rendered markdown (wikilinks resolve through aliases)
#   /daily/<date>   daily brief
#   /canvas/        D3 force-directed graph of every cross-repo edge
#   ?q=...&rag=1    inline search (header bar, RAG checkbox)

Every command is idempotent. Re-running on the same input updates frontmatter timestamps and refreshes the index, never destroys content.

What you get

• repos/<name>/ — your wiki, mirrored, with managed YAML frontmatter (source_repo, last_synced, ebbinghaus_stage, last_reviewed, tags).
• canvas/all-repos.canvas — a JSON Canvas graph: every repo as a labeled group, every note as a file node, edges drawn from resolved wikilinks (cross-repo too).
• daily/<date>.md — a 4-section morning brief: ① Ebbinghaus-due reviews ② 10 frontier directions (cross-repo concept carom) ③ 1 deep opportunity ④ self-evolution (rotates 4 quadrants by weekday).
• evolution/<YYYY>-W<WW>.md — weekly digest of §④ entries grouped by quadrant.
• opportunities/ — your own promotion target when §② surfaces something worth pursuing.

The whole thing is plain markdown. Open it in Obsidian, edit by hand, version with git, sync with Self-hosted LiveSync — pwiki never locks you in.

Why not just use the Karpathy gist directly?

Six excellent open implementations have appeared in the 30 days since Karpathy's gist dropped (April 2026):

Project	Focus	What pwiki adds
Ar9av/obsidian-wiki	Skill-based framework, ingest pipeline	One-line install, multi-repo Vault, JSON Canvas
AgriciDaniel/claude-obsidian	/wiki /save /autoresearch slash commands	Cross-repo concept carom + Ebbinghaus review
NicholasSpisak/second-brain	Personal vault skills	Daily brief + weekly evolution rollup
Karpathy's original gist	The pattern itself	Brew-install-ready CLI + per-command help

See docs/COMPARISON.md for a full breakdown.

The honest pitch: every existing implementation requires reading a 50-line tutorial, copy-pasting Python, and configuring paths by hand. pwiki is one pip install and five subcommands. That's the entire delta.

How it actually works

pwiki ships as five composable Python modules around one shared assumption: your Vault is your source of truth, and every file's frontmatter is the contract.

wiki/  ──pwiki sync──→  Vault/repos/<name>/
                            │
                            ├─ adds frontmatter (source_repo, ebbinghaus_stage, …)
                            └─ updates _index.md from _templates/

Vault/repos/  ──pwiki canvas──→  Vault/canvas/all-repos.canvas (JSON Canvas)
                                     │
                                     └─ edges from [[wikilinks]] (resolves through aliases)

Vault/repos/  ──pwiki brief──→  Vault/daily/<today>.md
   + git logs                       │
   from ~/workspace                 ├─ ① review queue (frontmatter → Ebbinghaus)
                                    ├─ ② 10 directions (LLM fills from materials block)
                                    ├─ ③ 1 opportunity
                                    └─ ④ self-evolution (rotates 4 axes by weekday)

Vault/daily/   ──pwiki evolution──→  Vault/evolution/<YYYY>-W<WW>.md
   (past 7 days)                        (grouped by quadrant)

Architecture details: docs/ARCHITECTURE.md.

Roadmap

• ✅ 0.1: 5 命令 CLI + JSON Canvas + Ebbinghaus + 周度演进
• ✅ 0.2: alias Pass 4 支持英文文件名 + pwiki query (grep / RAG via fastembed multilingual MiniLM)
• ✅ 0.3.0: pwiki init — embeds Karpathy's full LLM Wiki pattern (3 layers / 3 operations / 6 page types / 8-step bootstrap / 7-step ingest / 5-category lint) into every AI tool's instruction file. AI auto-fills the wiki from your code; you say one phrase.
• ✅ 0.3 (also): pwiki serve — local web UI with D3 Canvas viewer + inline grep/RAG search.
• ✅ 0.3.1: stop writing stubs. Scale-aware page count (5-8 / 10-15 / 20-30 / 35-50 by LOC tier) + mandatory 6-section page structure (TL;DR + Source Anchors table with line numbers + Q&A + cross-refs) + citation density target ≥3/page. Real-user dogfood on a 50K LOC repo found AI was writing 8 stubs when 25-30 deep pages were needed. 0.3.1 fixes the protocol so the AI defaults to deep, not shallow.
• 🟡 0.4 (hosted, not started): one-click LiveSync-as-a-service so multi-device sync stops being a CouchDB project. Spec: docs/0.4-hosted-spec.md. Implementation gated on ⭐ ≥ 300 (premature SaaS without traction is a known anti-pattern).

Pricing (Freemium)

Tier	Price	What you get
OSS (CLI + serve)	free forever	0.1 → 0.3 全部 — 5 命令 CLI、Canvas、Ebbinghaus、演进、本地 RAG（自带 OpenAI key）、pwiki serve 本地 web UI
Hosted Pro	$9/mo	0.4 hosted LiveSync (no CouchDB to operate) + hosted RAG (cached embeddings) + pwiki.dev/yourname public URL
Team Pro	$29/seat/mo	shared team vault + permissions + aggregated team brief + SSO

Contributing

Bug reports and PRs welcome. Run tests:

pip install -e ".[dev]"
pytest

If you've built something on top of pwiki — a custom quadrant, a new subcommand, a different Canvas layout — open a PR or link me to it. I'll feature it here.

License

MIT — do whatever you want, including commercial use.

Acknowledgements

• Andrej Karpathy for the LLM Wiki gist that started all of this in April 2026.
• The Obsidian team and kepano for the obsidian-skills collection.
• vrtmrz for Self-hosted LiveSync — the multi-device sync layer pwiki recommends.
• @karpathy for the framing that turned a markdown folder into a programming environment.