← All guides AI Release
RU Subscribe to @ai_release1

How to Set Up QMD for Coding Agents and Cut Token Usage on File Search

Updated: 16.11.2026 · AI Release · @ai_release1
How to Set Up QMD for Coding Agents and Cut Token Usage on File Search

TL;DR

Requirements and setup

Illustration: Requirements and setup
Illustration: Requirements and setup

Example: in a typical Node project the generated directories are node_modules/ and dist/; in a Python project they are .venv/ and __pycache__/. These are the directories you will exclude in Step 2, because indexing them inflates the index and returns files the agent should never open.

If you want semantic (meaning-based) search instead of symbol-based search, that is a different toolchain — see local semantic file search with Rummage and EmbeddingGemma 2. QMD is used here as the fast path-lookup layer in front of your agent's file reads.

Step 1. Measure the baseline: how many bytes your agent burns on file search

What to do: record three numbers for one repository before changing anything — tracked file count, total repository text size, and the number of bytes a naive search returns for one real query.

Why: without a baseline you cannot claim a token reduction, and token spend is proportional to the bytes your agent pulls into context.

How to check: run these commands from the repository root and write the outputs into a scratch file.

cd ~/projects/<your-repo>
git ls-files | wc -l
git ls-files -z | xargs -0 cat | wc -c
rg -n "createCheckout" --glob '!node_modules' | wc -c

Example output (your numbers will differ):

1842
7341002
41208

The third number is the important one: it is the byte volume the agent ingests when it greps a common symbol across the tree without any index. A rough token estimate is characters ÷ 4; treat it as an estimate only, and for exact counts use the tokenizer of the model you actually run.

Example: if rg -n "createCheckout" | wc -c returns 41208, the naive path costs roughly 10k tokens of context before the agent has read a single function body.

Save the numbers:

printf 'files=%s\ntotal_bytes=%s\nquery_bytes=%s\n' \
  "$(git ls-files | wc -l)" \
  "$(git ls-files -z | xargs -0 cat | wc -c)" \
  "$(rg -n "createCheckout" | wc -c)" > .qmd-baseline.txt
cat .qmd-baseline.txt

Why this works: .qmd-baseline.txt is a fixed reference you re-read in Step 3, so the before/after comparison uses identical commands and an identical query.

Step 2. Build the index and give the agent a single search entry point

Illustration: Step 2. Build the index and give the agent a single search entry point
Illustration: Step 2. Build the index and give the agent a single search entry point

What to do: create the QMD index for the repository, restrict it to tracked and hand-written files, then replace the agent's habit of "grep everything, then read everything" with one wrapper command and one written rule.

Why: agents burn tokens because they search broadly and read whole files. An index returns a short list of paths; a written rule stops the agent from ignoring that list. The wrapper also gives you one stable contract, so a QMD upgrade does not require rewriting your agent instructions.

How to check: qfind "createCheckout" returns at most five paths and no file bodies.

First, create the wrapper:

mkdir -p ~/bin
cat > ~/bin/qfind <<'EOF'
#!/usr/bin/env bash
# ~/bin/qfind — the only file-search entry point the agent may use.
# The QMD subcommand and flags below vary by build: run `qmd --help`
# and check the documentation before the first run.
set -euo pipefail

QUERY="${1:?usage: qfind <symbol-or-phrase>}"
LIMIT="${2:-5}"

qmd search "$QUERY" --limit "$LIMIT" --format paths
EOF
chmod +x ~/bin/qfind

If your build exposes a differently named subcommand (for example a query-style command instead of a search-style one), change that single line — check the documentation. The agent-facing contract stays qfind "<query>".

Second, write the index configuration. The field names below are a skeleton; confirm each one against the documentation for your installed version.

# qmd.config.yaml — skeleton. Field names are version-dependent: check the documentation.
index:
  root: .
  exclude:
    - node_modules/
    - dist/
    - .venv/
    - vendor/
  respect_gitignore: true

Third, index the repository:

cd ~/projects/<your-repo>
qmd index            # flags for incremental vs full reindex: check the documentation
qfind "createCheckout"

