Generic qmd semantic search: per-project setup interview, smart search across collections, guard hooks for qmd-first workflow
- version
- 2.0.1
- GitHub stars
- 39
Install
/plugin install qmd@claude-code-in-avinycRun it inside Claude Code after adding the marketplace with /plugin marketplace add aviflombaum/claude-code-in-avinyc.
Contents
Discovered from sourceSkills 4
QMD Configure
Interactive interview to set up or reconfigure qmd collections for a project. Idempotent: works for both first-time setup and reconfiguration.
Run this flow step by step. Do NOT skip steps or assume answers.
Step 1: Check qmd is installed
command -v qmd
If missing, tell the user:
qmd is not installed. Install it with:
npm install -g @tobilu/qmd
Then STOP.
Step 2: Check qmd MCP server
The search skill uses qmd's MCP tools for best performance (models stay warm between queries). Check if the MCP server is configured:
cat .mcp.json 2>/dev/null | grep -q '"qmd"' && echo "found in project" || echo "not in project"
If not configured, tell the user:
qmd MCP server is not configured. Add it for the best search experience.
Option 1 — CLI (recommended):
claude mcp add qmd -- qmd mcpOption 2 — Manual: Add to
.mcp.jsonin the project root:{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }The search skill will fall back to CLI if MCP isn't available, but MCP is significantly faster for repeated queries.
Continue with setup regardless — MCP is recommended but not required.
Step 3: Derive project name
Get the git repo folder name and normalize it:
basename "$(git rev-parse --show-toplevel)" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//'
Show the derived name to the user via AskUserQuestion. Let them confirm or type a custom name. Once confirmed, this is the canonical project name used for all collection prefixes.
Step 4: Scan for indexable directories
Find directories containing markdown files:
find . -maxdepth 2 -type f -name "*.md" -exec dirname {} \; | sort -u
From the output, select only directories useful for a searchable document collection (docs/, plans/, tasks/, etc.). Ignore tmp/, vendor/, node_modules/, and other project cruft.
Step 5: Ask which directories to index
Use AskUserQuestion with multiSelect: true. List indexable directories as options. Explain that each directory becomes a qmd collection for fast semantic search.
If no candidate directories were found, ask the user to type custom directory paths.
Step 6: Get collection details
For each selected directory, use AskUserQuestion to:
- Ask for a short description of what the directory contains (e.g., "Project architecture and feature docs")
- Confirm the file pattern (default:
**/*.md, offer alternatives like**/*.{md,txt})
Step 7: Add collections
For each selected directory, derive the collection name: {project}_{dirname} where dirname has / and . replaced with _ and leading dots stripped. Example: .cursor/rules → cursor_rules, so collection is myproject_cursor_rules.
Get the absolute path to the directory:
echo "$(git rev-parse --show-toplevel)/<dirname>"
Then add the collection:
qmd collection add "<absolute_path>" --name "<collection_name>" --mask "<pattern>"
qmd context add "qmd://<collection_name>/" "<description>"
If qmd collection add fails (collection already exists), ask the user whether to overwrite. If yes:
qmd collection remove "<collection_name>"
qmd collection add "<absolute_path>" --name "<collection_name>" --mask "<pattern>"
qmd context add "qmd://<collection_name>/" "<description>"
Step 8: Write project config
Use the Write tool to create .claude/qmd.json:
{
"project": "<project_name>",
"collections": {
"<project>_<dirname>": {
"path": "<relative-dir-path>",
"pattern": "**/*.md",
"description": "<user-provided description>"
}
},
"gitHook": false
}
Step 9: Generate embeddings
qmd update && qmd embed
Tell the user it's generating embeddings. This may take a moment for large collections.
Step 10: Ask about git post-commit hook
Use AskUserQuestion: "Install a git post-commit hook? When enabled, committing changes to .md files will automatically re-index in the background so search results stay fresh."
Options: "Yes, install hook" / "No, skip"
If yes, install the hook by appending to .git/hooks/post-commit (create the file if needed, ensure it's executable):
# qmd-auto-index:<project_name>
# Auto-update qmd index when markdown files change
export PATH="$HOME/.bun/bin:$HOME/.local/bin:$PATH"
if command -v qmd &>/dev/null; then
if git diff-tree --no-commit-id --name-only -r HEAD | grep -q '\.md$'; then
(qmd update && qmd embed) &>/dev/null &
fi
fi
Check for the marker comment # qmd-auto-index:<project_name> first to avoid duplicates. Update .claude/qmd.json to set "gitHook": true.
Step 11: Print summary
Show the user:
- Project name
- Collections created (name, path, description)
- MCP server: configured/not configured
- Git hook: installed/not installed
- How to search:
/avinyc:qmd-search <query> - How to reconfigure:
/avinyc:qmd-configure - How to check status:
/avinyc:qmd-status - How to diagnose issues:
/avinyc:qmd-doctor
QMD Doctor
Run a comprehensive health check on the qmd configuration for this project. Perform each check below in order and report results as [PASS], [FAIL], or [WARN]. At the end, summarize the total number of issues found.
Remediation Reference
For any failure, suggest the appropriate fix:
| Failure | Fix |
|---|---|
| qmd binary not found | npm install -g @tobilu/qmd |
| .claude/qmd.json missing | Run /avinyc:qmd-configure |
| Missing project field | Run /avinyc:qmd-configure |
| Collection not in qmd index | Run /avinyc:qmd-configure |
| Collection naming mismatch | Run /avinyc:qmd-configure to rename |
| Git hook missing/wrong marker | Run /avinyc:qmd-configure and re-enable git hook |
| Git hook has old --index flag | Run /avinyc:qmd-configure and re-enable git hook |
| MCP server not responding | Run claude mcp add qmd -- qmd mcp or add qmd to .mcp.json |
| YAML config missing collection | Run /avinyc:qmd-configure |
Checks
1. qmd binary
command -v qmd
[PASS] if found (print the path), [FAIL] if not.
2. Config file exists
Check if .claude/qmd.json exists using Read. If it does not exist, report [FAIL] and stop — remaining checks depend on it.
3. Valid JSON
Read .claude/qmd.json. If you can parse it as JSON, [PASS]. If the content is malformed, [FAIL] and stop.
4. Has "project" field
Check the parsed JSON has a non-empty project string. [PASS] or [FAIL].
5. Default index database
test -f "$HOME/.cache/qmd/index.sqlite" && echo "exists" || echo "missing"
[PASS] if exists, [FAIL] if missing.
6. Global config
test -f "$HOME/.config/qmd/index.yml" && echo "exists" || echo "missing"
[PASS] if exists, [FAIL] if missing.
7-9. Collection checks
For each key in the collections object:
7. Collection in qmd index:
qmd collection list
Check if the collection name appears in the output. [PASS] or [FAIL].
8. Naming convention: If the project name is set, check that the collection name starts with {project}_. [PASS] or [WARN].
9. YAML config entries
If ~/.config/qmd/index.yml exists, check that each collection name appears in it:
grep -F "{collection_name}:" "$HOME/.config/qmd/index.yml"
[PASS] or [FAIL] per collection.
10-11. Git hook checks (only if gitHook is true)
10. Check .git/hooks/post-commit exists. If it does, verify it contains the marker comment # qmd-auto-index:{project}. [PASS], [WARN] (marker mismatch), or [FAIL] (missing).
11. Check the hook does NOT contain the deprecated --index flag. [PASS] or [WARN].
12. MCP server connectivity
Try calling mcp__qmd__status. If it returns data, [PASS]. If the tool is not available or returns an error, [WARN] with message:
MCP server not configured or not responding. Search will fall back to CLI. Run
claude mcp add qmd -- qmd mcpor add qmd to.mcp.json.
Output Format
Print each result on its own line:
[PASS] qmd binary found: /path/to/qmd
[PASS] .claude/qmd.json exists
[PASS] .claude/qmd.json is valid JSON
[PASS] Project name: myproject
[FAIL] Default index database missing: ~/.cache/qmd/index.sqlite
[WARN] MCP server not configured — search will use CLI fallback
...
N issue(s) found.
If all checks pass, end with: All checks passed.
QMD Search
Search your project's indexed markdown documentation using qmd's MCP tools. This skill reads your project's qmd configuration to know which collections to search, constructs structured queries, and retrieves relevant documents.
Step 1: Read Config
Read .claude/qmd.json from the project root.
If missing, tell the user:
qmd is not configured for this project. Run
/avinyc:qmd-configureto set it up.
Then STOP.
Extract project name and collections — each has a name, path, and description. Pick the best collection for the query by matching against descriptions. If only one collection exists, use it.
Step 2: Search via MCP
Use the mcp__qmd__query tool with a structured query. This is the primary search method — it's faster than CLI (models stay warm between queries) and supports multi-type queries with intent disambiguation.
Constructing the Query
Every search should include at least two query types for best recall. The first query gets 2x weight in fusion scoring, so put your best guess first.
{
"searches": [
{ "type": "lex", "query": "2-5 exact keywords, no filler" },
{ "type": "vec", "query": "full natural language question" }
],
"collections": ["<collection_name>"],
"limit": 10
}
Query Types
| Type | Method | When to use | Writing tips |
|---|---|---|---|
lex | BM25 keyword | You know the exact terms in the docs | 2-5 terms. Exact phrases: "rate limiter". Exclude: -sports. Code identifiers work. |
vec | Vector semantic | You don't know the vocabulary | Full question. Be specific: "how does the auth system handle session expiry?" |
hyde | Hypothetical doc | Complex topic, you can imagine the answer | Write 50-100 words of what the answer looks like, using vocabulary you expect in the result. |
When to Use What
| Situation | Query types to include |
|---|---|
| Know exact terms | lex only |
| Don't know vocabulary | vec only |
| Best recall | lex + vec |
| Complex or broad topic | lex + vec + hyde |
| Ambiguous query (e.g., "performance" could mean web perf, team health, etc.) | Any combination + intent |
Intent Disambiguation
When a query term is ambiguous, add intent to steer all pipeline stages (expansion, reranking, snippet extraction):
{
"searches": [
{ "type": "lex", "query": "performance" },
{ "type": "vec", "query": "how to improve page load speed" }
],
"intent": "web page load times and Core Web Vitals",
"collections": ["project_docs"],
"limit": 10
}
Intent does not search on its own — it's a steering signal that disambiguates what you mean.
Step 3: Interpret Results
Results include docid, score, file, title, context, and snippet.
| Score | Meaning |
|---|---|
| 0.7+ | Highly relevant — read this document |
| 0.5–0.7 | Worth reading if topic matches |
| < 0.5 on all | Try different query types or refine |
Step 4: Retrieve Documents
To read a full document from the results, use mcp__qmd__get:
{ "file": "#docid" }
Or by file path:
{ "file": "collection_name/path/to/file.md" }
For multiple related documents, use mcp__qmd__multi_get to batch retrieve:
{ "pattern": "collection_name/docs/*.md" }
This is faster than reading files one at a time.
Error Handling
If MCP tools fail, diagnose the issue:
| Error | Likely cause | Fix |
|---|---|---|
mcp__qmd__query not available | MCP server not configured | Run claude mcp add qmd -- qmd mcp or add qmd to .mcp.json. Run /avinyc:qmd-configure. |
| MCP call returns error | Server not running or crashed | Run qmd mcp to verify. Check qmd status. |
| Collection not found | Config out of sync | Run /avinyc:qmd-doctor to diagnose. |
| No results | Index empty or stale | Run qmd update && qmd embed to rebuild. |
CLI Fallback
If MCP tools are unavailable, fall back to the CLI. The qmd query command supports structured queries via multiline strings:
qmd query $'lex: exact keywords here\nvec: natural language question here' -c <collection> --json -n 10
This single command subsumes qmd search (BM25 only) and qmd vsearch (vector only). Always use --json for parseable output.
Fallback to Glob/Grep
After 2 poor query attempts (different query types, refined terms), fall back to Glob/Grep on the collection's directory path from config. qmd can't find everything — sometimes a direct file search is faster.
QMD Status
Show the project's qmd configuration alongside live index health.
Step 1: Read project config
Read .claude/qmd.json. If missing, tell the user:
qmd is not configured for this project. Run
/avinyc:qmd-configureto set it up.
Print a summary:
- Project name
- Collections (name, path, description for each)
- Git hook: installed/not installed
Step 2: Get live index status
Try mcp__qmd__status first (fastest, returns structured data). If MCP is unavailable, fall back to CLI:
qmd status
Display the live status alongside the project config. Key things to highlight:
- Total documents indexed per collection
- Embedding status (how many chunks have vectors)
- Any collections in config that are missing from the index
- Model info (which embedding/reranker models are loaded)
Step 3: MCP connectivity
Report whether MCP tools are available. If not, suggest:
MCP server not configured. Run
claude mcp add qmd -- qmd mcpor add qmd to.mcp.jsonfor faster searches.
Sponsors
Details
- Marketplace
- aviflombaum/claude-code-in-avinyc
- Source
- plugins/qmd
- Author
- Avi Flombaum
- Category
- Community
- License
- MIT
