{
"markdown": "# LLM Wiki Compiler\n\nA 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.\n\n**[Documentation](https://saydo-5cd0e3d7.mintlify.app/)**\n\n### What's New in v2.1\n\n- **Codex-compatible plugin metadata** — install from the same `plugin/` package root\n- **Skill-first Codex workflows** — use natural prompts instead of Claude slash commands\n- **Shared session context helper** — one wiki context renderer for Claude hooks and Codex guidance\n\n### What's New in v2.0\n\n- **Codebase mode** — generate wikis from code repositories, not just markdown files\n- **Auto-detection** — `/wiki-init` detects whether you're in a codebase or knowledge project\n- **Knowledge graph visualization** — interactive canvas-based graph of your wiki\n\n\n\n\n\n## Inspiration\n\nThis plugin implements the **LLM Knowledge Base** pattern described by [Andrej Karpathy](https://x.com/karpathy/status/2039805659525644595):\n\n> *\"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.\"*\n\nThe 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.\n\n## What It Does\n\nYou 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.\n\n**Before:** Read 13+ raw files (~3,200 lines) per session\n**After:** Read INDEX + 2 topic articles (~330 lines) per session\n\n\n\n### How It Works\n\n```mermaid\nflowchart LR\n subgraph Sources[\"📁 Raw Sources (you own)\"]\n M1[\"meetings/\"]\n M2[\"strategy/\"]\n M3[\"research/\"]\n M4[\"notes/\"]\n end\n\n subgraph Commands[\"⚡ Commands\"]\n INIT[\"/wiki-init samples files proposes structure\"]\n CAPTURE[\"/wiki-capture link + context\"]\n COMPILE[\"/wiki-compile batch compilation\"]\n INGEST[\"/wiki-ingest single file, interactive\"]\n SEARCH[\"/wiki-search find anything\"]\n LINT[\"/wiki-lint health check\"]\n end\n\n subgraph Wiki[\"📖 Compiled Wiki (LLM owns)\"]\n INDEX[\"INDEX.md\"]\n T1[\"topics/retention.md\"]\n T2[\"topics/onboarding.md\"]\n T3[\"topics/...\"]\n C1[\"concepts/...\"]\n SCHEMA[\"schema.md\"]\n end\n\n Sources -->|\"383 files · 13 MB\"| COMPILE --> Wiki\n Sources -->|\"1 link + context\"| CAPTURE --> Wiki\n Sources -->|\"1 file\"| INGEST --> Wiki\n INIT -->|\"creates config + article structure\"| COMPILE\n Wiki -->|\"13 articles · 161 KB 84% fewer tokens\"| LLM[\"🤖 Your LLM Agent reads wiki, not raw files\"]\n LINT -.->|\"checks\"| Wiki\n SEARCH -.->|\"searches\"| Wiki\n```\n\n## Install\n\n### Clone the repo\n\n```bash\ngit clone https://github.com/ussumant/llm-wiki-compiler.git\n```\n\n### Claude Code\n\n```bash\n# Add as a local marketplace\nclaude plugin marketplace add /path/to/llm-wiki-compiler\n\n# Install the plugin\nclaude plugin install llm-wiki-compiler\n\n# Restart Claude Code for hooks to register\n```\n\nFor a single Claude session without installing:\n\n```bash\nclaude --plugin-dir /path/to/llm-wiki-compiler/plugin\n```\n\n### Codex\n\nThis 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.\n\nCodex does not use Claude slash commands. Invoke the same workflows with prompts:\n\n| Workflow | Claude Code | Codex prompt |\n| --- | --- | --- |\n| Initialize | `/wiki-init` | \"Initialize a wiki for this repo\" |\n| Global setup | `/wiki-global-init` | \"Set up my global wiki\" |\n| Capture link | `/wiki-capture URL --context \"why it matters\"` | \"URL — capture this in my wiki\" |\n| Compile | `/wiki-compile` | \"Compile changed sources into the wiki\" |\n| Ingest | `/wiki-ingest path/to/file.md` | \"Ingest this source into the wiki: path/to/file.md\" |\n| Search | `/wiki-search architecture decisions` | \"Search the compiled wiki for architecture decisions\" |\n| Query | `/wiki-query what do we know about retention?` | \"Answer from the compiled wiki: what do we know about retention?\" |\n| Lint | `/wiki-lint` | \"Lint the compiled wiki\" |\n| Visualize | `/wiki-visualize` | \"Launch the wiki knowledge graph\" |\n| Migrate | `/wiki-migrate` | \"Show a wiki-first startup migration report\" |\n\nThe 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.\n\n## Quick Start\n\n### Claude Code\n\n```bash\n# 1. Initialize — auto-detects whether this is a codebase or knowledge project,\n# samples your files, proposes a domain-specific article structure\n/wiki-init\n\n# 2. Compile — reads all sources, creates topic articles (5-10 min first run)\n/wiki-compile\n\n# 3. Visualize — launch an interactive knowledge graph of your wiki\n/wiki-visualize\n\n# 4. Browse in Obsidian — open wiki/INDEX.md to see all topics with backlinks\n```\n\nAfter setup, Claude reads wiki articles automatically at session start — no special commands needed. The wiki updates incrementally when sources change.\n\n> **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)**.\n\n### Codex\n\nAsk Codex:\n\n```text\nInitialize a wiki for this repo\nhttps://example.com/article — capture this in my wiki\nCompile changed sources into the wiki\nLaunch the wiki knowledge graph\n```\n\nFor ongoing sessions, ask Codex to start with `wiki/INDEX.md`, then read relevant topic articles before raw sources.\n\n## Global and Local Wikis\n\nLLM Wiki Compiler supports two layers:\n\n| Layer | Default location | Use it for |\n| --- | --- | --- |\n| Global wiki | `~/Knowledge` | Cross-project links, ideas, research, videos, bookmarks, and reusable patterns |\n| Local wiki | Current repo/folder with `.wiki-compiler.json` | Deep project-specific architecture, decisions, source files, and operating knowledge |\n\nThe default global folder is:\n\n```text\n~/Knowledge\n```\n\nYou can override it:\n\n```bash\nexport LLM_WIKI_GLOBAL_DIR=\"$HOME/CompanyKnowledge\"\n```\n\nRouting defaults:\n\n- \"capture this in my wiki\" → global wiki\n- \"capture this in this repo/project wiki\" → local wiki\n- \"capture this in both\" → global and local\n- no global wiki yet → initialize `~/Knowledge` automatically from the global wiki template\n\nSet it up explicitly with:\n\n```text\nSet up my global wiki\n```\n\n## Codebase Mode (New in v2.0)\n\nGenerate 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.\n\n### Quick Start\n\n```bash\n# One command to set up and compile\n/wiki-init --codebase\n```\n\nThe compiler auto-detects your project type, discovers modules/services, finds knowledge files (READMEs, ADRs, API specs, Docker configs), and compiles everything into topic articles.\n\n### What It Scans\n\n| File Type | Examples | What It Captures |\n|-----------|----------|-----------------|\n| Documentation | `README.md`, `CLAUDE.md`, `ARCHITECTURE.md` | Purpose, architecture, conventions |\n| API contracts | `*.proto`, `*.graphql`, `openapi.yaml` | API surface, inter-service communication |\n| Decision records | `ADR-*.md`, `docs/adr/*.md` | Key decisions and rationale |\n| Infrastructure | `docker-compose.yml`, `Dockerfile`, `k8s/*.yaml` | Deployment topology, scaling |\n| Operations | `docs/runbooks/*.md`, `CHANGELOG.md` | Gotchas, failure modes, version history |\n| Config shape | `.env.example`, `package.json` | Environment requirements, dependencies |\n\nWith `deep_scan: true`, it also reads entry points, type definitions, and route files for richer articles.\n\n### Example Output\n\n```markdown\n# auth-service\n\n## Purpose [coverage: high -- 8 sources]\nHandles user authentication and session management via JWT tokens.\nAll other services call auth-service to validate requests.\n\n## Talks To [coverage: high -- 6 sources]\n- **user-service** (REST: /api/users/:id) -- subscription status lookup\n- **notification-service** (SQS: auth.password-reset) -- triggers email\n- **billing-service** (gRPC) -- validates payment status before premium access\n\n## Key Decisions [coverage: medium -- 3 sources]\n- **JWT over sessions** -- stateless scaling, no shared session store (ADR-003)\n- **Refresh token rotation** -- security requirement from compliance audit\n\n## Gotchas [coverage: high -- 5 sources]\n- Token expiry is 15 minutes, not 1 hour (changed in v2.3)\n- Rate limiting on /auth/login is per-IP, not per-user\n```\n\n### How It Differs from Google Code Wiki / DeepWiki\n\nThose tools answer \"what does this code do?\" by parsing functions and generating API docs.\n\nThis tool answers **\"what does this project *know*?\"** by synthesizing documentation, decision records, deployment configs, and operational knowledge into articles an agent can navigate.\n\n| | Google Code Wiki / DeepWiki | LLM Wiki Compiler |\n|---|---|---|\n| Input | Source code (AST parsing) | Knowledge files + optional code |\n| Output | API docs + architecture diagrams | Synthesized topic articles with coverage indicators |\n| Infrastructure | Hosted platform / server + embeddings | Zero infra — Claude Code plugin |\n| Updates | Full regen on every commit | Incremental — only changed topics |\n| Consumer | Developers reading docs | Your AI agent (and you) |\n\n### Monorepo / Microservice Support\n\nFor 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.\n\n```\n📚 Wiki compiled — 8 topics from 47 files\n\n Topics created:\n ├── auth-service (12 sources)\n ├── billing-service (9 sources)\n ├── notification-service (6 sources)\n ├── api-gateway (5 sources)\n ├── infrastructure (4 sources)\n ├── testing (3 sources)\n └── deployment (3 sources)\n\n Concepts discovered:\n ├── error-handling-strategy — shared pattern across 4 services\n └── auth-flow — touches auth, gateway, billing\n```\n\n### Codebase Configuration\n\n```json\n{\n \"version\": 2,\n \"mode\": \"codebase\",\n \"name\": \"My Project\",\n \"sources\": [{ \"path\": \"./\", \"exclude\": [\"node_modules/\", \"dist/\", \".git/\", \"wiki/\"] }],\n \"output\": \"wiki/\",\n \"service_discovery\": \"auto\",\n \"deep_scan\": false,\n \"knowledge_files\": [\"README.md\", \"CLAUDE.md\", \"*.proto\", \"openapi.*\", \"ADR-*.md\", \"Dockerfile\"]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `mode` | `\"codebase\"` enables code-aware topic discovery |\n| `service_discovery` | `\"auto\"` detects monorepo vs single project |\n| `deep_scan` | `true` to also read source code files for richer articles |\n| `knowledge_files` | Glob patterns for priority documentation files |\n\n## Knowledge Graph Visualization\n\nSee your compiled wiki as an interactive knowledge graph. Topics appear as nodes sized by source count, concepts as connecting edges.\n\n```bash\n/wiki-visualize\n```\n\n- **Hover** nodes to see source count and highlight connections\n- **Click** a node to read the full article in a side panel with coverage badges\n- **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.\n- **Hover edges** to see concept names linking topics\n- **Search** to filter topics by name or alias\n- **Escape** to close the article panel or clear the expansion\n\nCanvas-based, zero dependencies, Nothing Design System tokens (Space Grotesk + Space Mono typography). Works with both knowledge mode and codebase mode wikis.\n\nYou can also run it manually without the plugin:\n```bash\nnode plugin/visualize/server.js --wiki-dir path/to/wiki/\n# Open http://localhost:3848\n```\n\n## Fetch from External Sources\n\nYour context isn't always on disk — a lot of it lives in services like X bookmarks, Readwise highlights, or Pocket saves. `/fetch-bookmarks ` pulls that content into a local directory that `/wiki-compile` can consume alongside your regular sources.\n\nOptional — skip it entirely if all your sources are already local markdown.\n\n### Quick Start\n\n```bash\n/fetch-bookmarks x\n```\n\nFirst run walks you through:\n\n1. Checking that Node.js 20+ is installed\n2. Installing [Field Theory CLI](https://github.com/afar1/fieldtheory-cli) (MIT-licensed, free) globally via npm — one consent prompt\n3. Syncing your X bookmarks using Chrome cookie auth (no X API key needed)\n4. Adding `~/.ft-bookmarks/md/` to your `.wiki-compiler.json` sources\n\nAfter that, `/fetch-bookmarks x` just resyncs. Run `/wiki-compile` whenever you want bookmarks folded into topic articles.\n\n### Auto-Sync (Set and Forget)\n\nManual syncing gets forgotten. Install a daily background job:\n\n```bash\n/fetch-bookmarks schedule x\n```\n\nOn 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.\n\nThe `/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.\n\nUninstall with `/fetch-bookmarks schedule x --uninstall` (or `launchctl unload` manually).\n\n### Available Sources\n\n| Source | Status | Backend |\n|--------|--------|---------|\n| `x` | Shipped | [Field Theory CLI](https://github.com/afar1/fieldtheory-cli) (MIT) |\n| `readwise` | Planned | TBD |\n| `pocket` | Planned | TBD |\n| `github-stars` | Planned | TBD |\n\n### How It Works\n\n`/fetch-bookmarks` is a thin dispatcher. Each source has its own adapter at `plugin/skills/wiki-compiler/adapters/.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.\n\n### Requirements\n\n- **Node.js 20+** (for Field Theory CLI)\n- **Chrome** (for first-time X cookie sync — this is a Field Theory CLI limitation)\n\n### Contributing a New Adapter\n\nCopy `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.\n\n## Capture Links With Context\n\nThe primary UX is: paste a link and say **\"capture this in my wiki.\"** You do not need to remember command names.\n\nIn Codex:\n\n```text\nhttps://example.com/article\n\ncapture this in my wiki\n```\n\nAdd context when you have it:\n\n```text\nhttps://example.com/article\n\ncapture this in my wiki\n\nContext: Relevant to Codex plugin onboarding and skill discovery.\n```\n\nClaude Code users can use the explicit command form:\n\n```bash\n/wiki-capture https://example.com/article --context \"Relevant to Codex plugin onboarding and skill discovery\"\n```\n\nThe capture flow is adapter-based:\n\n| Source | Adapter | What gets saved |\n|--------|---------|-----------------|\n| Web article | `capture-web` | readable page text, metadata, relevance notes |\n| YouTube | `capture-youtube` | transcript evidence, timestamps, workflow notes when relevant |\n| X/Twitter link | `capture-x` | post/thread text or bookmark source, date-aware relevance notes |\n\nCaptured 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.\n\n### Connector Roadmap\n\nThe 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.\n\nPlanned connector shape:\n\n```text\nconnector pulls context\n→ normalizes to markdown with metadata\n→ writes to wiki-sources/{connector}/\n→ adds that folder to sources[]\n→ wiki compile builds topic/concept connections\n```\n\nCandidate connectors:\n\n| Connector | Use case |\n|-----------|----------|\n| Granola | Meeting notes, summaries, decisions, and follow-ups |\n| Google Drive / Docs | Docs, strategy notes, specs, and research folders |\n| Slack | High-signal threads, decisions, and customer/team context |\n| Linear / GitHub Issues | Roadmap, bugs, project decisions, and implementation context |\n| Readwise / Pocket | Reading highlights and saved articles |\n\nThe key rule: connectors create source material; the wiki compiler owns synthesis and connections.\n\n## How It Works (Knowledge Mode)\n\n### Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/wiki-init` | One-time setup -- auto-detects markdown directories, samples files, proposes custom article structure |\n| `/wiki-global-init` | Initialize the default global wiki at `~/Knowledge` or `LLM_WIKI_GLOBAL_DIR` |\n| `/wiki-compile` | Compiles source files into topic articles (incremental -- only recompiles changes). Generates `schema.md` on first run. |\n| `/wiki-capture` | Capture a URL plus context, normalize it into markdown, and connect it to existing topics/concepts |\n| `/wiki-ingest` | Add a single source interactively -- read, discuss key takeaways, update relevant wiki articles |\n| `/fetch-bookmarks` | Pull bookmarks from external services (X today; Readwise, Pocket planned). `schedule ` wires a daily launchd job. |\n| `/wiki-search` | Search across wiki articles by keyword or phrase |\n| `/wiki-lint` | Health checks -- finds stale articles, orphan pages, missing cross-references, contradictions, low coverage |\n| `/wiki-query` | Optional -- Q&A against the wiki. Can file useful answers back into wiki articles. |\n| `/wiki-migrate` | One-time migration -- analyzes your AGENTS.md startup reads, shows which are covered by wiki, generates replacement |\n| `/wiki-visualize` | Launch interactive knowledge graph of your compiled wiki |\n| `/wiki-upgrade` | Update the plugin to the latest version from GitHub |\n\nThe 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.\n\n### Staged Adoption (The Key Feature)\n\nThe plugin never modifies your existing CLAUDE.md or AGENTS.md. Instead, it injects context via a SessionStart hook with three modes:\n\n| Mode | What Happens | Your Existing Setup |\n|------|-------------|-------------------|\n| **staging** (default) | \"Wiki available — check it when you need depth\" | Completely unchanged |\n| **recommended** | \"Check wiki articles before raw files\" | Unchanged, but Claude prioritizes wiki |\n| **primary** | \"Wiki is your primary knowledge source\" | You can optionally simplify startup reads |\n\nChange mode by editing `.wiki-compiler.json`:\n```json\n{ \"mode\": \"staging\" } → { \"mode\": \"recommended\" } → { \"mode\": \"primary\" }\n```\n\n### What Gets Compiled\n\nDuring `/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.\n\nFor example, a product team's wiki might get:\n- **Summary** — **Timeline** — **Current State** — **Key Decisions** — **Experiments & Results** — **Gotchas** — **Open Questions** — **Sources**\n\nWhile a research wiki might get:\n- **Summary** — **Key Findings** — **Methodology** — **Evidence** — **Gaps & Contradictions** — **Open Questions** — **Sources**\n\nAnd a book notes wiki might get:\n- **Summary** — **Characters** — **Themes** — **Plot Threads** — **Connections** — **Quotes** — **Sources**\n\nThe structure is saved in `.wiki-compiler.json` and can be edited anytime. **Summary** and **Sources** are always included.\n\n### Coverage Indicators (Best of Both Worlds)\n\nEvery section includes a coverage tag so you (or your AI agent) know when to trust the wiki vs when to read raw sources:\n\n```markdown\n## Summary [coverage: high -- 15 sources]\n...trust this, it's well-sourced...\n\n## Experiments & Results [coverage: medium -- 3 sources]\n...decent overview, check raw files for details...\n\n## Gotchas [coverage: low -- 1 source]\n...read the raw gotchas.md directly...\n```\n\n- **high** (5+ sources) — trust the wiki section directly\n- **medium** (2-4 sources) — good overview, check raw sources for granular questions\n- **low** (0-1 sources) — read the raw sources listed in that section\n\nThis 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.\n\n### Time-Decay Awareness\n\nTweets 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:\n\n- Extracts a source date from each input (frontmatter `posted_at` / `date`, filename date, or mtime)\n- Orders Timeline and Key Decisions bullets newest-first, date-prefixed\n- Flags claims older than 18 months with ⚠️\n- Adds `[as of YYYY-MM]` tags to sections resting mostly on aging sources\n- In conflicts, prefers the newer source and notes the shift\n\nStable topics (career, personal growth, visa work) use looser thresholds (24/48 months). Nothing gets deleted — stale entries stay for historical context, just clearly marked.\n\n### Obsidian Compatible\n\nThe 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.\n\n### Concept Articles (Cross-Cutting Patterns)\n\nAfter 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?\"\n\nExamples from a real project:\n- **\"Speed vs Quality Tradeoff\"** -- 6 instances where this decision appeared across retention, push notifications, and experiment design\n- **\"Cross-Team Decision Patterns\"** -- communication patterns and decision dynamics synthesized from 24 meetings\n- **\"Evolution of Retention Thinking\"** -- how the approach changed from Oct 2025 to Apr 2026 across analytics, strategy, and experiments\n\nConcept articles are discovered automatically during compilation. You can also seed them in `schema.md` if you know what patterns you want tracked.\n\n### Schema Document\n\nOn 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.\n\nYou 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.\n\n### Wiki Lint\n\nRun `/wiki-lint` to check wiki health:\n\n- **Stale articles** -- sources changed since last compile\n- **Orphan pages** -- articles with deleted/missing sources\n- **Missing cross-references** -- topics sharing 3+ sources that don't link to each other\n- **Low coverage sections** -- `[coverage: low]` tags flagged for improvement\n- **Contradictions** -- conflicting facts across articles (e.g., different dates for same event)\n- **Schema drift** -- topics in wiki/ not listed in schema.md, or vice versa\n\n### Query Filing\n\nWhen `/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.\n\n## Configuration\n\n`.wiki-compiler.json` (created by `/wiki-init`):\n\n```json\n{\n \"version\": 2,\n \"name\": \"My Project\",\n \"mode\": \"staging\",\n \"sources\": [\n { \"path\": \"Knowledge/\", \"exclude\": [\"wiki/\"] },\n { \"path\": \"docs/meetings/\" }\n ],\n \"output\": \"Knowledge/wiki/\",\n \"topic_hints\": [\"retention\", \"onboarding\"],\n \"link_style\": \"obsidian\"\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `version` | Config version (`2` for latest) |\n| `name` | Display name for the knowledge base |\n| `mode` | Integration mode: `staging` / `recommended` / `primary` — OR `codebase` for code repositories |\n| `sources` | Directories to scan |\n| `output` | Where compiled wiki lives |\n| `article_sections` | Article structure — generated during `/wiki-init` based on your content (see below) |\n| `topic_hints` | Optional seed topics to guide classification |\n| `link_style` | `obsidian` (wikilinks) or `markdown` (standard links) |\n| `service_discovery` | (codebase mode) `auto` or `manual` — how to detect modules/services |\n| `knowledge_files` | (codebase mode) Glob patterns for priority documentation files |\n| `deep_scan` | (codebase mode) `true` to also read source code files |\n\n### Custom Article Structure\n\nThe `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.\n\n```json\n\"article_sections\": [\n { \"name\": \"Summary\", \"description\": \"standalone briefing of the topic\", \"required\": true },\n { \"name\": \"Key Findings\", \"description\": \"main discoveries and insights\" },\n { \"name\": \"Methodology\", \"description\": \"approaches and methods used\" },\n { \"name\": \"Open Questions\", \"description\": \"unresolved threads and gaps\" },\n { \"name\": \"Sources\", \"description\": \"backlinks to all contributing files\", \"required\": true }\n]\n```\n\nYou 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.\n\nIf `article_sections` is missing (older configs), the compiler falls back to a default template.\n\n## Safety Guarantees\n\n- Source files are **never modified** — the compiler only writes to the output directory\n- The wiki can be **deleted and regenerated** at any time from source files\n- Your **CLAUDE.md and AGENTS.md are never touched** — context injection happens via hooks\n- **Rollback anytime** — change mode back to `staging` or delete `.wiki-compiler.json`\n\n## Cost Savings (Real Data)\n\nTested on a real project with 1,183 markdown files across meetings, strategy docs, session histories, and research notes.\n\n### Token Reduction\n\n| | Without Wiki | With Wiki |\n|---|---|---|\n| Session startup context | ~79K tokens (13 files) | ~8.5K tokens (INDEX + 2-3 articles) |\n| Per-question research | ~8,000 tokens (10+ files) | ~600 tokens (1 article) |\n| **Reduction** | — | **89%** |\n\n### Compilation Costs\n\n| | Tokens | Cost (Opus) | Cost (Sonnet) |\n|---|---|---|---|\n| First compilation | ~880K | ~$13 | ~$2.60 |\n| Daily incremental | ~100K | ~$1.50 | ~$0.30 |\n| **Break-even** | — | **First session** | **First session** |\n\n### Accuracy\n\nWe spot-checked wiki articles against their raw source files:\n\n- **10/10 key facts accurately synthesized** -- no fabrication, no missing critical details\n- **Coverage indicators are honest** -- sections marked `[coverage: high]` had 5+ contributing sources\n- **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%\n\n### Compression\n\n- 1,183 files → 14 topic articles -- **84x compression**\n- Session startup: 13 file reads → 1 INDEX + 2-3 topic articles -- **89% fewer tokens**\n- ~$1.05 saved per session at Opus pricing ($15/M input tokens)\n\n## Integrating with AGENTS.md (Recommended)\n\nThis 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:\n\n```markdown\n## Knowledge Base\n\nA compiled knowledge wiki is available at `{your output path}/`.\n\n**Session startup:** Read `wiki/INDEX.md` for a topic overview, then read\nspecific topic articles relevant to your current task.\n\n**Using coverage indicators:** Each section has a coverage tag:\n- `[coverage: high]` -- trust this section, skip the raw files.\n- `[coverage: medium]` -- good overview, check raw sources for granular questions.\n- `[coverage: low]` -- read the raw sources listed in that section directly.\n\n**When you need depth:** Check the article's Sources section for links to\nraw files. Only read raw sources for medium/low coverage sections or when\nyou need very specific detail.\n\n**Never modify wiki files directly** -- they are regenerated by `/wiki-compile`.\n```\n\nOnce 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.\n\n**When to add this:** After running `/wiki-compile` at least once and validating that the topic articles accurately reflect your knowledge.\n\n## Advanced\n\n### Incremental Compilation\n\nAfter the first full compile, `/wiki-compile` only recompiles topics whose source files changed. INDEX.md is always regenerated.\n\n### Force Full Recompile\n\n```\n/wiki-compile --full\n```\n\n### Compile Single Topic\n\n```\n/wiki-compile --topic retention\n```\n\n### Interactive Ingest\n\nAdd sources one at a time with `/wiki-ingest`:\n\n```\n/wiki-ingest path/to/new-meeting-notes.md\n```\n\nThe 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.\n\nThis 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.\n\n### Wiki Search\n\nSearch your compiled wiki:\n\n```\n/wiki-search retention experiments\n```\n\nSearches 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.\n\nFor synthesis questions that require connecting multiple topics, use `/wiki-query` instead.\n\nFor 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.\n\n### Migrate to Wiki-First Startup\n\nOnce your wiki is compiled and spot-checked, run `/wiki-migrate` to switch your AGENTS.md from reading raw files to reading the wiki:\n\n```\n/wiki-migrate\n\nWiki Migration Report for \"My Project\"\n\nCurrent startup: 13 file reads\n\n✅ gotchas.md → covered by analytics [coverage: high]\n✅ product-context.md → covered by product [coverage: high]\n⚠️ reporting-backlog.md → partially covered [coverage: medium]\n❌ acceptance-criteria.md → not covered (operational checklist)\n\nSummary: 10/13 reads can be replaced\nEstimated savings: ~79K → ~8.5K tokens (89% reduction)\n```\n\nThe command generates a replacement startup section and applies it with your confirmation.\n\n### Stale Wiki Detection\n\nThe plugin automatically detects when source files have changed since the last compile. Enable it in `.wiki-compiler.json`:\n\n```json\n{ \"auto_update\": \"prompt\" }\n```\n\nWith `prompt` mode, the SessionStart hook counts changed files and warns:\n\n> \"Wiki may be stale — 42 files changed since last compile (2026-04-06). Run /wiki-compile to update.\"\n\nSet to `\"off\"` (default) to disable.\n\n### Scheduled Compilation\n\nUse Claude Code's `/schedule` to set up daily automatic compilation.\n\n### Updating the Plugin\n\nFrom inside Claude Code:\n```\n/wiki-upgrade\n```\n\nThis pulls the latest version from GitHub and shows what changed. Restart Claude Code after to load new commands and hooks.\n\nIf `/wiki-upgrade` isn't available yet (older version), update manually:\n```bash\ncd /path/to/llm-wiki-compiler && git pull\nclaude plugin update llm-wiki-compiler\n# Then restart Claude Code\n```\n\n## License\n\nMIT\n",
"bytes": 33151,
"sha": "4de10bdf02b9ebc2de6097a22c2881e4b25f8488af2129ce28a52b80e78e74a3",
"repo_slug": "ussumant/llm-wiki-compiler",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_ussumant_llm_wiki_compiler_llm_wiki_comp_b04012c0/readme"
}