mdlens is a Markdown retrieval CLI for AI agents.

The headline command is mdlens scout: give it a directory and a natural-language question, and it returns a bounded evidence pack with likely files, section IDs, highlights, table/context snippets, and enough structure for one precise follow-up read.

mdlens scout docs/ "Which config option controls authentication timeout?" --max-tokens 1400

scout is meant to replace the common agent pattern of find, rg, cat, and large raw file reads when the target corpus is Markdown. It works over arbitrary English Markdown collections: READMEs, runbooks, model cards, generated docs, experiment logs, tables, stale notes, and multi-file policy docs.

Agent Integration

For AGENTS.md, CLAUDE.md, plugin docs, system prompts, or tool routers, add:

When answering questions over Markdown files or documentation directories, consider using `mdlens`.
If `mdlens` is available and you need command guidance, run `mdlens --help` once.
For question answering over a Markdown directory, prefer:
  mdlens scout <dir> "<question>" --max-tokens 1400
Answer from `[highlights]` and `[evidence]` when sufficient.
If exactly one detail is missing, use the section map from `[files]`:
  mdlens read <file> --id <section-id> --max-tokens 1200
Avoid reading whole Markdown files unless scout clearly found the wrong file.
Preserve exact short source terms such as flags, IDs, option names, metrics, table values, and policy phrases.

Detailed guidance lives in mdlens --help and mdlens scout --help, so harness prompts can stay short while future agents can still discover the workflow.

Commands

scout should be the first call for natural-language QA, multi-file comparison, stale/current checks, table lookup, and policy/rationale questions.

The other commands are digging tools:

Examples:

mdlens read docs/guide.md --id 1.2 --max-tokens 1200
mdlens search docs/ "rate limit"
mdlens tree docs/
rg -nH "rate limit" docs/ | mdlens sections --preview 3 --max-sections 8

All commands support --json for machine-readable output. For scout, JSON includes schema_version, query expansions, selected candidates, and the same rendered evidence pack in rendered_text.

Evals

Important caveat: this eval is entirely Markdown QA/search. It is not a claim about broad coding-agent performance, even though Markdown QA is a common part of coding-agent work. It measures whether agents answer from documentation with fewer irrelevant reads, fewer calls, lower cost, and better recall.

Public eval notes and locked question sets live in evals/. Corpora and raw model outputs are omitted from the public repo; the questions and methodology are included so readers can inspect the task shapes.

The final combined eval used 30 hard questions over 1,783 Markdown files from three corpora: messy generated/scene Markdown, a SciCat-style scientific README proxy, and codebase docs. Five questions are workflow-like cross-corpus analysis tasks, but none require code edits.

Reproducibility dataset: dreeseaw/mdlens-combined-markdown-v1.

Across the 15 harness/model pairs where both arms completed all rows:

Selected full runs:

Native Claude rows are documented in the local reports, but the Sonnet run hit provider/credit exit_1 failures late in the run and is treated as partial harness data rather than a clean model comparison.

Other eval families:

• messy_markdown_v1: 500 carefully curated synthetic Markdown files with malformed formatting, stale/current contradictions, copied distractors, multi-needle tables, and cross-file policy/rationale questions.
• scicat_markdown_v1: a SciCat-style scientific README proxy, with Hugging Face and GitHub scientific Markdown fallback material.
• codebase_markdown_v1: repository-doc navigation over real project docs, runbooks, design notes, and experiment reports.

The planned next step, if the project gets traction, is a small mock-workflow eval where each task combines Markdown analysis, a code edit, and JSON/data inspection in a fresh branch.

Installation

Requires Rust 1.70+.

cargo install mdlens

Or from source:

cargo install --git https://github.com/Dreeseaw/mdlens

Claude Code Plugin

mdlens also ships as a Claude Code plugin:

/plugin install mdlens

License

MIT. See LICENSE.

AI Disclosure

One of most intriguing aspects of this project was directly working with my end-user all along: the agents. I tried to take advantage of as many as I could to iterate quickly.

• Initial Planning & PRD: ChatGPT 5.5 medium
• Initial Implementation: Locally running Qwen3.6-27B-Q3-K-M
• Adversarial Reviews & Code Improvements: ChatGPT 5.4 high, Sonnet 4.6 xhigh, Qwen3.6-Plus, Kimi-K2.6, Minimax-M2.7
• Optimization loops: ChatGPT 5.5 high & Opus 4.7 high

The total cost of both the final evaluations & all the development evals were ~$90 from Opencode Zen + burning out my $20 Claude sub every 5 hours + upgrading to ChatGPT Max (I have a few other projects in mind anyway). Opencode made my iteration & optimization process extremely easy from an infra perspective, and ChatGPT 5.5 was excellent at minimizing spend when optimizing problems that were only pervasive towards a subset of questions/models/harnesses.