Skip to content
Back to search

llm-wiki-compiler

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin that compiles markdown knowledge files into a topic-based wiki. Implements Karpathy's LLM Knowledge Base pattern.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ussumant--llm-wiki-compiler/badge.svg)](/listings/ussumant--llm-wiki-compiler)

HTML

<a href="/listings/ussumant--llm-wiki-compiler"><img src="/api/listings/ussumant--llm-wiki-compiler/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repo

git clone https://github.com/ussumant/llm-wiki-compiler.git

Claude Code

# Add as a local marketplace
claude plugin marketplace add /path/to/llm-wiki-compiler

# Install the plugin
claude plugin install llm-wiki-compiler

# Restart Claude Code for hooks to register

For a single Claude session without installing:

claude --plugin-dir /path/to/llm-wiki-compiler/plugin

Codex

This repo includes a Codex plugin manifest at `plugin/.codex-plugin/plugin.json` and local marketplace metadata at `.agents/plugins/marketplace.json`. Add this repository as a local Codex plugin marketplace, then install **LLM Wiki Compiler** from that marketplace.

Codex does not use Claude slash commands. Invoke the same workflows with prompts:

| Workflow | Claude Code | Codex prompt | | --- | --- | --- | | Initialize | `/wiki-init` | "Initialize a wiki for this repo" | | Global setup | `/wiki-global-init` | "Set up my global wiki" | | Capture link | `/wiki-capture URL --context "why it matters"` | "URL — capture this in my wiki" | | Compile | `/wiki-compile` | "Compile changed sources into the wiki" | | Ingest | `/wiki-ingest path/to/file.md` | "Ingest this source into the wiki: path/to/file.md" | | Search | `/wiki-search architecture decisions` | "Search the compiled wiki for architecture decisions" | | Query | `/wiki-query what do we know about retention?` | "Answer from the compiled wiki: what do we know about retention?" | | Lint | `/wiki-lint` | "Lint the compiled wiki" | | Visualize | `/wiki-visualize` | "Launch the wiki knowledge graph" | | Migrate | `/wiki-migrate` | "Show a wiki-first startup migration report" |

The shared session context helper is available at `plugin/hooks/wiki-session-context`. Claude calls it automatically through the `SessionStart` hook; Codex users can ask Codex to read the compiled wiki at session start until Codex hook registration is standardized.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "llm-wiki-compiler",
  3. "owner": {
  4. "name": "Sumant"
  5. },
  6. "plugins": [
  7. {
  8. "name": "llm-wiki-compiler",
  9. "source": "./plugin",
  10. "description": "Compile markdown knowledge files or codebases into a topic-based wiki. Implements Karpathy's LLM Knowledge Base pattern.",
  11. "version": "2.1.0",
  12. "author": {
  13. "name": "Sumant"
  14. }
  15. }
  16. ]
  17. }
