qmd

name	qmd
description	Set up and manage qmd search index for faster vault search. Subcommands: setup, embed, status, reindex, uninstall. Use when the user wants to configure, update, or troubleshoot the qmd search index itself. Do NOT use for: performing a search (call qmd tools directly), general vault operations, or installing OneBrain (use onboarding or update).

qmd Search Integration

qmd is an optional local search engine that indexes your vault for fast keyword and semantic search. When active, the agent uses it automatically for vault-wide searches.

Usage: /qmd <subcommand>

Available subcommands: setup, embed, status, reindex, uninstall

If no subcommand is given, show this help and list available subcommands.

---

/qmd setup

Set up qmd for this vault. Creates a collection, stores it in vault.yml, and runs an initial index.

Step 1: Confirm intent

Ask using AskUserQuestion:

• question: "Set up qmd for faster vault search?"
• header: "qmd Setup"
• multiSelect: false
• options:
  • label: "Yes, set up qmd", description: "Index this vault with qmd for faster search"
  • label: "Cancel", description: "Skip qmd setup"

If user selects Cancel, stop.

Step 2: Check for existing setup

Read vault.yml. If qmd_collection key is already present:

qmd is already configured for this vault (collection: <value>). To reconfigure, run /qmd uninstall first, then /qmd setup again.

Stop.

Step 3: Check qmd installation

Run: which qmd (macOS/Linux) or where qmd (Windows).

If qmd is NOT found:

Ask using AskUserQuestion:

• question: "qmd is not installed. Install it now?"
• header: "Install qmd"
• multiSelect: false
• options:
  • label: "Yes, install with npm", description: "Run: npm install -g @tobilu/qmd"
  • label: "Yes, install with bun", description: "Run: bun install -g @tobilu/qmd"
  • label: "Cancel", description: "Skip for now : install manually later"

If Cancel: tell user "You can install qmd manually with npm install -g @tobilu/qmd, then run /qmd setup again." Stop.

If npm: run npm install -g @tobilu/qmd. If it fails, show the error and stop. If bun: run bun install -g @tobilu/qmd. If it fails, show the error and stop.

After installation, verify with which qmd (macOS/Linux) or where qmd (Windows). If still not found, tell user to check their PATH and stop.

Step 4: Generate collection name

node is reliably on PATH because the OneBrain CLI requires it — calling node -e "…" works without per-platform branching from Bash, PowerShell, and Git Bash. (Native cmd.exe needs care: %VAR% is still expanded inside double quotes, so a vault path containing a literal % will be substituted away. If the active shell is cmd, run the command through bash -c or PowerShell instead.)

1. Get vault root directory name (replaces basename, which is not available on Windows):

   node -e "console.log(require('path').basename(process.cwd()))"
   

2. Generate a 6-character random hex string (replaces openssl rand -hex 3 and python3 -c …secrets.token_hex…, neither of which is on default Windows PATH):

   node -e "console.log(require('crypto').randomBytes(3).toString('hex'))"
   

   If node itself cannot be invoked (rare — would mean the CLI is not actually installed), tell the user "Could not generate a unique collection name. Please run /qmd setup again." and stop.
3. Collection name = <vault-dirname>-<hex> (e.g., onebrain-a3f2c1)

Step 5: Create the qmd collection

Run:

qmd collection add <vault-root-path> --name <collection-name> --ignore ".obsidian/**" --ignore ".claude/**" --ignore ".git/**" --ignore "docs/**" --ignore "<archive-folder>/**" --ignore "attachments/**"

Where <vault-root-path> is the value of $CLAUDE_PROJECT_DIR and <archive-folder> is [archive_folder].

If the command fails, show the error and stop.

Step 6: Add context description

Run:

qmd context add "qmd://<collection-name>" "Personal Obsidian knowledge vault : notes, projects, areas, resources, and session logs"

If this command fails, report the error but continue (context is optional metadata).

Step 7: Store collection name in vault.yml

Read vault.yml. Add qmd_collection: <collection-name> as a top-level key before the folders: block. Write the full updated vault.yml back.

Example of updated vault.yml:

qmd_collection: onebrain-a3f2c1
folders:
  inbox: 00-inbox
  ...

If the write fails, show the error. Tell the user to manually add qmd_collection: <collection-name> to vault.yml. Stop.

Step 8: Run initial index and register hook

onebrain qmd-reindex

Then register the PostToolUse hook so the index stays in sync automatically (run from vault root):

onebrain register-hooks --qmd

If the reindex fails, show the error : the collection is created but not indexed. User can run /qmd reindex to retry.

Step 9: Confirm completion

