
llm-wiki-compiler
Compile markdown knowledge files or codebases into a topic-based wiki. Implements Karpathy's LLM Knowledge Base pattern.
- version
- 2.1.0
- GitHub stars
- 331
Install
/plugin install llm-wiki-compiler@llm-wiki-compilerRun it inside Claude Code after adding the marketplace with /plugin marketplace add ussumant/llm-wiki-compiler.
Contents
Discovered from sourceSkills 1
Wiki Compiler — Compilation Algorithm
This skill contains the 5-phase algorithm for compiling source files into a topic-based wiki.
Safety rule: NEVER modify any file outside the configured output directory. Source files are read-only.
Codex Usage
In Codex, use this skill through natural-language workflow prompts instead of Claude slash commands. The preferred capture UX is intentionally simple: paste a link and say "capture this in my wiki."
| Codex prompt | Claude command equivalent |
|---|---|
| "Initialize a wiki for this repo" | /wiki-init |
| "Set up my global wiki" | /wiki-global-init |
| "Capture this in my wiki: {url}. Context: {why it matters}" | /wiki-capture {url} --context "{why it matters}" |
| "{url} — capture this in my wiki" | /wiki-capture {url} |
| "Compile changed sources into the wiki" | /wiki-compile |
| "Search the compiled wiki for architecture decisions" | /wiki-search architecture decisions |
| "Answer this from the compiled wiki: {question}" | /wiki-query {question} |
| "Launch the wiki knowledge graph" | /wiki-visualize |
The command markdown files in commands/ remain the canonical workflow specs. When those files mention ${CLAUDE_PLUGIN_ROOT}, Codex should resolve the same paths relative to the installed plugin root.
For session-start context in Codex, read hooks/wiki-session-context as the shared helper. It prints the same wiki guidance that Claude receives through the SessionStart wrapper, but no Codex hook is registered until a supported hook schema is available.
Prerequisites
Before running, read .wiki-compiler.json from the project root to get:
mode— "knowledge" (default, markdown files) or "codebase" (code repository)sources[]— directories to scan (with optionalexcludepatterns)output— where to write wiki articlesname— project/domain name for the wikitopic_hints[]— optional seed topics from the userlink_style— "obsidian" (default) or "markdown"
Global wiki default: "my wiki" means the global wiki at ~/Knowledge unless LLM_WIKI_GLOBAL_DIR is set. Local/project wikis still live wherever a repo or folder has its own .wiki-compiler.json. A user can paste a URL and say "capture this in my wiki" to save one link plus context into the global wiki by default; "capture this in this project wiki" targets the local wiki.
Note: Sources don't have to live alongside the project. Captures are stored under wiki-sources/captures/ in the target wiki. /fetch-bookmarks <source> can pull batches from external services (X bookmarks today; Readwise, Pocket, GitHub stars planned) into a local directory that appears in sources[] alongside everything else.
Codebase mode additional config:
service_discovery— "auto" (detect monorepo vs single project) or "manual"knowledge_files[]— glob patterns for priority documentation files (README.md, CLAUDE.md, etc.)deep_scan—false(default) ortrue(also read key source files for richer articles)code_extensions[]— file extensions to consider as source code (e.g.,.ts,.py,.go)
Phase 1: Scan Sources
Knowledge mode (default)
- For each entry in
sources[], list all.mdfiles using Glob - Exclude any paths matching
excludepatterns (e.g., thewiki/output directory itself) - Read
.compile-state.jsonfrom the output directory - Compare file list against previous state to identify new or changed files
- On first run (no prior state), treat ALL files as new
Codebase mode
- For each entry in
sources[], scan for knowledge files matchingknowledge_files[]patterns:- Documentation:
README.md,CLAUDE.md,AGENTS.md,ARCHITECTURE.md,CONTRIBUTING.md - API contracts:
*.proto,*.graphql,openapi.yaml,openapi.json - Decision records:
ADR-*.md,docs/adr/*.md - Infrastructure:
docker-compose.yml,Dockerfile,k8s/*.yaml - Operations:
docs/runbooks/*.md,CHANGELOG.md,.env.example
- Documentation:
- If
deep_scanistrue, also scan for key source files per topic area:- Entry points:
index.ts,main.py,main.go,lib.rs,App.swift, etc. - Type definitions:
types.ts,models.py,schema.prisma,*.proto - Config files:
package.json,tsconfig.json,pyproject.toml,go.mod,Cargo.toml - Limit to ~20 source files per topic area to control token cost
- Entry points:
- Exclude:
node_modules/,dist/,.git/,vendor/,__pycache__/,.build/,target/, and configuredexcludepatterns - Read
.compile-state.jsonand compare to identify new or changed files - On first run, treat ALL discovered files as new
Phase 2: Classify and Discover Topics
Knowledge mode (default)
- For each source file, read its:
- File path (directory structure is a strong signal)
- Title (first
#heading) - First 500 characters of content
- Source date — extract using this precedence: frontmatter
posted_at/date/last_updated> filename date pattern (e.g.,2026-04-15-standup.md) > file mtime. Parse toYYYY-MM-DD. Track alongside the file path — every source should have a date, or be explicitly markedundated.
- Classify each file into one or more topics based on content signals
- Use
topic_hintsfrom config as seed topics when available - Prefer existing topic slugs from
.compile-state.json— avoid creating near-duplicates - A single file CAN belong to multiple topics
- Files that don't match any topic: group them — if 3+ unclassified files share a theme, create a new topic
- Topic slugs should be lowercase-kebab-case (e.g.,
d1-retention,push-notifications) - Classify each topic as time-sensitive or stable (used by Phase 3 for date annotations):
- Time-sensitive (default when unsure): any topic touching fast-moving domains — AI tooling/architecture, UI/design patterns, growth/marketing tactics, workflows, dev tools,
inspiration-*, or any topic drawing ≥50% of its sources from external bookmark directories. - Stable: career/visa/personal-growth/sessions-*/relationship topics where claims don't decay on short timescales.
- Err toward time-sensitive — the cost of annotating a date on stable content is low; the cost of confident-sounding stale claims is high.
- Time-sensitive (default when unsure): any topic touching fast-moving domains — AI tooling/architecture, UI/design patterns, growth/marketing tactics, workflows, dev tools,
Topic detection guidance:
- Use directory names as strong signals (files in
retention/likely belong to a retention topic) - Use headings and key terms in content as secondary signals
- Meeting notes and session histories often belong to multiple topics
- Team memory files (gotchas, decisions, dead-ends) contain entries for many topics — classify by scanning content
Codebase mode
Topic discovery uses a 3-pass approach: structure → knowledge → optional deep scan.
Pass 1 — Structure scan (automatic topic discovery):
-
Detect project type by looking for manifest files in the root:
package.json→ Node.js/JavaScript/TypeScriptgo.mod→ GoCargo.toml→ Rustpyproject.toml/requirements.txt/setup.py→ PythonGemfile→ Ruby*.sln/*.csproj→ .NETPackage.swift→ Swiftpom.xml/build.gradle→ Java/Kotlin
-
Detect monorepo vs single project:
- Monorepo/microservices: Multiple directories each containing their own manifest file (e.g.,
services/auth/package.json,services/billing/package.json). Each service directory = a topic. - Single project: One manifest at root. Use top-level directory structure as topic boundaries (e.g.,
src/auth/,src/api/,src/models/each become topics).
- Monorepo/microservices: Multiple directories each containing their own manifest file (e.g.,
-
Auto-create cross-cutting topics when relevant files exist:
infrastructure— ifdocker-compose.yml,Dockerfile,k8s/,.github/workflows/existtesting— iftests/,__tests__/,spec/,test/directories existdeployment— if CI/CD configs, Dockerfile, deployment scripts exist
Pass 2 — Knowledge file scan (primary sources):
For each topic area discovered in Pass 1:
- Find all knowledge files (from
knowledge_files[]config) within that topic's directory - Read each knowledge file's content — these are the primary sources for compilation
- A knowledge file CAN belong to multiple topics (e.g., root
README.mdtouches all topics) - Root-level knowledge files (
./README.md,./CLAUDE.md,./ARCHITECTURE.md) contribute to ALL topics or get their ownproject-overviewtopic
Pass 3 — Deep scan (optional, when deep_scan: true):
For each topic area, also read key source files to enrich understanding:
- Entry points:
index.ts,main.py,main.go,lib.rs,App.swift,app.py - Type definitions:
types.ts,models.py,schema.prisma,*.proto,types.go - Route/API definitions:
routes.ts,api.py,handlers.go,controller.ts - Config:
package.json(dependencies),tsconfig.json, language-specific config - Limit to ~20 files per topic to control token cost
- These supplement knowledge files — they add implementation detail to the article's Architecture, API Surface, and Data sections
Classification output is identical to knowledge mode: topic slug → list of source files. The rest of the pipeline (Phases 3-5) runs unchanged.
Topic slug conventions for codebases:
- Service names:
auth-service,billing-service,notification-service - Module names:
auth,api-routes,data-layer,ui-components - Cross-cutting:
infrastructure,testing,deployment,shared-utils
Article template: When mode is codebase, use ${CLAUDE_PLUGIN_ROOT}/templates/codebase-article-template.md as the fallback template (instead of the default knowledge template). If article_sections is set in config, use those sections (same as knowledge mode).
Phase 3: Compile Topic Articles
For EACH topic that has new or changed source files:
-
Read ALL source files classified under that topic (need full context, not just changed files)
-
Write the topic article to
{output}/topics/{topic-slug}.md -
Determine article structure:
- If
.wiki-compiler.jsonhas anarticle_sectionsarray: use those sections in order. Each section'sdescriptionfield tells you what content belongs there. - If
article_sectionsis absent (legacy configs without this field): fall back to the default template at${CLAUDE_PLUGIN_ROOT}/templates/article-template.md
- If
-
Fill every section with specific, factual content -- no placeholders
-
Summary should be a standalone briefing: someone reading just this section should understand the current state
-
Sources must list every source file that contributed, using the configured link style
-
Coverage indicators -- each section heading must include a coverage tag:
[coverage: high -- N sources]-- 5+ sources contributed to this section, detailed synthesis. Reader can trust this section without checking raw files.[coverage: medium -- N sources]-- 2-4 sources, decent but may miss detail. Reader should check raw sources for granular or recent questions.[coverage: low -- N sources]-- 0-1 sources or sparse data. Reader should read the raw sources directly.
Calculate coverage per section, not per article. An article might have high coverage on Summary but low coverage on Experiments. This tells the reader (human or AI agent) exactly when to trust the wiki vs when to fall back to raw files.
-
Time-decay annotations — apply these rules so readers can calibrate claims against when they were captured. Use the
source_datecollected in Phase 2.Define the staleness threshold:
- Time-sensitive topics: claims older than 6 months are "aging", older than 18 months are "stale"
- Stable topics: claims older than 24 months are "aging", older than 48 months are "stale"
Apply these conventions:
- Summary section for time-sensitive topics: lead with the date range of sources, e.g., "Sources span 2024-01 to 2026-04. Recent consensus (<12mo): … Older patterns (>18mo, may be stale): …". Do not blend old and new claims as if equivalent.
- Timeline / Key Decisions: order bullets reverse-chronologically (newest first). Prefix each bullet with its date. Prefix stale bullets with
⚠️ [YYYY-MM, may be stale]so the reader can skim past them. - Per-section
[as of YYYY-MM]tag: when a section rests primarily on aging sources (older than the topic's aging threshold), add[as of YYYY-MM]next to the coverage tag, where YYYY-MM is the median source date. - Conflicting sources: when two sources disagree and one is materially newer (>12 months for time-sensitive, >24 months for stable), prefer the newer synthesis and note the shift explicitly in Key Decisions:
"YYYY-MM: {earlier framing} → {new framing}". Attribute both to their source files. - Bookmark-dominated topics (≥50% of sources from external bookmark directories like
~/.ft-bookmarks/md/bookmarks/): always annotate bullets with inline dates, and mention the dominant date range in Summary. Tweets are snapshots of a moment — never present them as timeless.
Do NOT delete stale content. Flag, re-order, or annotate. The wiki is a time-series artifact; old entries have historical value even when no longer current.
Link style:
obsidian: Use[[relative/path/to/file]](without .md extension)markdown: Use[filename](relative/path/to/file.md)
Relative paths should be from the topics/ directory to the source file.
Parallel compilation: When possible, compile multiple topic articles in parallel using subagents. Each subagent gets one topic + its source files. This significantly speeds up first-run compilation.
IMPORTANT — Sequencing: Parallel dispatch is ONLY for Phase 3 (topic article compilation). After ALL parallel agents have returned and all topic articles are written, the PARENT process MUST continue to Phase 3.5 (concept discovery). Do NOT end the compilation after Phase 3. The remaining phases (3.5, 3.7, 4, 5) run sequentially in the parent process after parallel compilation completes.
Phase 3.5: Discover and Compile Concept Articles
This phase MUST run after Phase 3 completes. Read the topic articles that were just compiled and look for cross-cutting patterns. These become concept articles -- stored in {output}/concepts/.
How to discover concepts:
- Read all topic articles that were just compiled (or all if first run)
- Look for patterns that appear in 3+ topic articles:
- Recurring decisions -- the same tradeoff appearing in different contexts (e.g., "speed vs quality" showing up in retention decisions, push notification strategy, and experiment design)
- Relationship patterns -- a person, team, or stakeholder who appears across multiple topics with consistent dynamics
- Methodology evolution -- how an approach changed over time across topics (e.g., "how we measure retention" evolving from n-day to bracket)
- Recurring failures -- the same type of mistake across different domains (e.g., "trusting aggregated data without checking raw events")
- Check
schema.mdfor existing concepts -- prefer updating existing concept articles over creating new ones - Only create a concept if it genuinely connects 3+ topics with a non-obvious insight. Don't force concepts.
Concept article format:
Write to {output}/concepts/{concept-slug}.md:
---
concept: {Concept Name}
last_compiled: {YYYY-MM-DD}
topics_connected: [{topic1}, {topic2}, {topic3}]
status: active
---
# {Concept Name}
## Pattern
{1-2 paragraphs describing the cross-cutting pattern. What keeps recurring and why.}
## Instances
{Each time this pattern appeared, with dates and context}
- **{date}** in [[../topics/{topic}]]: {what happened}
- **{date}** in [[../topics/{topic}]]: {what happened}
## What This Means
{Synthesis -- what the pattern tells you about your work, decisions, or blind spots.
This is the "so what" that Farzapedia calls the writer's job.}
## Sources
- [[../topics/{topic1}]]
- [[../topics/{topic2}]]
Important: Concept articles are interpretive, not just factual. They answer "what does this pattern mean?" not just "what happened?" This is what makes them useful for strategic and creative thinking.
Create the concepts/ directory if it doesn't exist.
Phase 3.7: Generate or Update Schema
If {output}/schema.md does not exist (first run):
- Generate it from
${CLAUDE_PLUGIN_ROOT}/templates/schema-template.md - Fill in the Topics section AND Concepts section with all discovered slugs and descriptions
- Add an Evolution Log entry: "{today's date}: Initial schema generated from {N} topics, {N} concepts"
If {output}/schema.md already exists:
- Read it BEFORE Phase 2 (classification) -- use its topic list, concept list, and naming conventions
- After Phase 3.5 (concepts), check for new topics and concepts not in the schema
- Add any new topics/concepts to the schema
- Add an Evolution Log entry if anything was added: "{today's date}: Added {slug} -- {reason}"
- Never remove topics or concepts from schema without human approval -- flag them as candidates instead
The schema is the source of truth for wiki structure. The human can edit it between compiles to rename topics, merge them, or change conventions. The compiler respects those changes.
Phase 4: Update INDEX.md
Write to {output}/INDEX.md:
# {name} Knowledge Base
Last compiled: {today's date}
Total topics: {count} | Total sources: {unique file count}
## Topics
| Topic | Also Known As | Sources | Last Updated | Status |
|-------|--------------|---------|-------------|--------|
| [[topics/{slug}]] | {keyword aliases} | {count} | {date} | active |
## Concepts
| Concept | Connects | Last Updated |
|---------|----------|-------------|
| [[concepts/{slug}]] | {topic1}, {topic2}, {topic3} | {date} |
## Recent Changes
- {date}: {what changed in this compilation run}
Keyword aliases: For each topic, include alternate names, abbreviations, and related terms that someone might search for. For example, a topic called side-quest-ideas might have aliases "FitOS, Growth OS, Paperclip, ClawShip". These help /wiki-search and Claude find the right topic even when the user uses different terminology.
Concepts section: List all concept articles with the topics they connect. If no concepts exist yet, omit this section.
Always regenerate INDEX.md, even if no topics changed (it's cheap).
Phase 5: Update State and Log
- Log — Append to
{output}/log.md:
## {today's date}
**Topics updated:** {list}
**New topics:** {list or "none"}
**Sources scanned:** {count}
**Sources changed:** {count}
- Compile state — Update
{output}/.compile-state.json:
{
"last_compiled": "{today's date}",
"topics": ["{slug1}", "{slug2}", ...],
"source_locations": ["{path1}", "{path2}", ...],
"total_sources_scanned": {count}
}
Phase 6: Generate CONTEXT.md (codebase mode only, first run)
On the first compile (no prior .compile-state.json), generate {output}/CONTEXT.md:
# Codebase Wiki — Navigation Guide
This project has a compiled knowledge wiki. Use it instead of scanning raw files.
## How to use this wiki
1. Start at INDEX.md — scan the topic table to find relevant modules
2. Read 1-3 topic articles relevant to your current task
3. Check coverage tags:
- [coverage: high] — trust this section, skip raw files
- [coverage: medium] — good overview, check raw sources for implementation details
- [coverage: low] — read the raw source files listed in Sources
4. Check concepts/ for cross-cutting patterns (auth strategy, error handling, etc.)
5. Only read raw source files when you need code-level detail
## When NOT to use the wiki
- Writing new code (read the actual source files for exact syntax/types)
- Debugging a specific function (go to the file directly)
- The wiki article says [coverage: low] for what you need
## Stats
Compiled: {date} | Topics: {N} | Sources: {M} | Auto-updates on session start
On subsequent compiles, update the Stats line in CONTEXT.md.
After generating CONTEXT.md, ask the user (don't auto-modify): "Want me to add a reference to wiki/CONTEXT.md in your CLAUDE.md? This helps the agent discover the wiki automatically."
Output
After compilation, show a summary to the user:
- Topics created/updated (with article line counts)
- Total sources scanned
- Any files that couldn't be classified
- Any suggested new topics for next run
- Time taken
Commands 12
Fetch Bookmarks from an External Source
Pull bookmarks from an external service (X/Twitter today; Readwise, Pocket, GitHub stars planned) into a local directory that /wiki-compile can consume. Optional — only needed when you want wiki topics synthesized from external sources, not just files already on disk.
The command itself is a thin dispatcher. Each source has its own adapter file that handles dependency checks, auth, sync, and wiring.
Instructions
Step 1: Parse arguments
Accept one of these forms:
/fetch-bookmarks <source>— sync once (default)./fetch-bookmarks schedule <source>— install a daily auto-sync job./fetch-bookmarks schedule <source> --uninstall— remove the auto-sync job./fetch-bookmarks(no args) — list available adapters and usage; then stop.
When listing adapters, glob ${CLAUDE_PLUGIN_ROOT}/skills/wiki-compiler/adapters/*.md:
Usage:
/fetch-bookmarks <source> Sync once
/fetch-bookmarks schedule <source> Install daily auto-sync
/fetch-bookmarks schedule <source> --uninstall Remove auto-sync
Available sources:
- x — X/Twitter bookmarks (via Field Theory CLI)
More adapters planned: readwise, pocket, github-stars.
Step 2: Locate the adapter
- Resolve the adapter file at
${CLAUDE_PLUGIN_ROOT}/skills/wiki-compiler/adapters/{source}.md. - If the file does not exist, print:
Then stop.No adapter for "{source}" yet. Available: {list}. Want to contribute one? See adapters/x.md for the contract.
Step 3a: One-off sync (default)
- Read the adapter file in full.
- Follow its numbered steps in order. Each adapter is self-contained and handles its own preflight, consent prompts, sync, and config updates.
- Surface the adapter's step-by-step progress to the user as you go. Do not retry failing steps silently — if a step fails, stop and show the error.
- After successful completion, print:
Do not auto-invokeBookmarks fetched. Run /wiki-compile to synthesize them into topic articles./wiki-compile.
Step 3b: Install auto-sync (schedule <source>)
- Read the adapter file and look for its
## Schedulingsection. It must document:sync_command— the shell command to run on a schedule (e.g.,ft sync && ft mdforx)default_cadence— recommended schedule (e.g., "daily 03:00 local")log_path— where the sync command writes stdout/stderr
- If the adapter has no
## Schedulingsection, tell the user this adapter doesn't support auto-sync yet and stop. - macOS: Generate a launchd plist at
~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plistusing the adapter'ssync_commandanddefault_cadence. Label:dev.llm-wiki-compiler.{source}-sync. IncludeStandardOutPathandStandardErrorPathpointing atlog_path. Use/bin/bash -lc "<sync_command>"so the login shell loads PATH. SetRunAtLoadtofalse. - Run
launchctl unload ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist 2>/dev/nullfirst (idempotent), thenlaunchctl load ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist. - Verify with
launchctl list | grep dev.llm-wiki-compiler.{source}-sync. - Print: next scheduled run time, log path, and the uninstall command. Example:
✓ Auto-sync installed. Next run: tomorrow 03:00 local. Log: ~/.ft-bookmarks/autosync.log Uninstall: /fetch-bookmarks schedule x --uninstall - Linux / WSL: Don't auto-install. Print a crontab snippet the user can paste:
# Add this with `crontab -e`: 0 3 * * * /bin/bash -lc '<sync_command> >> <log_path> 2>&1' - Windows: Print a Task Scheduler hint; don't auto-install.
Step 3c: Uninstall auto-sync (schedule <source> --uninstall)
- macOS: Run
launchctl unload ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist 2>/dev/null, then delete the plist file. - Print confirmation.
- If the plist doesn't exist, say so and stop without error.
Arguments
<source>— slug matching an adapter file (currently:x).schedule <source>— install auto-sync for this source.schedule <source> --uninstall— remove auto-sync for this source.- No arguments: prints help listing available adapters.
Adapter contract (for contributors)
Each adapter is a self-contained markdown file that the dispatcher follows. Adapters must:
- Preflight runtime and CLI dependencies. Abort with a friendly install link if a prerequisite is missing — never auto-install a runtime.
- Get explicit user consent before installing any tool (
npm install,pip install, etc.). Show the project URL and license. - Run the third-party sync command and surface its output verbatim so the user can respond to any prompts it raises.
- Ensure the source's output ends up as markdown at a stable path.
- Read
.wiki-compiler.jsonfrom the project root. If that path is not already present insources[], ask the user to confirm adding it, then write the update preserving all other fields. - Print a "run
/wiki-compile" suggestion. Never auto-invoke compile. - Optional:
## Schedulingsection documentingsync_command,default_cadence, andlog_pathso/fetch-bookmarks schedule <source>can wire launchd/cron. Adapters without this section don't support auto-sync.
See plugin/skills/wiki-compiler/adapters/x.md for the reference implementation.
Capture a Link Into the Wiki
Capture a URL plus user context, normalize it into a durable markdown source, then connect it to the global wiki, local project wiki, or both.
Arguments
/wiki-capture <url>— capture a link and ask for context/wiki-capture <url> --context "why this matters"— capture with explicit context/wiki-capture <url> --no-update— only write the source markdown; do not update wiki articles
Codex prompt equivalents:
https://example.com/article
capture this in my wiki
or:
Capture this in my wiki:
{url}
Context: {why it matters to the work I am doing}
Instructions
Step 1: Resolve target wiki
Default global wiki:
~/Knowledge
Override:
LLM_WIKI_GLOBAL_DIR=/path/to/wiki-root
Routing rules:
- If the user says "my wiki", "global wiki", "personal wiki", or just "capture this in my wiki", use the global wiki by default.
- If the user says "this repo", "this project", "local wiki", or "project wiki", use the nearest local
.wiki-compiler.json. - If the user says "both", capture into both global and local wiki targets.
- If no local
.wiki-compiler.jsonexists and the user asks for local capture, offer to initialize one. - If no global
.wiki-compiler.jsonexists, initialize the global wiki automatically fromtemplates/global-wiki-config.jsonbefore capture. - If a local wiki exists and the capture defaults to global, mention that a local wiki is available and offer to also connect the source there when it clearly relates to the current project.
Step 2: Validate wiki config
- For each target wiki, read
.wiki-compiler.json. - Confirm
outputis set. - If the target wiki has not been compiled yet, still allow capture, but explain that connections will be stronger after the first compile.
Step 3: Collect user context
- If
--contextis absent, ask:"What should I pay attention to? For example: how this link relates to the product, codebase, strategy, customer, or workflow."
- Treat this context as part of the source, not as a transient instruction.
- Do not summarize the link generically. Read it through the user's context.
Step 4: Route to a capture adapter
Choose exactly one adapter:
| URL pattern | Adapter |
|---|---|
youtube.com, youtu.be | skills/wiki-compiler/adapters/capture-youtube.md |
x.com, twitter.com | skills/wiki-compiler/adapters/capture-x.md |
Any other http or https URL | skills/wiki-compiler/adapters/capture-web.md |
Read the adapter and follow it. The adapter must return a normalized markdown file path under the configured capture source directory.
Step 5: Ensure capture source is configured
- Default capture source directory:
wiki-sources/captures/ - If
.wiki-compiler.jsonalready includes that path insources[], leave it alone. - Otherwise ask:
Add wiki-sources/captures/ to this wiki's sources so future compiles include captured links? (y/n) - On yes, append:
{ "path": "wiki-sources/captures/", "description": "Captured links with user context" } - Preserve every other config field. Do not reformat unrelated config.
Step 6: Connect it to the wiki
If --no-update is set:
- Stop after writing the source file and wiring the source directory.
- Print the source path and suggest running
/wiki-ingest {source_path}or/wiki-compile.
Otherwise:
- Read
{output}/INDEX.mdand{output}/schema.mdif they exist. - Read the normalized source file.
- Identify 1-3 likely existing topics or concepts this source connects to.
- Present a short connection plan:
Captured: {title} Likely connections: - {topic}: {why it fits} - {concept}: {why it fits} Proposed update: - Update existing topic(s): {list} - Create new topic/concept only if needed: {slug or "none"} - Ask for confirmation before writing wiki article changes.
- On confirmation, follow the
/wiki-ingestflow using the captured markdown file as the source. Integrate the user's context and extracted insights into topic/concept articles, with provenance back to the captured source and original URL.
Step 7: Output summary
Print:
Captured: {title}
Source: {path}
Original URL: {url}
Connected to:
- {topic/concept}: {what changed}
Target wiki:
- {global|local|both}: {wiki root}
Next:
- Run /wiki-lint to check cross-links and coverage
- Run /wiki-visualize to see the new graph connections
Source format
Use templates/captured-source-template.md as the source shape. Every captured source must include:
source_typeurlcaptured_attitleuser_context- extracted content or transcript
- relevance notes
- candidate wiki connections
Safety
- Never overwrite an existing captured source. If the slug exists, append
-2,-3, etc. - Never update raw source files outside
wiki-sources/captures/. - Never auto-install tools without explicit user consent.
- Do not auto-create a new topic when an existing topic is a reasonable fit.
Compile Knowledge Base Wiki
Compile all configured markdown source files into a topic-based wiki.
Instructions
-
Read configuration from
.wiki-compiler.jsonin the project root (or nearest parent directory). If not found, tell the user to run/wiki-initfirst. -
Validate configuration:
sources[]must have at least one entryoutputmust be set- Source paths must exist
-
Read schema from
{output}/schema.mdif it exists. Use it to guide topic/concept classification and naming. If it doesn't exist (first run), it will be generated in Phase 3.7. -
Invoke the
wiki-compilerskill to run the compilation:- Pass
article_sectionsfrom config to the skill (if present — legacy configs may not have this field) - Phase 1: Scan sources
- Phase 2: Classify and discover topics (respecting schema if present)
- Phase 3: Compile topic articles using
article_sectionsfor structure (use parallel agents when possible) - Phase 3.5: Discover and compile concept articles (cross-cutting patterns)
- Phase 3.7: Generate or update schema.md
- Phase 4: Update INDEX.md (now includes concepts section)
- Phase 5: Update state and log
- Pass
-
Show completion summary with topics created/updated, concepts discovered, source count, and schema changes.
Arguments
- No arguments: incremental compilation (recompile changed topics)
--full: force recompile all topics regardless of changes--topic {slug}: recompile only the specified topic--dry-run: show what would be compiled without writing files
Initialize the Global Wiki
Create or repair the user's default cross-project wiki.
Arguments
/wiki-global-init— initialize the default global wiki/wiki-global-init --path ~/Somewhere— initialize a custom global wiki directory
Codex prompt equivalents:
Set up my global wiki
or:
Use ~/Knowledge as my global wiki
Global wiki location
Default:
~/Knowledge
Override:
LLM_WIKI_GLOBAL_DIR=/path/to/wiki-root
Prefer ~/Knowledge over hidden app storage because users can browse it, back it up, sync it, edit sources, and understand where their knowledge lives.
Instructions
- Resolve the target directory:
--pathwins if provided.- Else
LLM_WIKI_GLOBAL_DIRif set. - Else
~/Knowledge.
- Create the directory if it does not exist.
- Create these subdirectories if missing:
wiki-sources/captures/ wiki/ - If
.wiki-compiler.jsondoes not exist, create it fromtemplates/global-wiki-config.json. - If
.wiki-compiler.jsonexists, verify it includeswiki-sources/captures/insources[]; ask before adding it if missing. - Do not overwrite an existing config.
- Print:
Global wiki ready at {path} Try: https://example.com capture this in my wiki
Default config
Use templates/global-wiki-config.json as the default config shape. The default wiki is a knowledge-mode wiki with capture sources enabled and output at wiki/.
Ingest a Single Source
Interactive workflow for adding one source file to the wiki. The LLM reads the file, discusses key takeaways with the user, then updates relevant topic articles.
Instructions
Step 1: Validate
- Read
.wiki-compiler.jsonfrom the project root (or nearest parent directory). If not found, tell the user to run/wiki-initfirst. - Accept one argument: the file path to ingest (e.g.,
/wiki-ingest Knowledge/meetings/2026-04-07-standup.md) - If no argument provided, ask: "Which file would you like to ingest?"
- Verify the file exists and is a
.mdfile - Check that the file is within one of the configured
sources[]directories (warn if not, but allow it)
Step 2: Read and discuss
- Read the full source file
- Present a brief summary of key takeaways (3-5 bullet points)
- Ask the user: "Anything you want me to emphasize or de-emphasize when updating the wiki?"
- Wait for the user's response before proceeding — this is the interactive part where the user guides what matters
Step 3: Classify
- Read
{output}/schema.mdto understand existing topics and naming conventions - Determine which existing topics this source belongs to (can be multiple)
- If the source introduces a genuinely new topic not in the schema, propose creating it
- Show the user: "This file touches these topics: [list]. I'll update each one. Sound right?"
- Wait for confirmation before proceeding
Step 4: Update topic articles
For each affected topic:
- Read the current topic article from
{output}/topics/{slug}.md - Read
article_sectionsfrom.wiki-compiler.json(or use default template from${CLAUDE_PLUGIN_ROOT}/templates/article-template.mdif absent) - Integrate the new source's information into the relevant sections
- Respect the user's emphasis guidance from Step 2
- Update coverage indicators — the source count may change the coverage level for some sections
- Add the new source to the Sources section (using configured
link_style) - Update the
source_countin the article frontmatter - Write the updated article
If a new topic was proposed and approved in Step 3:
- Create a new topic article using the configured
article_sections - Populate it with content from this source
Step 5: Update schema, index, and state
- Schema — If a new topic was created, add it to
{output}/schema.mdwith an evolution log entry: "{date}: Added {slug} — discovered during ingest of {filename}" - INDEX.md — Regenerate with updated source counts and dates
- Log — Append to
{output}/compile-log.md:## {date} — ingest **Source:** {filename} **Topics updated:** {list} **New topics:** {list or "none"} - State — Update
.compile-state.jsonwith new source in the file list
Step 6: Summary
Show what changed:
Ingested: {filename}
Topics updated:
- {topic1}: {brief description of what was added/changed}
- {topic2}: {brief description of what was added/changed}
New topics created: {list or "none"}
Tip: Run /wiki-lint to check for new cross-references or contradictions.
Arguments
- Single argument: file path to ingest
- No arguments: prompts user to specify a file
--quiet: Skip the interactive discussion (Steps 2-3 user prompts) and auto-classify. Useful for batch scripting.
Initialize Knowledge Base Wiki
Interactive, conversational setup for a new knowledge base wiki. One question at a time, multiple choice when possible.
Arguments:
- (none) — auto-detects whether this is a codebase or knowledge project (see Auto-Detection below)
--codebase— force codebase mode (skip auto-detection)--knowledge— force knowledge mode (skip auto-detection)
Instructions
Important: Ask ONE question per message. Wait for the user's response before moving to the next question. Never batch multiple questions. Keep the tone conversational — like a knowledgeable colleague setting things up for you.
Auto-Detection (when no flag is provided)
Before asking any questions, scan the project root to determine the mode:
- Check for code manifest files:
package.json,go.mod,Cargo.toml,pyproject.toml,requirements.txt,Gemfile,*.sln,Package.swift,pom.xml,build.gradle - Check for markdown-heavy directories:
Knowledge/,docs/,notes/,content/,meetings/,research/, or any directory with 10+.mdfiles
Decision logic:
- Manifest found, no markdown directories → codebase mode
- Markdown directories found, no manifest → knowledge mode
- Both found → ask the user:
I see both code files and markdown knowledge directories here. A) Codebase wiki — compile a wiki about this codebase's architecture, decisions, and patterns B) Knowledge wiki — compile a wiki from your markdown files (meetings, notes, research) - Neither found → ask the user what they want to compile
Then proceed to the appropriate mode below.
Codebase Mode (--codebase or auto-detected)
When codebase mode is selected, use this streamlined flow instead of the standard 10-step process.
Codebase Step 1: Check for existing config
Same as standard Step 1 — check for .wiki-compiler.json and ask to reconfigure or abort.
Codebase Step 2: Auto-detect everything
Scan the project root and build a complete picture in one pass:
-
Detect project type by looking for manifest files:
package.json→ Node.js/TypeScriptgo.mod→ GoCargo.toml→ Rustpyproject.toml/requirements.txt→ PythonGemfile→ Ruby*.sln→ .NETPackage.swift→ Swiftpom.xml/build.gradle→ Java/Kotlin- Multiple manifests in subdirectories → Monorepo
-
Discover topic candidates:
- Monorepo: each directory with its own manifest = a topic
- Single project: major subdirectories under
src/,lib/,app/, or root = topics - Cross-cutting topics:
infrastructure(if Docker/CI exists),testing(if test dirs exist),deployment(if k8s/deploy scripts exist)
-
Count knowledge files matching default patterns:
README.md,CLAUDE.md,ARCHITECTURE.md,CONTRIBUTING.md*.proto,*.graphql,openapi.*ADR-*.md,docs/adr/*.mddocker-compose.yml,DockerfileCHANGELOG.md,.env.example
-
Auto-detect project name from
package.jsonnamefield,go.modmodule name, directory name, or git remote.
Codebase Step 3: One confirmation prompt
Present everything in a single confirmation:
📚 I see a {project_type} project with {N} modules and {M} knowledge files.
Topics: {topic1}, {topic2}, {topic3}, ...
Sections: Purpose, Architecture, Talks To, API Surface, Data, Key Decisions, Gotchas
Output: wiki/
A) Looks good — create config and compile now (recommended)
B) Customize — let me adjust topics, sections, or settings
C) Not now
If A: create config (Codebase Step 4) and immediately run /wiki-compile.
If B: fall through to the standard interactive flow (Step 2 onwards) but with codebase defaults pre-filled.
If C: exit.
Codebase Step 4: Create configuration
Write .wiki-compiler.json:
{
"version": 2,
"mode": "codebase",
"name": "{auto_detected_name}",
"sources": [
{ "path": "./", "exclude": ["node_modules/", "dist/", ".git/", "wiki/", "vendor/", "__pycache__/", ".build/", "target/", ".next/", "coverage/"] }
],
"output": "wiki/",
"service_discovery": "auto",
"knowledge_files": [
"README.md", "CLAUDE.md", "AGENTS.md", "ARCHITECTURE.md", "CONTRIBUTING.md",
"*.proto", "*.graphql", "openapi.yaml", "openapi.json",
"ADR-*.md", "docs/adr/*.md",
"docker-compose.yml", "Dockerfile",
".env.example", "CHANGELOG.md"
],
"deep_scan": false,
"auto_update": "prompt",
"article_sections": [
{ "name": "Purpose", "description": "What this module/service does and who depends on it", "required": true },
{ "name": "Architecture", "description": "Key files, structure, entry points" },
{ "name": "Talks To", "description": "Dependencies, communication patterns, inter-service calls" },
{ "name": "API Surface", "description": "Endpoints, exported functions, or interfaces exposed" },
{ "name": "Data", "description": "Tables, collections, queues, caches, state owned" },
{ "name": "Key Decisions", "description": "Why it was built this way, from ADRs and READMEs" },
{ "name": "Gotchas", "description": "Known issues, edge cases, failure modes" },
{ "name": "Sources", "description": "Backlinks to all contributing files", "required": true }
],
"link_style": "markdown"
}
Codebase Step 5: Create output directory and compile
- Create
wiki/,wiki/topics/,wiki/concepts/directories - Create empty
wiki/.compile-state.json - Create empty
wiki/log.md - Run the wiki-compiler skill (all 6 phases including CONTEXT.md generation)
- Show the first-compile summary with topic tree
Codebase Step 6: Done
📚 Wiki compiled — {N} topics from {M} files
Topics created:
├── {topic1} ({count} sources) — {one-line description}
├── {topic2} ({count} sources) — {one-line description}
└── {topic3} ({count} sources) — {one-line description}
Concepts discovered:
└── {concept1} — {description}
Browse: wiki/INDEX.md
Navigation guide: wiki/CONTEXT.md
Want me to add a reference to wiki/CONTEXT.md in your CLAUDE.md?
Knowledge Mode (--knowledge or auto-detected)
Step 1: Check for existing config
Look for .wiki-compiler.json in the current project root. If it exists:
You already have a wiki configured for "{name}" ({topic_count} topics, last compiled {date}).
A) Reconfigure from scratch
B) Keep current setup (abort)
If B, exit. If A, continue.
Step 2: Welcome + auto-detect
Scan the project for markdown-heavy directories. Look for:
- Directories named
Knowledge/,docs/,notes/,content/,meetings/,research/ - Any directory containing 10+
.mdfiles - Exclude:
node_modules/,.git/,wiki/,build/,dist/
Present findings conversationally:
Welcome to LLM Wiki Compiler. I'll get you set up in about 5 questions.
I found {count} markdown files across your project:
{dir1}/ — {count} files
{dir2}/ — {count} files
{dir3}/ — {count} files
Which directories should I compile into your wiki?
A) All of the above (recommended)
B) Let me pick — show me the list
C) I'll type the paths myself
Wait for response. If B, show checkboxes. If C, ask for paths.
Step 3: Name
Got it, {count} directories selected. What should I call this knowledge base?
A) "{auto_detected_name}" (based on your project name)
B) Let me type a name
Wait for response.
Step 4: Output location
Where should the compiled wiki live?
A) {first_source}/wiki/ (recommended — keeps it near your sources)
B) docs/wiki/
C) Let me pick a different path
Wait for response.
Step 5: Sample files and propose article structure
Now read 10-15 representative .md files from the confirmed source directories:
- Pick files from different subdirectories for breadth
- Read the first ~500 characters + the title (first
#heading) of each - Note what kinds of content you're seeing
Based on what you found, generate 5-8 article sections that fit the domain. Then present:
I sampled {N} of your files. Looks like you have {description of content types}.
Here's the article structure I'd suggest for your wiki:
1. Summary — standalone briefing of the topic
2. {section} — {description}
3. {section} — {description}
4. {section} — {description}
5. {section} — {description}
6. Sources — backlinks to all contributing files
A) Looks good, use this (recommended)
B) I want to add or remove sections
C) Regenerate — try a different structure
If B, ask which sections to add/remove/rename. If C, regenerate with different emphasis.
Rules for section generation:
- Always include
Summaryfirst andSourceslast — these are universal - Middle sections are domain-specific — match the actual content patterns observed
- Examples of what the LLM might propose by domain:
- Product/growth: Timeline, Current State, Key Decisions, Experiments & Results, Gotchas, Open Questions
- Research: Key Findings, Methodology, Evidence, Gaps & Contradictions, Open Questions
- Personal journal: Themes & Patterns, Progress, Reflections, Action Items
- Book notes: Characters, Themes, Plot Threads, Connections, Quotes
- Technical docs: Architecture, API Surface, Dependencies, Known Issues, Migration Notes
- Business/team: Stakeholders, Decisions, Action Items, Meeting History, Open Threads
Step 6: Wiki mode
Almost done. How should the wiki integrate with your workflow?
A) Staging — wiki supplements your existing setup, no changes needed (recommended for first-time)
B) Recommended — Claude reads wiki before raw files
C) Primary — wiki is the main knowledge source, raw files only for detail
You can change this anytime in .wiki-compiler.json.
Wait for response.
Step 7: Stale detection
Last question. Want me to warn you when your wiki is out of date?
If source files change after a compile, the plugin can flag it at session start:
"Wiki may be stale — 12 files changed. Run /wiki-compile to update."
A) Yes, warn me (recommended)
B) No thanks, I'll compile manually
If A, set auto_update to "prompt". If B, set to "off".
Step 8: Create configuration
Write .wiki-compiler.json to the project root:
{
"version": 1,
"name": "{name}",
"sources": [
{ "path": "{path1}/", "exclude": ["wiki/"] },
{ "path": "{path2}/" }
],
"output": "{output_path}/",
"mode": "{selected_mode}",
"auto_update": "{selected_auto_update}",
"article_sections": [
{ "name": "Summary", "description": "{description}", "required": true },
{ "name": "{section2}", "description": "{description}" },
{ "name": "{section3}", "description": "{description}" },
{ "name": "{section4}", "description": "{description}" },
{ "name": "{section5}", "description": "{description}" },
{ "name": "Sources", "description": "backlinks to all contributing source files", "required": true }
],
"topic_hints": [],
"link_style": "obsidian"
}
Step 9: Create output directory
Create:
{output}/directory{output}/topics/directory{output}/.compile-state.jsonwith initial empty state{output}/compile-log.mdwith initial empty log
Step 10: Done
Wiki initialized for "{name}"
Sources: {count} directories, ~{file_count} markdown files
Output: {output_path}
Structure: {section_count} sections ({section names})
Mode: {mode}
Stale warnings: {on/off}
Next steps:
1. Run /wiki-compile to build your first compilation (5-10 min)
2. Open {output_path}/INDEX.md in Obsidian to browse
3. After compiling, run /wiki-migrate to switch your AGENTS.md to wiki-first
Edit .wiki-compiler.json anytime to adjust settings.
Lint Knowledge Base Wiki
Run health checks on the compiled wiki to find issues.
Instructions
-
Read configuration from
.wiki-compiler.json. If not found, tell the user to run/wiki-initfirst. -
Read the wiki state:
- Read
{output}/INDEX.mdfor current topics - Read
{output}/schema.mdfor expected structure (if exists) - Read
{output}/.compile-state.jsonfor last compilation state
- Read
-
Run these checks:
Check 1: Stale Articles
Compare source file modification dates against .compile-state.json. Flag topics whose sources have changed since last compile.
Check 2: Orphan Pages
Check each wiki article's Sources section. Flag articles where:
- Source files no longer exist (were deleted or moved)
- Article has 0 sources listed
Check 3: Missing Cross-References
For each pair of topics, count shared sources. If two topics share 3+ sources but neither references the other, suggest a cross-reference.
Check 4: Low Coverage Sections
Scan all articles for [coverage: low] tags. List them as improvement candidates -- these sections should either be expanded with more sources or flagged as known gaps.
Check 5: Contradictions
Compare key facts across articles. Look for:
- Different dates for the same event in different articles
- Conflicting metrics (e.g., "D1 is 17.5%" in one article, "D1 is 13.3%" in another)
- Decisions described differently across topics
Check 6: Schema Drift
If schema.md exists:
- Topics in
topics/directory not listed in schema.md - Topics listed in schema.md that don't have a corresponding article
- Article sections that don't match the schema's Article Structure
- Output a summary:
Wiki Lint: "{name}"
──────────────────────────
Stale: {N} topics (sources changed since last compile)
Orphans: {N} articles with missing sources
Cross-refs: {N} missing links suggested
Low coverage: {N} sections across {N} topics
Contradictions: {N} found
Schema drift: {N} mismatches
{Details for each finding, grouped by check}
-
Suggest fixes:
- Stale topics: "Run
/wiki-compileto refresh" - Orphans: "Source was deleted -- recompile to remove stale references"
- Cross-refs: "Consider adding a reference to [[topic-b]] in topic-a's Summary"
- Contradictions: "Check {source1} vs {source2} for the correct value"
- Schema drift: "Add {topic} to schema.md" or "Remove {topic} from schema.md"
- Stale topics: "Run
-
Log the lint run by appending to
{output}/log.md:
### {date} — Lint
- Stale: {N}, Orphans: {N}, Cross-refs: {N}, Low: {N}, Contradictions: {N}, Drift: {N}
Migrate to Wiki-First Startup
One-time migration command. Analyzes your AGENTS.md or CLAUDE.md session startup sequence and shows which raw file reads can be replaced by wiki articles.
Instructions
Step 1: Validate
- Read
.wiki-compiler.json— if not found, tell the user to run/wiki-initfirst - Check that the wiki has been compiled at least once (INDEX.md and topic articles exist)
- If not compiled, tell the user to run
/wiki-compilefirst
Step 2: Find startup instructions
Look for session startup instructions in this order:
AGENTS.mdin the project rootCLAUDE.mdin the project root- Any file referenced by
CLAUDE.mdthat contains startup/context loading instructions
Identify the section that lists files to read at session start. Look for patterns like:
- "Read these files", "Session Startup", "Before doing any work, read..."
- Numbered lists of file paths with descriptions
- References to context files, knowledge bases, or startup sequences
Step 3: Map raw files to wiki topics
For each file listed in the startup sequence:
- Read the wiki INDEX.md to get the list of topics
- For each raw file, check if its content is covered by a wiki topic:
- Match by filename appearing in a topic's Sources section
- Match by content overlap (the raw file's key terms appearing in a topic article)
- Check the coverage level of the relevant topic sections
Step 4: Present the coverage report
Wiki Migration Report for {project name}
Current startup: {N} file reads
✅ {filename} → covered by {topic} [coverage: high]
✅ {filename} → covered by {topic} [coverage: high]
⚠️ {filename} → partially covered by {topic} [coverage: medium]
→ Check raw source for: {what's missing}
⚠️ {filename} → partially covered by {topic} [coverage: low]
→ Read raw source directly for granular detail
❌ {filename} → not covered by any wiki topic
→ Keep this in startup, or /wiki-ingest to add it
Summary: {covered}/{total} reads can be replaced by wiki
Estimated token savings: ~{old_tokens} → ~{new_tokens} ({reduction}% reduction)
Step 5: Generate replacement startup block
Based on the report, generate a replacement startup section that:
- Reads wiki INDEX.md first
- Lists relevant topic articles by work area
- Keeps any ❌ items as direct file reads (operational rules, checklists)
- Includes coverage-based fallback instructions
Present the replacement block to the user:
Here's a suggested replacement for your startup section:
---
{generated startup block}
---
Want me to apply this? (I'll only edit the startup section — everything else stays the same.)
Step 6: Apply (with confirmation)
Only if the user confirms:
- Replace the startup section in AGENTS.md or CLAUDE.md
- Keep everything outside the startup section unchanged
- Show a diff of what changed
Never auto-apply. The user must explicitly confirm before any file is modified.
Arguments
- No arguments: analyzes and reports
--apply: skip the confirmation prompt and apply immediately (for scripting)--dry-run: just show the report, don't offer to apply
Query Knowledge Base Wiki
Search the compiled wiki to answer a question. Faster and cheaper than reading raw source files.
Arguments
The user's question is passed as $ARGUMENTS. Example: /wiki-query what do we know about retention?
Instructions
-
Read configuration from
.wiki-compiler.json. If not found, tell user to run/wiki-init. -
Read INDEX.md from the configured output directory to see all available topics.
-
Read schema.md if it exists -- check for cross-reference rules that might point to related topics.
-
Identify relevant topics -- based on the user's question, select 1-3 topic articles most likely to contain the answer.
-
Read the selected topic articles from
{output}/topics/. -
Answer the question with:
- Specific facts, dates, and decisions from the wiki articles
- Citations in the format:
(from: {topic name} > {section}) - If the wiki doesn't have enough detail, point the user to specific raw source files from the article's Sources section
-
Keep it concise -- the user wants an answer, not a summary of every article you read.
-
Offer to file the answer -- if the answer synthesizes information in a useful way that isn't already in a wiki article, ask:
"This answer connects information across topics. Want me to file it into the wiki? (y/n)"
If yes:
- Append the synthesis to the most relevant topic article (add a new subsection or expand an existing section)
- Add a note:
*Filed from query on {date}* - Log it in
{output}/log.md:### {date} -- Query Filed - Question: "{question}" - Filed to: {topic-slug} > {section}
If the answer doesn't add new synthesis (just restated what's already in the article), skip the filing offer.
If no wiki exists
If INDEX.md doesn't exist or the wiki hasn't been compiled yet:
Wiki not compiled yet. Run /wiki-compile first, then try your query again.
Search the Wiki
Search across all wiki articles for keywords, phrases, or topics.
Instructions
Step 1: Validate
- Read
.wiki-compiler.jsonfrom the project root (or nearest parent directory). If not found, tell the user to run/wiki-initfirst. - Accept a search query as argument (e.g.,
/wiki-search retention experiments) - If no argument provided, ask: "What are you looking for?"
Step 2: Search strategy
Use a two-tier search approach:
Tier 1 — Index scan (fast, try this first):
- Read
{output}/INDEX.md - Check topic names and one-line summaries for keyword matches
- This is usually sufficient for "which topic covers X?" questions
Tier 2 — Full article search (when Tier 1 isn't enough):
- Use Grep to search across all files in
{output}/topics/and{output}/concepts/for the search terms - Return matching sections with context — include the section heading (
##) and surrounding lines so the user can see the match in context - Search both topic articles and concept articles
Step 3: Present results
Format results clearly:
Found {N} matches for "{query}":
### Topics
- **{topic-name}** [coverage: {level}] — {matching excerpt}
→ {output}/topics/{slug}.md
### Concepts
- **{concept-name}** — {matching excerpt}
→ {output}/concepts/{slug}.md
Include coverage indicators so the user knows whether to trust the wiki excerpt or read raw sources.
If no matches found:
- Suggest related topics that might be relevant
- Recommend
/wiki-queryfor synthesis questions that require connecting multiple topics - Suggest
/wiki-ingestif the user thinks the knowledge should be in the wiki but isn't
Step 4: Offer next steps
Based on results:
- "Want me to read the full article on {topic}?"
- "Want to ask a deeper question? Try
/wiki-query {your question}" - If search reveals a gap: "This area has low coverage. Want to
/wiki-ingesta source to improve it?"
Arguments
- Search query as argument (can be multiple words)
- No arguments: prompts user to specify what they're looking for
Notes
This is a keyword/grep-based search designed to work at any scale without external dependencies. For large wikis (100+ topics) that need semantic search, consider adding qmd as an MCP server for hybrid BM25/vector search with LLM re-ranking.
Upgrade Wiki Compiler Plugin
Update the plugin to the latest version from GitHub.
Instructions
-
Find the plugin source directory by running:
find ~/.claude/plugins -name "llm-wiki-compiler" -type d 2>/dev/null | head -1 -
Pull the latest changes:
cd {plugin_directory} && git pull origin main -
Show what changed by reading the git log:
git log --oneline -5 -
Tell the user to restart Claude Code for the changes to take effect:
Updated to latest version. Restart Claude Code to load the new commands and hooks.
What's new: {list the new commits since their previous version}
If git pull fails
If the plugin was installed from marketplace (not a git clone), tell the user:
Run: claude plugin update llm-wiki-compiler
Then restart Claude Code.
Visualize Wiki Knowledge Graph
Launch an interactive canvas-based knowledge graph of your compiled wiki. Topics appear as nodes, concepts as connecting edges. Click any node to read the article.
Instructions
-
Check that
.wiki-compiler.jsonexists in the project root -
Check that the wiki has been compiled (output directory has
INDEX.md) -
If not compiled, suggest running
/wiki-compilefirst -
Start the visualization server:
node "${CLAUDE_PLUGIN_ROOT}/visualize/server.js" --wiki-dir "{output_path}" -
Open the browser:
open "http://localhost:3848" -
Tell the user:
📊 Wiki Knowledge Graph running at http://localhost:3848 - Click nodes to read topic articles - Hover edges to see concept connections - Search to filter topics - The server reads your wiki files live — changes from /wiki-compile appear immediately Stop with Ctrl+C when done.
Arguments
- (none) — launch visualization for current project's wiki
--port {number}— use a custom port (default: 3848)
Hooks 1
Sponsors
Details
- Marketplace
- ussumant/llm-wiki-compiler
- Source
- plugin
- Author
- Sumant
- Category
- Community