README.md · README · 786 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # LLM Wiki Compiler
  2. A Claude Code and Codex-compatible plugin that compiles knowledge into a topic-based wiki — from scattered markdown files **or entire codebases**. Reduce context costs by ~90% and give your agent a synthesized understanding of any project.
  3. **[Documentation](https://saydo-5cd0e3d7.mintlify.app/)**
  4. ### What's New in v2.1
  5. - **Codex-compatible plugin metadata** — install from the same `plugin/` package root
  6. - **Skill-first Codex workflows** — use natural prompts instead of Claude slash commands
  7. - **Shared session context helper** — one wiki context renderer for Claude hooks and Codex guidance
  8. ### What's New in v2.0
  9. - **Codebase mode** — generate wikis from code repositories, not just markdown files
  10. - **Auto-detection** — `/wiki-init` detects whether you're in a codebase or knowledge project
  11. - **Knowledge graph visualization** — interactive canvas-based graph of your wiki
  12. ![Knowledge Graph — Dayflow codebase wiki](assets/knowledge-graph.png)
  13. ![Article panel with coverage badges](assets/knowledge-graph-panel.png)
  14. ## Inspiration
  15. This plugin implements the **LLM Knowledge Base** pattern described by [Andrej Karpathy](https://x.com/karpathy/status/2039805659525644595):
  16. > *"Raw data from a given number of sources is collected, then compiled by an LLM into a .md wiki, then operated on by various CLIs by the LLM to do Q&A and to incrementally enhance the wiki, and all of it viewable in Obsidian. You rarely ever write or edit the wiki manually, it's the domain of the LLM."*
  17. The key insight: instead of re-reading hundreds of raw files every session, have the LLM compile them into topic-based articles once, then query the synthesized wiki. Knowledge compounds instead of fragmenting.
  18. ## What It Does
  19. You have 100+ files across meetings, strategy docs, codebases, and research. Every Claude session re-reads them. This plugin compiles them into topic-based articles that synthesize everything known about each subject — with backlinks to sources.
  20. **Before:** Read 13+ raw files (~3,200 lines) per session
  21. **After:** Read INDEX + 2 topic articles (~330 lines) per session
  22. ![Before and After — LLM Wiki Compiler](assets/before-after.png)
  23. ### How It Works
  24. ```mermaid
  25. flowchart LR
  26. subgraph Sources["📁 Raw Sources (you own)"]
  27. M1["meetings/"]
  28. M2["strategy/"]
  29. M3["research/"]
  30. M4["notes/"]
  31. end
  32. subgraph Commands["⚡ Commands"]
  33. INIT["/wiki-init<br/>samples files<br/>proposes structure"]
  34. CAPTURE["/wiki-capture<br/>link + context"]
  35. COMPILE["/wiki-compile<br/>batch compilation"]
  36. INGEST["/wiki-ingest<br/>single file, interactive"]
  37. SEARCH["/wiki-search<br/>find anything"]
  38. LINT["/wiki-lint<br/>health check"]
  39. end
  40. subgraph Wiki["📖 Compiled Wiki (LLM owns)"]
  41. INDEX["INDEX.md"]
  42. T1["topics/retention.md"]
  43. T2["topics/onboarding.md"]
  44. T3["topics/..."]
  45. C1["concepts/..."]
  46. SCHEMA["schema.md"]
  47. end
  48. Sources -->|"383 files · 13 MB"| COMPILE --> Wiki
  49. Sources -->|"1 link + context"| CAPTURE --> Wiki
  50. Sources -->|"1 file"| INGEST --> Wiki
  51. INIT -->|"creates config +<br/>article structure"| COMPILE
  52. Wiki -->|"13 articles · 161 KB<br/>84% fewer tokens"| LLM["🤖 Your LLM Agent<br/>reads wiki, not raw files"]
  53. LINT -.->|"checks"| Wiki
  54. SEARCH -.->|"searches"| Wiki
  55. ```
  56. ## Install
  57. ### Clone the repo
  58. ```bash
  59. git clone https://github.com/ussumant/llm-wiki-compiler.git
  60. ```
  61. ### Claude Code
  62. ```bash
  63. # Add as a local marketplace
  64. claude plugin marketplace add /path/to/llm-wiki-compiler
  65. # Install the plugin
  66. claude plugin install llm-wiki-compiler
  67. # Restart Claude Code for hooks to register
  68. ```
  69. For a single Claude session without installing:
  70. ```bash
  71. claude --plugin-dir /path/to/llm-wiki-compiler/plugin
  72. ```
  73. ### Codex
  74. This repo includes a Codex plugin manifest at `plugin/.codex-plugin/plugin.json` and local marketplace metadata at `.agents/plugins/marketplace.json`. Add this repository as a local Codex plugin marketplace, then install **LLM Wiki Compiler** from that marketplace.
  75. Codex does not use Claude slash commands. Invoke the same workflows with prompts:
  76. | Workflow | Claude Code | Codex prompt |
  77. | --- | --- | --- |
  78. | Initialize | `/wiki-init` | "Initialize a wiki for this repo" |
  79. | Global setup | `/wiki-global-init` | "Set up my global wiki" |
  80. | Capture link | `/wiki-capture URL --context "why it matters"` | "URL — capture this in my wiki" |
  81. | Compile | `/wiki-compile` | "Compile changed sources into the wiki" |
  82. | Ingest | `/wiki-ingest path/to/file.md` | "Ingest this source into the wiki: path/to/file.md" |
  83. | Search | `/wiki-search architecture decisions` | "Search the compiled wiki for architecture decisions" |
  84. | Query | `/wiki-query what do we know about retention?` | "Answer from the compiled wiki: what do we know about retention?" |
  85. | Lint | `/wiki-lint` | "Lint the compiled wiki" |
  86. | Visualize | `/wiki-visualize` | "Launch the wiki knowledge graph" |
  87. | Migrate | `/wiki-migrate` | "Show a wiki-first startup migration report" |
  88. The shared session context helper is available at `plugin/hooks/wiki-session-context`. Claude calls it automatically through the `SessionStart` hook; Codex users can ask Codex to read the compiled wiki at session start until Codex hook registration is standardized.
  89. ## Quick Start
  90. ### Claude Code
  91. ```bash
  92. # 1. Initialize — auto-detects whether this is a codebase or knowledge project,
  93. # samples your files, proposes a domain-specific article structure
  94. /wiki-init
  95. # 2. Compile — reads all sources, creates topic articles (5-10 min first run)
  96. /wiki-compile
  97. # 3. Visualize — launch an interactive knowledge graph of your wiki
  98. /wiki-visualize
  99. # 4. Browse in Obsidian — open wiki/INDEX.md to see all topics with backlinks
  100. ```
  101. After setup, Claude reads wiki articles automatically at session start — no special commands needed. The wiki updates incrementally when sources change.
  102. > **No plugin? Different agent?** You can compile a wiki with **any** LLM agent (Codex, Cursor, Gemini, a plugin-less Claude) using a single self-contained, project-agnostic protocol file. Deploy it with `deploy-protocol.ps1` and point the agent at it — no skill or template files required. See **[EXPORTING.md](EXPORTING.md)**.
  103. ### Codex
  104. Ask Codex:
  105. ```text
  106. Initialize a wiki for this repo
  107. https://example.com/article — capture this in my wiki
  108. Compile changed sources into the wiki
  109. Launch the wiki knowledge graph
  110. ```
  111. For ongoing sessions, ask Codex to start with `wiki/INDEX.md`, then read relevant topic articles before raw sources.
  112. ## Global and Local Wikis
  113. LLM Wiki Compiler supports two layers:
  114. | Layer | Default location | Use it for |
  115. | --- | --- | --- |
  116. | Global wiki | `~/Knowledge` | Cross-project links, ideas, research, videos, bookmarks, and reusable patterns |
  117. | Local wiki | Current repo/folder with `.wiki-compiler.json` | Deep project-specific architecture, decisions, source files, and operating knowledge |
  118. The default global folder is:
  119. ```text
  120. ~/Knowledge
  121. ```
  122. You can override it:
  123. ```bash
  124. export LLM_WIKI_GLOBAL_DIR="$HOME/CompanyKnowledge"
  125. ```
  126. Routing defaults:
  127. - "capture this in my wiki" → global wiki
  128. - "capture this in this repo/project wiki" → local wiki
  129. - "capture this in both" → global and local
  130. - no global wiki yet → initialize `~/Knowledge` automatically from the global wiki template
  131. Set it up explicitly with:
  132. ```text
  133. Set up my global wiki
  134. ```
  135. ## Codebase Mode (New in v2.0)
  136. Generate a wiki from a code repository — not just markdown files, but the full knowledge embedded in your codebase: architecture, API contracts, decision records, deployment configs, and gotchas.
  137. ### Quick Start
  138. ```bash
  139. # One command to set up and compile
  140. /wiki-init --codebase
  141. ```
  142. The compiler auto-detects your project type, discovers modules/services, finds knowledge files (READMEs, ADRs, API specs, Docker configs), and compiles everything into topic articles.
  143. ### What It Scans
  144. | File Type | Examples | What It Captures |
  145. |-----------|----------|-----------------|
  146. | Documentation | `README.md`, `CLAUDE.md`, `ARCHITECTURE.md` | Purpose, architecture, conventions |
  147. | API contracts | `*.proto`, `*.graphql`, `openapi.yaml` | API surface, inter-service communication |
  148. | Decision records | `ADR-*.md`, `docs/adr/*.md` | Key decisions and rationale |
  149. | Infrastructure | `docker-compose.yml`, `Dockerfile`, `k8s/*.yaml` | Deployment topology, scaling |
  150. | Operations | `docs/runbooks/*.md`, `CHANGELOG.md` | Gotchas, failure modes, version history |
  151. | Config shape | `.env.example`, `package.json` | Environment requirements, dependencies |
  152. With `deep_scan: true`, it also reads entry points, type definitions, and route files for richer articles.
  153. ### Example Output
  154. ```markdown
  155. # auth-service
  156. ## Purpose [coverage: high -- 8 sources]
  157. Handles user authentication and session management via JWT tokens.
  158. All other services call auth-service to validate requests.
  159. ## Talks To [coverage: high -- 6 sources]
  160. - **user-service** (REST: /api/users/:id) -- subscription status lookup
  161. - **notification-service** (SQS: auth.password-reset) -- triggers email
  162. - **billing-service** (gRPC) -- validates payment status before premium access
  163. ## Key Decisions [coverage: medium -- 3 sources]
  164. - **JWT over sessions** -- stateless scaling, no shared session store (ADR-003)
  165. - **Refresh token rotation** -- security requirement from compliance audit
  166. ## Gotchas [coverage: high -- 5 sources]
  167. - Token expiry is 15 minutes, not 1 hour (changed in v2.3)
  168. - Rate limiting on /auth/login is per-IP, not per-user
  169. ```
  170. ### How It Differs from Google Code Wiki / DeepWiki
  171. Those tools answer "what does this code do?" by parsing functions and generating API docs.
  172. This tool answers **"what does this project *know*?"** by synthesizing documentation, decision records, deployment configs, and operational knowledge into articles an agent can navigate.
  173. | | Google Code Wiki / DeepWiki | LLM Wiki Compiler |
  174. |---|---|---|
  175. | Input | Source code (AST parsing) | Knowledge files + optional code |
  176. | Output | API docs + architecture diagrams | Synthesized topic articles with coverage indicators |
  177. | Infrastructure | Hosted platform / server + embeddings | Zero infra — Claude Code plugin |
  178. | Updates | Full regen on every commit | Incremental — only changed topics |
  179. | Consumer | Developers reading docs | Your AI agent (and you) |
  180. ### Monorepo / Microservice Support
  181. For monorepos, the compiler detects service boundaries by looking for directories with their own manifest files (`package.json`, `go.mod`, etc.). Each service becomes a topic article. Cross-cutting concerns (infrastructure, testing, deployment) get their own articles.
  182. ```
  183. 📚 Wiki compiled — 8 topics from 47 files
  184. Topics created:
  185. ├── auth-service (12 sources)
  186. ├── billing-service (9 sources)
  187. ├── notification-service (6 sources)
  188. ├── api-gateway (5 sources)
  189. ├── infrastructure (4 sources)
  190. ├── testing (3 sources)
  191. └── deployment (3 sources)
  192. Concepts discovered:
  193. ├── error-handling-strategy — shared pattern across 4 services
  194. └── auth-flow — touches auth, gateway, billing
  195. ```
  196. ### Codebase Configuration
  197. ```json
  198. {
  199. "version": 2,
  200. "mode": "codebase",
  201. "name": "My Project",
  202. "sources": [{ "path": "./", "exclude": ["node_modules/", "dist/", ".git/", "wiki/"] }],
  203. "output": "wiki/",
  204. "service_discovery": "auto",
  205. "deep_scan": false,
  206. "knowledge_files": ["README.md", "CLAUDE.md", "*.proto", "openapi.*", "ADR-*.md", "Dockerfile"]
  207. }
  208. ```
  209. | Field | Description |
  210. |-------|-------------|
  211. | `mode` | `"codebase"` enables code-aware topic discovery |
  212. | `service_discovery` | `"auto"` detects monorepo vs single project |
  213. | `deep_scan` | `true` to also read source code files for richer articles |
  214. | `knowledge_files` | Glob patterns for priority documentation files |
  215. ## Knowledge Graph Visualization
  216. See your compiled wiki as an interactive knowledge graph. Topics appear as nodes sized by source count, concepts as connecting edges.
  217. ```bash
  218. /wiki-visualize
  219. ```
  220. - **Hover** nodes to see source count and highlight connections
  221. - **Click** a node to read the full article in a side panel with coverage badges
  222. - **Shift-click** a node to expand its neighborhood — concept-connected topics light up, others dim. Shift-click again to keep walking the graph (depth 2, depth 3, …). The HUD shows how many nodes and seeds are currently lit.
  223. - **Hover edges** to see concept names linking topics
  224. - **Search** to filter topics by name or alias
  225. - **Escape** to close the article panel or clear the expansion
  226. Canvas-based, zero dependencies, Nothing Design System tokens (Space Grotesk + Space Mono typography). Works with both knowledge mode and codebase mode wikis.
  227. You can also run it manually without the plugin:
  228. ```bash
  229. node plugin/visualize/server.js --wiki-dir path/to/wiki/
  230. # Open http://localhost:3848
  231. ```
  232. ## Fetch from External Sources
  233. Your context isn't always on disk — a lot of it lives in services like X bookmarks, Readwise highlights, or Pocket saves. `/fetch-bookmarks <source>` pulls that content into a local directory that `/wiki-compile` can consume alongside your regular sources.
  234. Optional — skip it entirely if all your sources are already local markdown.
  235. ### Quick Start
  236. ```bash
  237. /fetch-bookmarks x
  238. ```
  239. First run walks you through:
  240. 1. Checking that Node.js 20+ is installed
  241. 2. Installing [Field Theory CLI](https://github.com/afar1/fieldtheory-cli) (MIT-licensed, free) globally via npm — one consent prompt
  242. 3. Syncing your X bookmarks using Chrome cookie auth (no X API key needed)
  243. 4. Adding `~/.ft-bookmarks/md/` to your `.wiki-compiler.json` sources
  244. After that, `/fetch-bookmarks x` just resyncs. Run `/wiki-compile` whenever you want bookmarks folded into topic articles.
  245. ### Auto-Sync (Set and Forget)
  246. Manual syncing gets forgotten. Install a daily background job:
  247. ```bash
  248. /fetch-bookmarks schedule x
  249. ```
  250. On macOS this writes a `launchd` plist to `~/Library/LaunchAgents/dev.llm-wiki-compiler.x-sync.plist` that runs `ft sync && ft md` daily at 03:00 local. No LLM tokens, no Claude Code needed — pure shell. On Linux/WSL you get a `crontab` snippet to paste.
  251. The `/wiki-compile` step stays manual by design — it needs an LLM and your judgment. When you next open Claude Code in a wiki project, the session-start hook tells you how many new bookmarks have arrived since the last compile, so your intent translates to action without you having to track dates.
  252. Uninstall with `/fetch-bookmarks schedule x --uninstall` (or `launchctl unload` manually).
  253. ### Available Sources
  254. | Source | Status | Backend |
  255. |--------|--------|---------|
  256. | `x` | Shipped | [Field Theory CLI](https://github.com/afar1/fieldtheory-cli) (MIT) |
  257. | `readwise` | Planned | TBD |
  258. | `pocket` | Planned | TBD |
  259. | `github-stars` | Planned | TBD |
  260. ### How It Works
  261. `/fetch-bookmarks` is a thin dispatcher. Each source has its own adapter at `plugin/skills/wiki-compiler/adapters/<source>.md` that handles dependency checks, auth, sync, and wiring the output directory into your wiki config. Adapters delegate to existing open-source tools rather than reimplementing fetch logic — so you get a stable plugin surface (`/fetch-bookmarks x`) while the heavy lifting is maintained upstream.
  262. ### Requirements
  263. - **Node.js 20+** (for Field Theory CLI)
  264. - **Chrome** (for first-time X cookie sync — this is a Field Theory CLI limitation)
  265. ### Contributing a New Adapter
  266. Copy `plugin/skills/wiki-compiler/adapters/x.md` and follow the contract documented in `plugin/commands/fetch-bookmarks.md`: preflight, consent, sync, markdown output, wire into `sources[]`, suggest compile.
  267. ## Capture Links With Context
  268. The primary UX is: paste a link and say **"capture this in my wiki."** You do not need to remember command names.
  269. In Codex:
  270. ```text
  271. https://example.com/article
  272. capture this in my wiki
  273. ```
  274. Add context when you have it:
  275. ```text
  276. https://example.com/article
  277. capture this in my wiki
  278. Context: Relevant to Codex plugin onboarding and skill discovery.
  279. ```
  280. Claude Code users can use the explicit command form:
  281. ```bash
  282. /wiki-capture https://example.com/article --context "Relevant to Codex plugin onboarding and skill discovery"
  283. ```
  284. The capture flow is adapter-based:
  285. | Source | Adapter | What gets saved |
  286. |--------|---------|-----------------|
  287. | Web article | `capture-web` | readable page text, metadata, relevance notes |
  288. | YouTube | `capture-youtube` | transcript evidence, timestamps, workflow notes when relevant |
  289. | X/Twitter link | `capture-x` | post/thread text or bookmark source, date-aware relevance notes |
  290. Captured links are written to `wiki-sources/captures/` inside the target wiki as markdown with frontmatter, the original URL, captured date, user context, extracted content, relevance notes, and candidate wiki connections. The wiki then uses the same ingest/compile logic to update existing topics or propose a new topic/concept.
  291. ### Connector Roadmap
  292. The capture system is intentionally adapter-based. Future connectors should feed durable, provenance-rich source markdown into the same compiler pipeline instead of writing topic articles directly.
  293. Planned connector shape:
  294. ```text
  295. connector pulls context
  296. → normalizes to markdown with metadata
  297. → writes to wiki-sources/{connector}/
  298. → adds that folder to sources[]
  299. → wiki compile builds topic/concept connections
  300. ```
  301. Candidate connectors:
  302. | Connector | Use case |
  303. |-----------|----------|
  304. | Granola | Meeting notes, summaries, decisions, and follow-ups |
  305. | Google Drive / Docs | Docs, strategy notes, specs, and research folders |
  306. | Slack | High-signal threads, decisions, and customer/team context |
  307. | Linear / GitHub Issues | Roadmap, bugs, project decisions, and implementation context |
  308. | Readwise / Pocket | Reading highlights and saved articles |
  309. The key rule: connectors create source material; the wiki compiler owns synthesis and connections.
  310. ## How It Works (Knowledge Mode)
  311. ### Commands
  312. | Command | Purpose |
  313. |---------|---------|
  314. | `/wiki-init` | One-time setup -- auto-detects markdown directories, samples files, proposes custom article structure |
  315. | `/wiki-global-init` | Initialize the default global wiki at `~/Knowledge` or `LLM_WIKI_GLOBAL_DIR` |
  316. | `/wiki-compile` | Compiles source files into topic articles (incremental -- only recompiles changes). Generates `schema.md` on first run. |
  317. | `/wiki-capture` | Capture a URL plus context, normalize it into markdown, and connect it to existing topics/concepts |
  318. | `/wiki-ingest` | Add a single source interactively -- read, discuss key takeaways, update relevant wiki articles |
  319. | `/fetch-bookmarks` | Pull bookmarks from external services (X today; Readwise, Pocket planned). `schedule <source>` wires a daily launchd job. |
  320. | `/wiki-search` | Search across wiki articles by keyword or phrase |
  321. | `/wiki-lint` | Health checks -- finds stale articles, orphan pages, missing cross-references, contradictions, low coverage |
  322. | `/wiki-query` | Optional -- Q&A against the wiki. Can file useful answers back into wiki articles. |
  323. | `/wiki-migrate` | One-time migration -- analyzes your AGENTS.md startup reads, shows which are covered by wiki, generates replacement |
  324. | `/wiki-visualize` | Launch interactive knowledge graph of your compiled wiki |
  325. | `/wiki-upgrade` | Update the plugin to the latest version from GitHub |
  326. The primary workflow is: **init → compile → add to AGENTS.md → done.** After that, Claude reads the wiki automatically. `/wiki-query` is a convenience for testing or quick lookups.
  327. ### Staged Adoption (The Key Feature)
  328. The plugin never modifies your existing CLAUDE.md or AGENTS.md. Instead, it injects context via a SessionStart hook with three modes:
  329. | Mode | What Happens | Your Existing Setup |
  330. |------|-------------|-------------------|
  331. | **staging** (default) | "Wiki available — check it when you need depth" | Completely unchanged |
  332. | **recommended** | "Check wiki articles before raw files" | Unchanged, but Claude prioritizes wiki |
  333. | **primary** | "Wiki is your primary knowledge source" | You can optionally simplify startup reads |
  334. Change mode by editing `.wiki-compiler.json`:
  335. ```json
  336. { "mode": "staging" } → { "mode": "recommended" } → { "mode": "primary" }
  337. ```
  338. ### What Gets Compiled
  339. During `/wiki-init`, the compiler samples your source files and proposes an article structure that fits your domain. You approve (or tweak) the sections before anything gets compiled.
  340. For example, a product team's wiki might get:
  341. - **Summary** — **Timeline** — **Current State** — **Key Decisions** — **Experiments & Results** — **Gotchas** — **Open Questions** — **Sources**
  342. While a research wiki might get:
  343. - **Summary** — **Key Findings** — **Methodology** — **Evidence** — **Gaps & Contradictions** — **Open Questions** — **Sources**
  344. And a book notes wiki might get:
  345. - **Summary** — **Characters** — **Themes** — **Plot Threads** — **Connections** — **Quotes** — **Sources**
  346. The structure is saved in `.wiki-compiler.json` and can be edited anytime. **Summary** and **Sources** are always included.
  347. ### Coverage Indicators (Best of Both Worlds)
  348. Every section includes a coverage tag so you (or your AI agent) know when to trust the wiki vs when to read raw sources:
  349. ```markdown
  350. ## Summary [coverage: high -- 15 sources]
  351. ...trust this, it's well-sourced...
  352. ## Experiments & Results [coverage: medium -- 3 sources]
  353. ...decent overview, check raw files for details...
  354. ## Gotchas [coverage: low -- 1 source]
  355. ...read the raw gotchas.md directly...
  356. ```
  357. - **high** (5+ sources) — trust the wiki section directly
  358. - **medium** (2-4 sources) — good overview, check raw sources for granular questions
  359. - **low** (0-1 sources) — read the raw sources listed in that section
  360. This gives you the speed of the wiki (84% fewer tokens) without sacrificing accuracy. Your agent reads the wiki first, and only falls back to raw files for low-coverage sections.
  361. ### Time-Decay Awareness
  362. Tweets from 2022 and tweets from 2026 don't carry equal weight on questions about AI tooling or UI patterns — so the compiler doesn't treat them as equal either. For **time-sensitive topics** (AI, design, growth tactics, bookmark-heavy topics), the compiler:
  363. - Extracts a source date from each input (frontmatter `posted_at` / `date`, filename date, or mtime)
  364. - Orders Timeline and Key Decisions bullets newest-first, date-prefixed
  365. - Flags claims older than 18 months with ⚠️
  366. - Adds `[as of YYYY-MM]` tags to sections resting mostly on aging sources
  367. - In conflicts, prefers the newer source and notes the shift
  368. Stable topics (career, personal growth, visa work) use looser thresholds (24/48 months). Nothing gets deleted — stale entries stay for historical context, just clearly marked.
  369. ### Obsidian Compatible
  370. The wiki output is plain markdown with Obsidian-style `[[wikilinks]]`. Open `wiki/INDEX.md` in Obsidian and you'll see the full knowledge base with bidirectional links to source files.
  371. ### Concept Articles (Cross-Cutting Patterns)
  372. After compiling topic articles, the compiler looks for patterns that span 3+ topics and generates **concept articles** in `wiki/concepts/`. These are interpretive, not just factual -- they answer "what does this pattern mean?" not just "what happened?"
  373. Examples from a real project:
  374. - **"Speed vs Quality Tradeoff"** -- 6 instances where this decision appeared across retention, push notifications, and experiment design
  375. - **"Cross-Team Decision Patterns"** -- communication patterns and decision dynamics synthesized from 24 meetings
  376. - **"Evolution of Retention Thinking"** -- how the approach changed from Oct 2025 to Apr 2026 across analytics, strategy, and experiments
  377. Concept articles are discovered automatically during compilation. You can also seed them in `schema.md` if you know what patterns you want tracked.
  378. ### Schema Document
  379. On first compile, a `schema.md` is generated in your wiki output directory. It defines your wiki's structure: topic list, naming conventions, article format, and cross-reference rules.
  380. You can edit `schema.md` to rename topics, merge them, or add conventions. The compiler reads it before each run and respects your changes. New topics get added automatically with an evolution log entry.
  381. ### Wiki Lint
  382. Run `/wiki-lint` to check wiki health:
  383. - **Stale articles** -- sources changed since last compile
  384. - **Orphan pages** -- articles with deleted/missing sources
  385. - **Missing cross-references** -- topics sharing 3+ sources that don't link to each other
  386. - **Low coverage sections** -- `[coverage: low]` tags flagged for improvement
  387. - **Contradictions** -- conflicting facts across articles (e.g., different dates for same event)
  388. - **Schema drift** -- topics in wiki/ not listed in schema.md, or vice versa
  389. ### Query Filing
  390. When `/wiki-query` produces a useful synthesis that connects information across topics, it offers to file the answer back into the relevant wiki article. Your explorations compound in the knowledge base instead of disappearing with the session.
  391. ## Configuration
  392. `.wiki-compiler.json` (created by `/wiki-init`):
  393. ```json
  394. {
  395. "version": 2,
  396. "name": "My Project",
  397. "mode": "staging",
  398. "sources": [
  399. { "path": "Knowledge/", "exclude": ["wiki/"] },
  400. { "path": "docs/meetings/" }
  401. ],
  402. "output": "Knowledge/wiki/",
  403. "topic_hints": ["retention", "onboarding"],
  404. "link_style": "obsidian"
  405. }
  406. ```
  407. | Field | Description |
  408. |-------|-------------|
  409. | `version` | Config version (`2` for latest) |
  410. | `name` | Display name for the knowledge base |
  411. | `mode` | Integration mode: `staging` / `recommended` / `primary` — OR `codebase` for code repositories |
  412. | `sources` | Directories to scan |
  413. | `output` | Where compiled wiki lives |
  414. | `article_sections` | Article structure — generated during `/wiki-init` based on your content (see below) |
  415. | `topic_hints` | Optional seed topics to guide classification |
  416. | `link_style` | `obsidian` (wikilinks) or `markdown` (standard links) |
  417. | `service_discovery` | (codebase mode) `auto` or `manual` — how to detect modules/services |
  418. | `knowledge_files` | (codebase mode) Glob patterns for priority documentation files |
  419. | `deep_scan` | (codebase mode) `true` to also read source code files |
  420. ### Custom Article Structure
  421. The `article_sections` array defines what sections appear in each topic article. It's generated during `/wiki-init` by sampling your source files — the compiler proposes sections that fit your domain, and you approve or tweak them.
  422. ```json
  423. "article_sections": [
  424. { "name": "Summary", "description": "standalone briefing of the topic", "required": true },
  425. { "name": "Key Findings", "description": "main discoveries and insights" },
  426. { "name": "Methodology", "description": "approaches and methods used" },
  427. { "name": "Open Questions", "description": "unresolved threads and gaps" },
  428. { "name": "Sources", "description": "backlinks to all contributing files", "required": true }
  429. ]
  430. ```
  431. You can edit this array anytime — add, remove, or rename sections. The compiler will use your updated structure on the next `/wiki-compile` run. `Summary` and `Sources` are required and cannot be removed.
  432. If `article_sections` is missing (older configs), the compiler falls back to a default template.
  433. ## Safety Guarantees
  434. - Source files are **never modified** — the compiler only writes to the output directory
  435. - The wiki can be **deleted and regenerated** at any time from source files
  436. - Your **CLAUDE.md and AGENTS.md are never touched** — context injection happens via hooks
  437. - **Rollback anytime** — change mode back to `staging` or delete `.wiki-compiler.json`
  438. ## Cost Savings (Real Data)
  439. Tested on a real project with 1,183 markdown files across meetings, strategy docs, session histories, and research notes.
  440. ### Token Reduction
  441. | | Without Wiki | With Wiki |
  442. |---|---|---|
  443. | Session startup context | ~79K tokens (13 files) | ~8.5K tokens (INDEX + 2-3 articles) |
  444. | Per-question research | ~8,000 tokens (10+ files) | ~600 tokens (1 article) |
  445. | **Reduction** | — | **89%** |
  446. ### Compilation Costs
  447. | | Tokens | Cost (Opus) | Cost (Sonnet) |
  448. |---|---|---|---|
  449. | First compilation | ~880K | ~$13 | ~$2.60 |
  450. | Daily incremental | ~100K | ~$1.50 | ~$0.30 |
  451. | **Break-even** | — | **First session** | **First session** |
  452. ### Accuracy
  453. We spot-checked wiki articles against their raw source files:
  454. - **10/10 key facts accurately synthesized** -- no fabrication, no missing critical details
  455. - **Coverage indicators are honest** -- sections marked `[coverage: high]` had 5+ contributing sources
  456. - **Trade-off is transparent** -- wiki captures ~90% of raw file content; coverage tags tell you when to fall back to raw sources for the remaining 10%
  457. ### Compression
  458. - 1,183 files → 14 topic articles -- **84x compression**
  459. - Session startup: 13 file reads → 1 INDEX + 2-3 topic articles -- **89% fewer tokens**
  460. - ~$1.05 saved per session at Opus pricing ($15/M input tokens)
  461. ## Integrating with AGENTS.md (Recommended)
  462. This is the main way to use the wiki long-term. After you've compiled and spot-checked the output, add this to your project's AGENTS.md or CLAUDE.md:
  463. ```markdown
  464. ## Knowledge Base
  465. A compiled knowledge wiki is available at `{your output path}/`.
  466. **Session startup:** Read `wiki/INDEX.md` for a topic overview, then read
  467. specific topic articles relevant to your current task.
  468. **Using coverage indicators:** Each section has a coverage tag:
  469. - `[coverage: high]` -- trust this section, skip the raw files.
  470. - `[coverage: medium]` -- good overview, check raw sources for granular questions.
  471. - `[coverage: low]` -- read the raw sources listed in that section directly.
  472. **When you need depth:** Check the article's Sources section for links to
  473. raw files. Only read raw sources for medium/low coverage sections or when
  474. you need very specific detail.
  475. **Never modify wiki files directly** -- they are regenerated by `/wiki-compile`.
  476. ```
  477. Once this is in your AGENTS.md, Claude automatically uses the wiki every session with smart fallback. High-coverage sections save tokens. Low-coverage sections point Claude to the exact raw files it needs.
  478. **When to add this:** After running `/wiki-compile` at least once and validating that the topic articles accurately reflect your knowledge.
  479. ## Advanced
  480. ### Incremental Compilation
  481. After the first full compile, `/wiki-compile` only recompiles topics whose source files changed. INDEX.md is always regenerated.
  482. ### Force Full Recompile
  483. ```
  484. /wiki-compile --full
  485. ```
  486. ### Compile Single Topic
  487. ```
  488. /wiki-compile --topic retention
  489. ```
  490. ### Interactive Ingest
  491. Add sources one at a time with `/wiki-ingest`:
  492. ```
  493. /wiki-ingest path/to/new-meeting-notes.md
  494. ```
  495. The compiler reads the file, shows you key takeaways, asks what to emphasize, then updates all relevant topic articles. A single source might touch multiple topics — the compiler handles the cross-referencing.
  496. This is Karpathy's recommended workflow for staying involved with your knowledge base as it grows. Use `/wiki-compile` for batch processing, `/wiki-ingest` for interactive single-source additions.
  497. ### Wiki Search
  498. Search your compiled wiki:
  499. ```
  500. /wiki-search retention experiments
  501. ```
  502. Searches topic names first (fast), then full article content if needed. Results include coverage indicators so you know when to trust the wiki vs read raw sources.
  503. For synthesis questions that require connecting multiple topics, use `/wiki-query` instead.
  504. For large wikis (100+ topics), consider adding [qmd](https://github.com/jina-ai/qmd) as an MCP server for hybrid BM25/vector search with LLM re-ranking.
  505. ### Migrate to Wiki-First Startup
  506. Once your wiki is compiled and spot-checked, run `/wiki-migrate` to switch your AGENTS.md from reading raw files to reading the wiki:
  507. ```
  508. /wiki-migrate
  509. Wiki Migration Report for "My Project"
  510. Current startup: 13 file reads
  511. ✅ gotchas.md → covered by analytics [coverage: high]
  512. ✅ product-context.md → covered by product [coverage: high]
  513. ⚠️ reporting-backlog.md → partially covered [coverage: medium]
  514. ❌ acceptance-criteria.md → not covered (operational checklist)
  515. Summary: 10/13 reads can be replaced
  516. Estimated savings: ~79K → ~8.5K tokens (89% reduction)
  517. ```
  518. The command generates a replacement startup section and applies it with your confirmation.
  519. ### Stale Wiki Detection
  520. The plugin automatically detects when source files have changed since the last compile. Enable it in `.wiki-compiler.json`:
  521. ```json
  522. { "auto_update": "prompt" }
  523. ```
  524. With `prompt` mode, the SessionStart hook counts changed files and warns:
  525. > "Wiki may be stale — 42 files changed since last compile (2026-04-06). Run /wiki-compile to update."
  526. Set to `"off"` (default) to disable.
  527. ### Scheduled Compilation
  528. Use Claude Code's `/schedule` to set up daily automatic compilation.
  529. ### Updating the Plugin
  530. From inside Claude Code:
  531. ```
  532. /wiki-upgrade
  533. ```
  534. This pulls the latest version from GitHub and shows what changed. Restart Claude Code after to load new commands and hooks.
  535. If `/wiki-upgrade` isn't available yet (older version), update manually:
  536. ```bash
  537. cd /path/to/llm-wiki-compiler && git pull
  538. claude plugin update llm-wiki-compiler
  539. # Then restart Claude Code
  540. ```
  541. ## License
  542. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.