Example: the expected output is a short list, not code:

src/checkout/createCheckout.ts
src/checkout/createCheckout.test.ts
src/api/routes/checkout.ts

Fourth, encode the rule in the file your agent reads at startup (AGENTS.md, or the equivalent instruction file your agent supports):

## File search rules
- Do not run `grep -r` or `rg` across the whole repository.
- Call `qfind "<symbol>"` first; it returns at most 5 paths.
- Open only the returned paths and read at most 80 lines around the match.
- If `qfind` returns nothing, print the query and ask before falling back to `rg`.

The 5 and 80 values are your policy choices, not QMD defaults — pick numbers that match how much context your model handles comfortably.

Example: with the rule in place, the same question that previously produced a 41,208-byte grep now produces three paths, and the agent opens one file and reads 80 lines instead of reading the whole src/ tree.

Keep secrets out of the index before you run the first build: exclude .env, key material and credential dumps, and treat every indexed file as readable by the agent. The general checklist is in AI agent security: protecting your data during automation.

Step 3. Verify the reduction and keep the index fresh

Illustration: Step 3. Verify the reduction and keep the index fresh
Illustration: Step 3. Verify the reduction and keep the index fresh

What to do: re-run the exact Step 1 query through qfind, measure the returned bytes, compute the ratio, and automate reindexing so results never go stale.

Why: an index that lags behind HEAD returns deleted files and dead symbols, which costs more tokens than no index at all.

How to check: the byte count for the same query must be far below the Step 1 number, and the index timestamp must be newer than your last commit.

cd ~/projects/<your-repo>
time qfind "createCheckout" | tee /tmp/qmd.out | wc -c
head -5 /tmp/qmd.out

Example output:

412
src/checkout/createCheckout.ts
src/checkout/createCheckout.test.ts
src/api/routes/checkout.ts

Fill in the comparison table with your own measurements — the arithmetic is baseline ÷ after:

MetricBaseline (Step 1)After (Step 3)Ratio
Files in repository`<n>``<n>`—
Bytes returned for one symbol query`<n1>``<n2>``<n1>/<n2>`
Files the agent actually opens`<n>``<n>`—

Automate the refresh with a post-commit hook:

cat > .git/hooks/post-commit <<'EOF'
#!/usr/bin/env bash
# Reindex after every commit. Exact flags: check the documentation.
qmd index --update || echo "qmd reindex failed; agent results may be stale" >&2
EOF
chmod +x .git/hooks/post-commit

Confirm it fires:

git commit --allow-empty -m "test qmd hook"

Success looks like a clean commit with no qmd reindex failed line on stderr. If your build has no incremental flag, call the full index command in the hook instead — check the documentation.

Example: after the hook runs, qfind "createCheckout" on a branch where the file was renamed must return the new path only. If the old path still appears, the update did not complete.

Token savings are only half the budget story; set hard ceilings so a runaway agent cannot spend the difference — see How to set spending limits and budgets for AI agents.

Troubleshooting

Problem. The wrapper is not found when the agent runs it

Problem. The wrapper exists but will not execute

Problem. Indexing fails or produces an empty index

Summary and next steps

You now have a measured baseline, an excluded-directory index behind one qfind entry point, and a post-commit hook that keeps results current. Next, run the same baseline measurement on your second-largest repository and compare the ratios before rolling the AGENTS.md rules out to the rest of the team.

FAQ

What is QMD in one sentence?

QMD is the file-search and indexing layer you place in front of a coding agent so it receives a short list of paths instead of dumping raw file contents into context; the exact CLI surface differs by build, so check the documentation for your version.

Does QMD replace ripgrep?

No. rg stays useful for the baseline measurement and as a deliberate fallback when qfind returns nothing; the rule is that the agent must ask before using the fallback, not that ripgrep is removed.

Which directories should I exclude from the index?

Generated and vendored directories: node_modules/, dist/, .venv/, vendor/, plus any file holding secrets such as .env or key material. Excluding them keeps the index small and stops the agent from opening files nobody should edit.

How do I keep the index fresh across branches and machines?

