Drill into a PDF
with the cheapest
sufficient command.

01 — what it is

A flat CLI over a typed document model.

pdfdrill returns prose, never JSON, and persists what it learns in a sidecar next to each PDF — so a re-run answers instantly and a higher-level command never repeats a lower one. It wraps the heavy extraction tools so an LLM can reach for the cheapest command that still answers the question, escalating to OCR and the full document model only on demand.

There are five ways to drive it: the CLI itself; a drillui browser terminal for chatting with one drilled document; a stdio MCP server and a Streamable-HTTP MCP endpoint that hand drill results back as clickable resources inside Claude Desktop, Claude Code, or the claude.ai web custom connector; and a batch driver that walks a list of URLs or arXiv ids shallow→deep. Underneath, three packages do the work:

02 — the killer case

The link that no text stream can see.

A paper's page-1 text says only “Our code is available here.” — where here is a hyperlink with no separate anchor text. Plain extraction, MathPix Markdown, and a chatbot PDF upload all drop the annotation layer, so the URL simply does not exist in anything an LLM reads. pdfdrill links reads the annotation layer directly and surfaces it in ~50 ms.

$ pdfdrill links 2605.12061.pdf            # ~0.06 s · pure `pdfinfo -url`
Found 1 code/data host among external links:
  https://anonymous.4open.science/r/Unified-Representation-A9D9/  (page 1, no visible anchor text)

$ pdfdrill urls 2605.12061.pdf             # ~6 s · scans every page to recover anchor text
Same link re-derived — only reach for this when you need the visible text.

$ # MathPix / Markdown / chatbot upload: the link is gone — annotation layer never consulted.

03 — drill depth

Start shallow. Escalate only on demand.

Every command records facts in the sidecar, so a higher level never repeats a lower one. pdfdrill size is always step zero — free, ~40 ms, and it tells you whether the auto-extracted text is even enough.

$ pdfdrill size paper.pdf
18-page PDF, 0.2 MB, letter, produced by xdvipdfmx, has a text layer, not encrypted.

$ pdfdrill abstract paper.pdf
Abstract:

  For a finite planar set P, let ν(P) be the number of …

04 — command catalogue

One flat verb per job.

Run as PYTHONPATH=src python3 -m pdfdrill <command> <pdf> [args], or via the installed pdfdrill console script. Click a command to see what it returns.

05 — the qc pipeline

LaTeX · KaTeX · the image MathPix actually rendered.

MathPix lines.json is the only format that ships, for each equation, both the recognized LaTeX and the CDN crop it was read from. pdfdrill puts them side by side — and adds competing readings (MathPix Snip, an LLM on the crop, the author’s own .tex) as extra columns, each scored against a normalized LaTeX form. Below is a real row from report --embed on arXiv 2004.05631v1, eq (1.1):

LaTeX source	KaTeX render	MathPix CDN crop
a(x):=\{y \in Y \mid R(x, y)=1\} \quad b(y):=\{x \in X \mid R(x, y)=1\} snip 1.00 tex  0.99		crop URL · region 994×67 @ (259,666) · click → full page 12

Each crop’s <img> links to the full page it was cut from (page_url() strips the region query). --embed base64-inlines every crop so the artifact has no live-CDN dependency — ideal for a preview that won’t load remote images. The page click-through stays live even when embedded.

06 — live from the model

Real equations, rendered in your browser.

These are pulled verbatim from the extracted model of arXiv 2004.05631v1 (At the Interface of Algebra and Statistics) — the Galois connection at the heart of the thesis. Source LaTeX shown beneath each render; nothing was hand-typed.

07 — the document model

Every element is a typed, queryable node.

The unified docmodel resolves a paper into typed DocObjects. Projected to TiddlyWiki, each becomes one tiddler — equations carry their LaTeX, reference number, page, the MathPix crop, region geometry, and every competing reading as latex_<provenance> + score_<provenance>.

{
  "title": "2004.05631v1_EQ0001_p012",
  "text":  "<$latex text={{!!latex}} displayMode=true />",
  "tags":  "equation 2004.05631v1",
  "kind":  "Equation",
  "latex": "a(x):=\{y \in Y \mid R(x,y)=1\} …",
  "refnum":          "1.1",
  "equation_number": "(1.1)",
  "page":   "012",
  "canonical_uri": "https://cdn.mathpix.com/cropped/…-012.jpg?…",
  "width": "994", "height": "67",
  "top_left_x": "259", "top_left_y": "666",
  "latex_tex":  "a(x):=\{y\in Y\mid R(x,y)=1\}…",
  "score_tex":  "0.992",
  "latex_snip": "a(x):=\{y \in Y \mid …\}",
  "score_snip": "1"
}

08 — claude.ai & claude code

Nothing for you to install — just ask Claude.

You don’t run any of this yourself. Make pdfdrill available once — attach the bundle in a Claude.ai chat, or install the skill in Claude Code — then ask in plain language. Claude carries the skill (SKILL.md + the 89-command manifest), so it knows which commands to run, and it reads that manual — not you. The package is pure Python under src/ with no pip step, which is why the sandbox (the extraction tools and pydantic already aboard) runs it as-is. Everything in the terminal below is what Claude does for you — not a checklist you type.

you ▸ “Here’s pdfdrill (attached). Install it and load its skill, then tell me
       whether this paper’s equations extracted cleanly.”

# Claude — now holding the skill — does the rest. You watch; you don’t type any of this:
$ tar xzf pdfdrill.tgz                        # unpack the bundle you attached
$ cat src/pdfdrill/skill/SKILL.md            # the skill IS Claude’s manual — it reads this, you don’t
$ PYTHONPATH=src python3 -m pdfdrill size   paper.pdf
$ PYTHONPATH=src python3 -m pdfdrill report paper.pdf --embed   # → self-contained formula-report.html

# In Claude Code the skill is installed once, so step one is simply your question.
# (the attachable bundle is one `git archive --format=tar.gz HEAD` of the repo.)

09 — live artifacts

Open the real output.

All produced by pdfdrill and served straight from this repository — no build step, no server.

arXiv 2607.02234 · Purified OPSD: On-Policy Self-Distillation new · docmodel inspector

Transformer Circuits Thread · Verbalizable Representations Form a Global Workspace in Language Models new · distill reading view

arXiv 2004.05631v1 · At the Interface of Algebra and Statistics

bibkey heimUFT · Burkhard Heim — Unified Field Theory (study notes; derived model published with permission)

bibkey kolbe2018hubbard · Kolbe (2018) — Korrelation im Hubbard-Modell (German BA thesis, published with the author's permission)