Say: ────────────────────────────────────────────────────────────── 🗄️ qmd — Search Index Ready ────────────────────────────────────────────────────────────── Collection: {collection-name} Documents indexed: {N} Embeddings: {ready / not yet — run /qmd embed to enable semantic search}

→ qmd will auto-update whenever files change in this vault → Run /qmd embed for semantic/similarity search (optional) → Run /qmd status to check index health → Run /qmd uninstall to remove qmd integration

---

/qmd embed

Generate vector embeddings for semantic search.

Step 1: Check prerequisites

Read vault.yml. If qmd_collection key is missing: 🔴 qmd not configured — run /qmd setup to enable vault search.

Stop.

Check that qmd is on PATH (which qmd on Bash, where qmd on cmd, Get-Command qmd on PowerShell). If not found:

qmd is not installed. Run /qmd setup to install and configure it.

Stop.

Step 2: Warn about time

Ask using AskUserQuestion:

• question: "Generating embeddings for the first time may take several minutes depending on vault size. This runs locally : no data leaves your machine. Continue?"
• header: "Generate Embeddings"
• multiSelect: false
• options:
  • label: "Yes, generate embeddings", description: "Run qmd embed : may take a few minutes for large vaults"
  • label: "Cancel", description: "Skip for now"

If Cancel, stop.

Step 3: Run embed

Run:

qmd embed -c <collection-name>

Where <collection-name> is read from vault.yml qmd_collection.

Report completion or any errors.

Step 4: Confirm

Say: ✅ Embeddings generated. Semantic search now active — use natural language queries.

---

/qmd status

Show collection info and index health.

Step 1: Check prerequisites

Read vault.yml for qmd_collection. If missing: 🔴 qmd not configured — run /qmd setup to enable vault search.

Stop.

Check that qmd is on PATH (which qmd on Bash, where qmd on cmd, Get-Command qmd on PowerShell). If not found: 🔴 qmd binary not found — run /qmd setup to reinstall.

Stop.

Step 2: Run status

Run:

qmd collection list

Show the output to the user. Highlight the line for the vault's collection name.

---

/qmd reindex

Force a full BM25 reindex of the vault collection.

Step 1: Check prerequisites

Read vault.yml for qmd_collection. If missing: 🔴 qmd not configured — run /qmd setup to enable vault search.

Stop.

Check that qmd is on PATH (which qmd on Bash, where qmd on cmd, Get-Command qmd on PowerShell). If not found:

qmd is not installed. Run /qmd setup to install and configure it.

Stop.

Step 2: Run update

onebrain qmd-reindex

Report progress and any errors.

Step 3: Confirm

Say:

Index updated. All vault notes are now searchable.

---

/qmd uninstall

Remove qmd integration from this vault. Does not uninstall the qmd binary.

Step 1: Check prerequisites

Read vault.yml. If qmd_collection key is missing:

qmd is not configured for this vault. Nothing to uninstall.

Stop.

Step 2: Confirm

Ask using AskUserQuestion:

• question: "Remove qmd integration from this vault?"
• header: "Confirm"
• multiSelect: false
• options:
  • label: "Yes, remove qmd", description: "Removes the collection and disables qmd search for this vault. Does not uninstall qmd itself."
  • label: "Cancel", description: "Keep qmd as-is"

If Cancel, stop.

Step 3: Remove collection from qmd

Read qmd_collection from vault.yml. Run:

qmd collection remove <collection-name>

If qmd is not installed or the command fails, report the error but continue to Step 4 (still need to clean vault.yml).

Step 4: Remove qmd_collection from vault.yml

Read vault.yml. Remove the qmd_collection: ... line. Write the full updated vault.yml back.

If the write fails, show the error. Tell the user to manually remove the qmd_collection line from vault.yml.

Step 4b: Remove PostToolUse hook from settings.json

onebrain register-hooks --remove-qmd

Run from vault root. This removes the onebrain qmd-reindex PostToolUse hook that was registered during /qmd setup. If the hook is not present, the script exits cleanly.

Step 5: Confirm

Say:

qmd search disabled for this vault. The agent will use standard Glob/Grep/Read search.

You can re-enable anytime with /qmd setup.

---

Known Gotchas

• qmd not found after setup. If qmd installs successfully but subsequent calls fail with "command not found", the binary may be in a PATH that is set in .zshrc but not active in the Claude Code session. The fix is already documented in the setup flow — add the path to .claude/settings.json env config. Remind the user to run /doctor to verify after setup.

• qmd embed must be run after setup before searches return semantic results. qmd setup registers the collection but does not create embeddings. The first search after setup returns lexical-only results until qmd embed completes.

• qmd_collection value in vault.yml must exactly match the collection name used during setup. A mismatch causes all qmd tool calls to silently fail (wrong collection). Verify with qmd status after changing the value.