Reindex on every commit with the post-commit hook from Step 3, and reindex after switching branches with a long diff. Confirm freshness by querying a symbol you just renamed — the old path must not appear in the output.

🤖 AI summary

AI Release Knowledge Layer
Machine-readable description · Version 1.0

Status: practical guide. Some statements come from vendors; verify in your environment.

1. Summary

Time to complete: 30–45 minutes Difficulty: Intermediate

Inside: direct answers, key facts, entities, context, reliability, unknowns and sources.

Machine data: Citation Map JSON · JSON-LD · Semantic Embeddings — separate stage.

Full Knowledge Layer: sections 2–8

2. Direct answers

What is required?
OS and shell. Linux or macOS with bash 4+; on Windows use WSL2. Verify: bash --version prints GNU bash, version 5.x or newer.; git. Your project must be a git repository, because the cheapest way to bound the index is to index tracked files only. Verify: git rev-parse --show-toplevel prints the repo root.; QMD… → details (AR-GUIDE-KAKNASTROI-003)
How to do it?
Step 1. Measure the baseline: how many bytes your agent burns on file search → Step 2. Build the index and give the agent a single search entry point → Step 3. Verify the reduction and keep the index fresh → details (AR-GUIDE-KAKNASTROI-004)
Which topics does it cover?
QMD для кодинг-агентов, как настроить QMD, экономия токенов ИИ-агента → details (AR-GUIDE-KAKNASTROI-002)
What are the key points?
Time to complete: 30–45 minutes Difficulty: Intermediate → details (AR-GUIDE-KAKNASTROI-007)

3. Key facts

  1. Time to complete: 30–45 minutes — evidence; status: заявление источника.
  2. Difficulty: Intermediate — evidence; status: заявление источника.
  3. You need: Linux or macOS (Windows via WSL2), bash 4+, git, rg (ripgrep) for the baseline measurement, one repository you can index, and a coding agent that can execute shell commands. QMD must be installed and resolvable on PATH. This guide does not pin a QMD version: every QMD-specific subcommand, flag or config field is marked check the documentation — run qmd --help and confirm the exact spelling for your build before you type it. — evidence; status: заявление источника.
  4. OS and shell. Linux or macOS with bash 4+; on Windows use WSL2. Verify: bash --version prints GNU bash, version 5.x or newer. — evidence; status: заявление источника.
  5. git. Your project must be a git repository, because the cheapest way to bound the index is to index tracked files only. Verify: git rev-parse --show-toplevel prints the repo root. — evidence; status: заявление источника.
  6. QMD installed and on PATH. Verify: qmd --version. If you get command not found, add the install directory to PATH (see Troubleshooting, case 1). The install command and supported version are check the documentation. — evidence; status: заявление источника.

4. Entities

EntityTypeRole
QMD для кодинг-агентовтема/инструментупоминается в заголовке, TL;DR или разделах гайда
как настроить QMDтема/инструментупоминается в заголовке, TL;DR или разделах гайда
экономия токенов ИИ-агентатема/инструментупоминается в заголовке, TL;DR или разделах гайда
Windowsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Linuxплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
macOSплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Gitплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Claudeтема/инструментупоминается в заголовке, TL;DR или разделах гайда

5. Context

  • Guide — describes → How to Set Up QMD for Coding Agents and Cut Token Usage on File Search (AR-GUIDE-KAKNASTROI-001).
  • Guide — includes step → Step 1. Measure the baseline: how many bytes your agent burns on file search (AR-GUIDE-KAKNASTROI-001).

6. Reliability

Confirmed

No independent confirmation is provided; source claims and editorial conclusions are separated below.

Source claims

  • Product features, versions, prices and limits come from vendors and the guide.
  • Commands and steps are recommendations, not guaranteed results.

AI Release analysis

  • Structure, comparison and selection criteria are editorial.
  • The guide does not replace an independent audit or legal advice.

7. Unknowns

  • Current versions, prices and limits.
  • Independent benchmarks and quality checks.
  • Terms of use and data policy.

8. Sources

SourceTypeRole
No external links——

Cite as: AI Release. Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов. ai-release.org.