WatsonTsai

PDF Text Router — Development skill for Claude Code

Development community

A Claude Code hook that routes each Read on a PDF to the path that actually works: text layer to UTF-8 text, scans to vision, and neither one through poppler.

How to install PDF Text Router

This entry records only its repository, not the path inside it, so there is no exact command to give. Open WatsonTsai/pdf-text-router and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What PDF Text Router does

A Claude Code hook that routes each Read on a PDF to the path that actually works: text layer to UTF-8 text, scans to vision, and neither one through poppler.

Alternatives in Development

Product Vision — Brainstorm inspiring, achievable product vision statements 7.8k ★
Diagnose Seq Scans — Remedy high seq scans on a table 7.2k ★
Setup Video Vision — Interactive setup wizard for claude-video-vision — configure backend, whisper, frames, and verify dependencies 1.3k ★

README

pdf-text-router

A Claude Code hook that routes each `Read` on a PDF to the path that actually works.

English · [繁體中文](README.zh-TW.md)

You ask Claude Code to read a PDF. Nothing errors. Claude quietly switches to some other method — a `Bash` one-liner, a guess from the filename — or tells you the file could not be opened. What actually happened underneath is `pdftoppm is not installed`, and you never saw it, because Read errors are not surfaced in the TUI ([#23699](https://github.com/anthropics/claude-code/issues/23699), closed as stale). Any PDF over ten pages, and any Read with a page range, goes through poppler's `pdftoppm`, and the official setup docs have never said so ([#23704](https://github.com/anthropics/claude-code/issues/23704), open). Even when poppler *is* there, a PDF with a real text layer is being read as pictures of words.

**What you get instead.** For a PDF with a text layer, the hook rewrites the Read in place: one `Read`, and what comes back is a UTF-8 `.txt` with `[page N/M]` markers, so Claude can still cite pages, `Grep` the file, and never runs an OCR pass over text that was already text. No poppler involved. For a scan, the hook lets the native path through when it works, and when it would fail for want of poppler it renders the pages locally, points the same Read at the first PNG and lists the rest.

**What it costs.** The extracted text is cached in plain text under `~/.claude/pdf-text-cache`. The PDF was already a readable file on the same machine, so the cache adds exposure in one situation only: the PDF lives on an encrypted volume, an external drive or a network share, and the cache lands in your home directory. For that case, `PDF_TEXT_ROUTER_CACHE=beside` keeps the cache next to the PDF, or point the variable at a directory of your own choosing; there is no encrypted mode (see [Cache](#design-notes)). Slide decks are the biggest saving and also the biggest trap: text drawn inside a figure — station names on a map, a scale bar,