A Claude Code hook that grades MarkItDown's output instead of trusting its exit code

[Andrew Avery (AndrewAvery7)]

I've been using MarkItDown as the document layer for an AI coding assistant, and wanted to share both the integration and the one thing that took me longest to understand — in case it saves someone else the same afternoon.

The setup. Claude Code reads PDFs by rendering every page as an image, which is slow and expensive, and it can't read .docx/.xlsx/.pptx at all. So: convert with MarkItDown first, then hand the assistant a pointer to the .md rather than its contents. It reads or greps the file only if the content turns out to matter. Referencing a 200-page PDF costs ~400 characters until someone actually needs page 140.

The thing that took me longest. My first version trusted the exit code:

$ markitdown screenshot.pdf -o out.md
$ echo $?
0
$ wc -c out.md
0 out.md

That is correct behaviour and I want to be precise about it — a browser screenshot saved as PDF has raster images and no text layer, pdfminer reports 0 characters, and MarkItDown's PDF backend extracts embedded text rather than OCR-ing. There was genuinely nothing to find, and finding nothing isn't an error.

The bug was entirely mine: I treated exit code as evidence of yield. The assistant got an empty file that had been reported as converted, and told the user their document was blank. Confidently. That's the worst possible failure for a document pipeline, because there's no signal anything went wrong.

What fixed it was scoring every conversion on what it actually recovered. For PDFs the useful measure turned out to be characters per page — raw byte count conflates document length with extraction quality, but density doesn't:

Document	Pages	Chars	Chars/page	Verdict
Webpage screenshot saved as PDF	1	0	0	rejected
Course certificate (graphic + title)	1	39	39	rejected
Two-page text document	2	1,864	932	converted
Twenty-page slide deck	20	13,289	664	converted

Two populations, no overlap, an order of magnitude apart. A threshold of 100 sits between them with roughly 6× margin either side. Below it, nothing is written and nothing is cached — the assistant is told the document is image-based and pointed at its own vision instead.

One detail that generalises to anyone building on MarkItDown: the density test should be PDF-only. A one-line email, a ten-second voice memo and a four-cell spreadsheet all legitimately convert to very little. Only PDFs have the specific failure of a text extractor meeting a picture. Applying a density floor everywhere looks consistent and quietly discards good conversions.

Repo (MIT, Windows/macOS/Linux): https://github.com/AndrewAvery7/claude-markitdown-hook

Happy to answer anything about the threshold — the measurements behind it are in docs/DESIGN.md.