Metadata-Version: 2.4
Name: pwiki-cli
Version: 0.3.1
Summary: Karpathy's LLM Wiki, brew-install ready. Sync, query, and graph any repo's wiki into your Obsidian Vault.
Project-URL: Homepage, https://github.com/zxs1633079383/pwiki
Project-URL: Documentation, https://github.com/zxs1633079383/pwiki#readme
Project-URL: Issues, https://github.com/zxs1633079383/pwiki/issues
Project-URL: Source, https://github.com/zxs1633079383/pwiki
Author: zlc
License: MIT
License-File: LICENSE
Keywords: claude-code,json-canvas,karpathy,knowledge-base,llm-wiki,obsidian,personal-knowledge-management,second-brain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: fastembed>=0.4; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: markdown-it-py>=3.0; extra == 'all'
Requires-Dist: numpy>=1.24; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: rag
Requires-Dist: fastembed>=0.4; extra == 'rag'
Requires-Dist: numpy>=1.24; extra == 'rag'
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == 'serve'
Requires-Dist: jinja2>=3.1; extra == 'serve'
Requires-Dist: markdown-it-py>=3.0; extra == 'serve'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'serve'
Description-Content-Type: text/markdown

# pwiki

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

[![PyPI version](https://img.shields.io/pypi/v/pwiki.svg)](https://pypi.org/project/pwiki/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Karpathy LLM Wiki](https://img.shields.io/badge/pattern-Karpathy_LLM_Wiki-purple.svg)](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

![pwiki demo](docs/demo.gif)

> *"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."*
> — Andrej Karpathy, [LLM Wiki Gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), April 2026

---

## What is pwiki

Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 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

```bash
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)

```bash
cd ~/your-project
pip install -U "pwiki-cli[rag,serve]"
pwiki init                  # 1. detects project + AI tools
                            # 2. writes Karpathy's full LLM Wiki pattern into
                            #    CLAUDE.md / AGENTS.md / .cursor/rules / GEMINI.md / .clinerules
                            # 3. bootstraps docs/wiki/ scaffold
```

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 protocol in its loaded instructions: 6 page
types (Entity / Concept / Operation / Comparison / Synthesis / Summary),
8-step bootstrap, citation rules, quality bar. It reads your README + source
tree, writes 5-15 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, 4205-line ARCHITECTURE.md:
8 wiki pages distilled, 38 cross-page links, full canvas in `~60 seconds`,
zero hand-typed CLI commands after `pwiki init`.

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

```bash
# 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]'`.

```bash
# 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](https://jsoncanvas.org) 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](https://github.com/vrtmrz/obsidian-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`](https://github.com/Ar9av/obsidian-wiki) | Skill-based framework, ingest pipeline | One-line install, multi-repo Vault, JSON Canvas |
| [`AgriciDaniel/claude-obsidian`](https://github.com/AgriciDaniel/claude-obsidian) | `/wiki /save /autoresearch` slash commands | Cross-repo concept carom + Ebbinghaus review |
| [`NicholasSpisak/second-brain`](https://github.com/NicholasSpisak/second-brain) | Personal vault skills | Daily brief + weekly evolution rollup |
| Karpathy's [original gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) | The pattern itself | Brew-install-ready CLI + per-command help |

See [`docs/COMPARISON.md`](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`](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.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`](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:

```bash
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](LICENSE) — do whatever you want, including commercial use.

## Acknowledgements

- Andrej Karpathy for [the LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) that started all of this in April 2026.
- The [Obsidian](https://obsidian.md) team and [kepano](https://github.com/kepano) for the [obsidian-skills](https://github.com/kepano/obsidian-skills) collection.
- [vrtmrz](https://github.com/vrtmrz) for [Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync) — the multi-device sync layer pwiki recommends.
- [@karpathy](https://x.com/karpathy) for the framing that turned a markdown folder into a programming environment.
