pwiki-cli 0.3.0

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

pwiki

Karpathy's LLM Wiki, brew-install ready. Turn any folder into a self-maintaining knowledge base your LLM can actually reason over.

"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)

cd ~/your-project
pip install -U "pwiki-cli[rag,serve]"
pwiki init                  # detects project + AI tools, writes per-tool instructions, bootstraps docs/wiki/

After pwiki init, you should not need to type pwiki commands again. Open Cursor / Claude Code / Codex / Gemini CLI in the project and say things like "sync the wiki", "今天的早报", "find my notes on X" — your AI reads the per-tool instructions file (CLAUDE.md / AGENTS.md / .cursor/rules/pwiki.md / GEMINI.md / .clinerules) and runs the right pwiki <subcommand> for you.

If the AI doesn't have a docs/wiki/ to sync, pwiki init bootstraps a scaffold + writes docs/wiki/_llm-prompt.md — paste that prompt into the AI to have it fill the wiki from your source code.

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: Five-command CLI, JSON Canvas, Ebbinghaus, weekly evolution.
• ✅ 0.2: alias-extraction Pass 4 covers English-named files (--dict for custom mappings); pwiki query "<text>" (grep) + pwiki query --rag (local fastembed semantic search, multilingual MiniLM, ~120MB ONNX).
• ✅ 0.3: pwiki serve — local web UI with D3 Canvas viewer, wikilink-aware markdown rendering, inline search (grep + RAG toggle).
• 🟡 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.