qmd: codebase indexing for Claude Code

qmd is a local document indexer that creates a searchable index of your codebase and exposes it as an MCP server. Instead of Claude exploring files with Glob/Grep/Read on every query — spending 80–90% of the token budget on navigation — qmd returns ranked snippets so Claude reads only what is relevant.

Real-world token reduction examples:

Task	Without qmd	With qmd	Reduction
Find auth logic	2,700 tokens	250 tokens	91%
Fix checkout bug	3,950 tokens	400 tokens	90%
Understand DB schema	6,050 tokens	400 tokens	93%

---

Installation

sudo npm install -g @tobilu/qmd

---

Indexing a collection

Register a project directory as a named collection:

qmd collection add /mnt/onedrive/github/LAB/traderapp/streamlit/traderapp \
  --name traderapp \
  --mask '**/*.{md,py}'

• --name — short identifier used when searching
• --mask — glob pattern to include only relevant file types (omit to index everything)

---

Building the index

After adding collections, generate embeddings:

qmd embed --chunk-strategy auto

--chunk-strategy auto lets qmd choose the best chunking method per file type. Re-run this after files change, or use qmd update to refresh incrementally.

Check index status:

qmd status

---

MCP server setup

Add qmd as an MCP server in ~/.claude/mcp.json:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Restart Claude Code after editing this file.

---

Instructing Claude and Codex to use qmd

The recommended approach is to add a rule directly to your project’s CLAUDE.md (for Claude Code) and AGENTS.md (for Codex). This makes qmd usage automatic for every session in that project — no manual invocation required.

Add this block to both files:

## Rule: always use qmd before reading files
 
Before reading files or exploring directories, always use qmd to search for information in local projects.
 
### QMD execution policy (important)
 
- Run all `qmd` commands with escalated permissions (`sandbox_permissions: require_escalated`).
- Do not run `qmd` in sandbox first.
- Reason: `qmd` needs write access to `~/.cache/qmd/index.sqlite` and related cache files, which may be read-only in sandbox.
- If escalation is not yet approved, request it immediately with a short justification before continuing.
 
Available tools:
 
- `qmd search -c tradingapp "query"` — fast keyword search (BM25)
- `qmd query -c tradingapp "query"` — hybrid search with reranking (best quality)
- `qmd vsearch -c tradingapp "query"` — semantic vector search
- `qmd get -c tradingapp <file>` — retrieve a specific document
 
Use qmd search for quick lookups and qmd query for complex questions.
Run qmd commands directly (for example `qmd search "..."`) and do not prefix with `XDG_CACHE_HOME` or other environment-variable overrides unless explicitly requested by the user.
Use Read/Glob only if qmd doesn't return enough results.

---

Search commands

Command	Description	When to use
search	BM25 keyword search	Default — fastest, ~80% of queries
vsearch	Vector similarity search	Conceptually related content, imprecise terms
query	Hybrid search with LLM reranking	Best quality, slower
get	Retrieve a specific document section	When you know the exact file/chunk

Example:

qmd search "authentication middleware"

---

Keeping the index current

qmd update                       # Incremental refresh (only changed files)
qmd embed --chunk-strategy auto  # Full re-index

Run qmd update after significant code changes or as a pre-session habit. Use qmd embed --chunk-strategy auto when re-indexing from scratch — it lets qmd pick the best chunking method per file type.