npx llm-wiki-skills init

🧠 Why This Exists

AI agents are useful until they forget the context you gave them last week. llm-wiki-skills gives them a local place to preserve what they learn:

| Before 😵 | After ✅ | | --- | --- | | Notes, PDFs, meeting docs, and decisions live in scattered files. | Sources stay in raw/, durable knowledge lands in wiki/, and agents know how to update it. | | Every session starts with "read these files again." | Codex or Claude Code can ingest, query, and lint the same local vault. | | Search depends on whatever the model happens to load. | Markdown stays canonical, with optional local qmd search acceleration. |

✨ Key Features

• 🤖 Agent-native: installs skills for Codex and Claude Code, not just docs for humans.
• 🏠 Local-first: no hosted memory service, no remote database, no required account.
• 📎 Source-grounded: raw evidence and synthesized wiki pages stay separate.
• 📦 OKF-compatible: new vaults are OKF v0.1 bundles with a root index, log, and concept-page metadata.
• 🧩 Custom-format markdown conversion: convert PDF, DOCX, PPTX, XLSX, XLS, HTML, HTM, EPUB, PNG, JPG, JPEG, WEBP, TIF, TIFF, and BMP files into markdown during ingest planning when Marker is installed.
• 🗂️ Topic-aware: choose a scaffold for research, product work, trips, investing, medical notes, legal/admin records, and more.
• 🌐 Web-only graph atlas: visualize, search, and read your wiki in a browser. Obsidian is optional, not required.
• 🚢 Static deploy: export the atlas as plain web assets for GitHub Pages, Netlify, Vercel, or any static host.
• 🔎 QMD search: optional qmd support adds local SQLite-backed hybrid search while markdown remains the source of truth.

🚀 Getting Started

⚡ 1. npx (Recommended)

Run the setup wizard in any repo or markdown workspace:

npx llm-wiki-skills init

The wizard asks which agent host to install, which topic scaffold to use, and whether to prepare the folder as an Obsidian vault.

For a non-interactive Codex setup:

npx llm-wiki-skills init --host codex --topic product-builder

Common flags:

| Flag | Use it when | | --- | --- | | --host codex | Install Codex repo skills under .agents/skills/. | | --host claude-code | Install Claude Code project skills under .claude/skills/. | | --topic work-project | Add topic directories and routing guidance. | | --obsidian / --no-obsidian | Enable or skip Obsidian vault metadata. | | --qmd | Add optional local qmd search support. | | --json / --quiet | Use in scripts or CI. |

📦 2. Global npm install

npm install -g llm-wiki-skills
llm-wiki-skills init

Then check the install:

npx llm-wiki-skills status

🛠️ Installation

Use it directly with npx:

npx llm-wiki-skills init

Or install it globally:

npm install -g llm-wiki-skills
llm-wiki-skills init

Requirements:

• Node.js 22 or newer.
• Codex or Claude Code if you want an agent to use the generated skills.
• Obsidian is optional. The web UI can visualize the wiki by itself.
• A project folder or markdown vault where local files can be created.

🤖 Non-interactive installation supported

npx llm-wiki-skills init --host codex --topic product-builder

Common flags:

| Flag | Use it when | | --- | --- | | --host codex | Install Codex repo skills under .agents/skills/. | | --host claude-code | Install Claude Code project skills under .claude/skills/. | | --topic work-project | Add topic directories and routing guidance. | | --obsidian / --no-obsidian | Enable or skip Obsidian vault metadata. | | --qmd | Add optional local qmd search support. | | --json / --quiet | Use in scripts or CI. |

🧭 Usage

🤖 Ask Your Agent to Use the Wiki

After setup, use the installed skills in your agent:

Use the llm-wiki-ingest skill. Ingest raw/sources/customer-notes.md
into the wiki and update any overlapping pages.

Use the llm-wiki-query skill. What do we know about onboarding friction?
Cite the wiki pages you used.

Use the llm-wiki-lint skill. Find stale claims, contradictions,
or missing cross-references before handoff.

🌐 Open or Deploy the Web UI

The web UI is web-only: it lets you inspect the wiki graph in a browser and does not require Obsidian.

Run locally:

npx llm-wiki-skills web serve --root .

By default this serves the atlas at http://127.0.0.1:3678/. Assign a custom port when needed:

npx llm-wiki-skills web serve --root . --port 4000

Build for remote deploy:

npx llm-wiki-skills web build --root . --out dist/atlas

Then upload dist/atlas to any static web host. The export includes the graph, search index, page content, and diagnostics needed by the browser UI.

📋 Plan Larger Ingests

For bigger raw folders, create a batch plan first:

npx llm-wiki-skills ingest plan --raw raw/sources
npx llm-wiki-skills ingest converters status
npx llm-wiki-skills ingest status --plan PLAN_ID
npx llm-wiki-skills ingest validate --plan PLAN_ID

The ingest commands help track source files before your agent synthesizes them into wiki pages. PDF, DOCX, PPTX, and other Marker-supported raw files are converted to markdown by default when Marker is installed. Marker is an external Python/PyTorch tool and is not bundled with this MIT-licensed npm package; install it separately if you want multimedia conversion.

Ingest plans, converted markdown, and converted assets are written under .llm-wiki-skills/ingest-plans/, outside wiki/ so the wiki stays focused on durable knowledge. Source summaries should read converted markdown when present, but still cite the original raw/ path and SHA-256 from the plan.

When a source is marked merged, the CLI moves the raw file into raw/archieved/ and keeps the original raw path plus SHA-256 in the ingest plan for provenance. Future ingest plans skip everything under raw/archieved/, including when scanning --raw raw.

For best results, ask your AI agent to handle this workflow. The installed skills tell the agent when to use these commands.

🔁 Example Workflow

1. Drop source material into raw/sources/
2. Ask the agent to use llm-wiki-ingest
3. The agent handles the ingest workflow automatically
4. The agent writes source summaries and durable wiki pages
5. Ask questions with llm-wiki-query
6. Run llm-wiki-lint before important handoffs

A small demo vault is included at fixtures/demo-vault. Use it to inspect the expected shape before initializing your own workspace.

🗂️ Topic Vault Structure

Every vault starts with the same simple contract:

raw/                         preserved source material
wiki/                        durable markdown knowledge
docs/llm-wiki-contract.md    local wiki rules
docs/llm-wiki-workflows.md   ingest/query/lint workflow reference
.obsidian/                   optional Obsidian vault settings
.llm-wiki-skills.json        install manifest for status checks
.llm-wiki-skills/            CLI-owned ingest plans and converted intermediates

Topic scaffolds add useful wiki/ categories and a routing guide at docs/llm-wiki-routing.md.

| Topic 🗂️ | Best for | Example categories | | --- | --- | --- | | general | Mixed notes and broad research | projects, areas, resources, questions | | study-research | Papers, courses, experiments | concepts, papers, methods, datasets | | work-project | Delivery context and team knowledge | architecture, decisions, meetings, risks | | product-builder | Customer evidence and product bets | personas, problems, competitors, metrics | | writing-content | Essays, drafts, editorial research | audience, topics, claims, outlines | | trip-plan | Travel planning and bookings | destinations, hotels, transport, itinerary | | investment | Research, theses, watchlists | companies, valuation, catalysts, postmortems | | home-life | Household systems and records | maintenance, purchases, utilities, documents | | medical | Clinical study notes and references | conditions, diagnostics, drugs, guidelines | | legal-admin | Contracts, deadlines, admin records | matters, obligations, agencies, contacts | | custom | Anything else | starts from general plus your custom label |

Example:

npx llm-wiki-skills init --host codex --topic study-research

Creates a research-friendly vault like:

wiki/
|-- concepts/
|-- papers/
|-- methods/
|-- datasets/
|-- claims-and-evidence/
`-- templates/

🔎 qmd Search Support

qmd is optional and off by default. Enable it when your wiki is large enough that local hybrid search is useful:

npx llm-wiki-skills init --host codex --qmd
npx llm-wiki-skills qmd status
npx llm-wiki-skills qmd reindex

Markdown under wiki/ remains canonical. qmd is only used for local candidate discovery.

✅ What This Is / Is Not

| ✅ This is | 🚫 This is not | | --- | --- | | A local installer for agent wiki workflows. | A hosted memory service. | | A way to keep raw evidence and durable knowledge organized. | A replacement for reviewing source material. | | A bridge between markdown vaults, Codex, Claude Code, the web atlas, and optional Obsidian. | A full note-taking app or automatic importer. | | Optional local search acceleration through qmd. | A required cloud search backend. |