Working with PDFs in Claude Code

Who this is for: Researchers whose core materials are PDFs — scanned sources, digitised books, journal articles, reports. This document covers how to read, summarise, extract, and batch-process PDFs in Claude Code, with no programming required.

Why PDFs in Claude Code, not Desktop

In Claude Desktop, PDF work means: upload, ask, copy output, repeat for every file. For more than two or three documents, this becomes the day's most tedious task.

In Claude Code, your PDFs sit on disk. You tell Claude where they are; Claude reads them. No uploading. No copy-pasting. If you have a folder of 40 PDFs, Claude can process all 40 in one instruction, and write the results to a file you can immediately use.

See A.issue.upload-dance for a fuller account of why this difference matters.

The basic pattern

> Read [filename.pdf] and [do something with it]

That is the entirety of the non-programmer's interface. Examples:

> Read montauban_1241.pdf and give me a 3-paragraph summary in English.

> Read this_article.pdf and list the main argument, the key evidence,
  and any methodological caveats the author raises.

> Read interview_17.pdf and extract everything the interviewee says
  about migration. Quote directly where possible.

Claude reads the PDF from disk and responds. The result appears in the terminal. To save it to a file:

> Read montauban_1241.pdf and write a summary to montauban_1241_summary.md

Claude creates montauban_1241_summary.md in your current folder.

Three ways Claude can read a PDF

Not all PDFs are equal, and not all reading approaches are equal. There are three distinct pathways, with different speed, accuracy, and effort tradeoffs. Knowing which to use saves time and avoids surprises.

Pathway 1: Direct reading (default)

Claude reads the PDF directly from disk when you type Read paper.pdf. This is dual-modal: every page is rasterized to an image and text is extracted simultaneously — Claude sees the page visually and reasons across both. Scanned PDFs with no text layer work through this path.

Hard limit: 100 pages / 20 MB. Exceeding either limit produces an explicit error. Pages are not silently dropped. For documents over 100 pages, ask Claude to read it in chunks using page ranges (see "Working with large PDFs" below).

Good for: Documents up to 100 pages, single- or multi-column layout, scanned PDFs, PDFs with charts and diagrams. Local files only — remote URLs are not supported.

Struggles with: Two-column academic papers where you want reliable markdown output for repeated use — direct reading works, but producing clean structured markdown from two-column layouts benefits from a conversion tool (Pathway 2). Very large batches where loading each full PDF consumes context window.

Pathway 1b: Remote PDFs and very long documents (native API)

For PDFs accessible via a URL rather than a local file, or for documents over 100 pages, the native Claude API document block is the alternative path. It uses the same dual-modal mechanism as the Read tool but supports remote sources and higher page limits.

Good for: PDFs at a URL (e.g. a repository link). Documents over 100 pages chunked via the API.

To use it, ask Claude:

> Read this PDF from this URL: [url]. Use the native API document block.

Pathway 2: Quick conversion to markdown first (pymupdf4llm)

Convert the PDFs to markdown before asking Claude to read them. The right tool for academic PDFs is pymupdf4llm — a Python library that extracts text using geometric layout analysis, so it correctly handles two-column journal layouts without scrambling the reading order. Claude reads the resulting markdown faster and more reliably than raw PDFs.

Why not markitdown? Microsoft's markitdown tool is excellent for converting DOCX, XLSX, PPTX, and HTML to markdown — and works adequately for single-column PDFs. But it uses a text-extraction backend that does not understand column geometry. For two-column academic papers (most journal articles), it interleaves the columns incorrectly and produces garbled output. For academic PDFs, use pymupdf4llm. For Word and Excel files, markitdown is fine — see A.markdown-central.

Good for: Any batch of academic articles, including two-column journal layouts. Processing the same documents repeatedly — convert once, read the markdown each time. Batches of 20+ files where direct reading would strain the context window.

The tradeoff: Conversion strips some visual information — images, equations, and very complex table layouts may need attention. For reading what a paper argues, this rarely matters.

To convert a folder, ask Claude:

> Convert all PDFs in the /papers/ folder to markdown using pymupdf4llm.
  Save each as [filename].md in the same folder.

Claude writes and runs this script for you — you don't need to understand the Python.

Pathway 3: Thorough conversion (for tables, equations, scanned pages)

For PDFs where precise structure matters — data tables you need to extract accurately, papers with equations, or image-only scans — the quick approach may lose important content. Two tools cover the main cases:

docling (free, MIT licensed, no GPU required): trained on scientific paper layouts, with a dedicated table model that correctly reconstructs merged cells, row/column spans, and nested headers. Also handles OCR for scanned pages. Best when your PDFs have data tables that matter.

marker-pdf --use_llm (free, GPL): adds a language model pass over extracted text to convert equations to LaTeX and clean up scientific typography. Requires an API key (Gemini Flash is cheap). Best when your PDFs contain mathematical notation.

Ask Claude to install and run either:

> Install docling and convert paper.pdf to markdown, preserving table structure.

> Install marker-pdf and convert paper.pdf using the --use_llm flag.

The official Anthropic pdf skill (document-skills bundle) offers a no-setup alternative — install once with /plugin install document-skills@anthropic-agent-skills — but it uses pdfplumber internally and shares the same column-layout limitations. Best suited for single-column sources.

Which pathway to choose

PDF type Task Use
Any local PDF, ≤100 pages Reading / summarising Direct reading (Pathway 1)
Scanned PDF (no text layer) Any Direct reading works — dual-modal (Pathway 1)
PDF at a URL Any Native API document block (Pathway 1b)
Academic articles (incl. two-column), batch use Structured markdown output pymupdf4llm → markdown (Pathway 2)
PDFs with data tables Structured data extraction docling (Pathway 3)
Scientific papers with equations Extraction with math marker-pdf --use_llm (Pathway 3)
Document over 100 pages Any Read in page-range chunks, or convert to markdown

Telling Claude which approach to use

By default, Claude uses the Read tool — dual-modal, up to 100 pages. For most PDFs under 100 pages, this is all you need. To get a different behaviour, ask explicitly:

Default (Pathway 1 — direct reading, local file, ≤100 pages):

> Read paper.pdf and summarise the main argument.

No extra instruction needed. Works for any local PDF up to 100 pages, including scanned documents.

Reading a specific page range (for documents over 100 pages):

> Read pages 1–80 of the_register.pdf and extract all named persons.

Then continue with the next chunk. Claude accepts page ranges when you specify them in your request.

Remote PDF (Pathway 1b — URL source):

> Read this PDF from this URL: [url]. Use the native API document block.

Quick conversion before reading (Pathway 2 — pymupdf4llm):

> Convert paper.pdf to markdown using pymupdf4llm, then read the markdown
  and summarise the argument.

For a whole folder:

> Convert all PDFs in this folder to markdown using pymupdf4llm.
  Save each as [filename].md in the same folder.

Then in subsequent requests, work with the .md files instead of the PDFs.

Thorough conversion (Pathway 3 — docling or marker):

> Convert paper.pdf to markdown using docling, preserving table structure,
  then extract all data tables from the result.

> Convert paper.pdf using marker-pdf with the --use_llm flag,
  then extract all equations in LaTeX format.

When to pre-convert your folder to markdown

Pre-converting PDFs to markdown (Pathway 2 or 3) has upfront cost — a few seconds per file — but pays back quickly. Convert first when any of these apply:

When direct reading is fine:

What Claude can and cannot read in a PDF

Can read:

Cannot read reliably:

Note on scanned PDFs: Because the Read tool is dual-modal (it sees the page as an image), it can handle many scanned documents directly — you do not always need to run OCR first. Try reading the scan directly; if the output is poor, then run OCR as a pre-processing step. Tools for OCR: Adobe Acrobat Pro (built-in), ABBYY FineReader, or the free OCRmyPDF (command-line).

Practical prompts for research use

Summarising a paper

> Read the_paper.pdf and write:
  1. Main argument (2 sentences)
  2. Key evidence and sources used
  3. Methods
  4. Relationship to debates in medieval religious history
  5. One critical question I might raise
  Save to the_paper_notes.md

First pass on an archival source

> Read source_register_1241.pdf
  It is in Latin. Please:
  1. Give me an overview of what it covers (2 paragraphs)
  2. List all named persons with folio/page references
  3. List all place names
  4. Note anything unusual — gaps, changes in hand visible in the text,
     interpolations
  Save to source_register_1241_firstpass.md

Extracting specific information

> Read deposition_guilhem.pdf
  Extract every mention of travel — where the person went, when, with whom.
  Format as a list of events, each with the direct quote and page number.

> Read the_report.pdf
  I am interested only in sections about funding and budget.
  Summarise those sections and ignore the rest.

Comparing two documents

> Read document_A.pdf and document_B.pdf
  These are two versions of the same text — one Latin, one Occitan.
  Compare them: what is added, omitted, or changed in the Occitan version?
  Focus on passages about penance and confession.

Generating a reading list annotation

> Read article.pdf and write a bibliographic annotation of 150 words
  suitable for a Zotero note, including: argument, methods, relevance
  to network analysis of medieval heresy.

Batch processing: multiple PDFs at once

This is where Claude Code becomes qualitatively different from Desktop.

One thing to know before you start: When processing many PDFs in a single session, Claude loads each file into its context window. If the combined text of all the files approaches the context limit, earlier files quietly drop out — Claude will continue working but may no longer have access to the first documents it read, without warning you. For large batches (20+ substantial PDFs), the quick conversion approach (Pathway 2 above) is safer: Claude reads lighter markdown files rather than full PDFs, and you can process more documents reliably before hitting limits.

Process all PDFs in a folder

> There are several PDF articles in this folder.
  For each one, read it and write:

  - Title (from the PDF itself)

  - Main argument (2 sentences)

  - Key methods
  Compile all into reading_notes.md, one section per article.

Extract structured data across a corpus

> I have deposition transcription PDFs in the /transcriptions/ folder.
  For each file, extract:

  - deponent_name

  - date (as given in the document)

  - location

  - inquisitor

  - persons mentioned (comma-separated)

  - charges (1 sentence)
  Output everything as extractions.csv
  If any field is unclear, write "unclear" and note why.

Filter a set of PDFs by content

> There are 25 PDFs in this folder.
  Read each one and tell me which ones discuss the topic of Waldensian
  communities in the Rhine valley. For those that do, give me the
  relevant passage(s) with page numbers.

Summarise a folder for a literature review

> Read all PDFs in /reading/montaillou_lit/
  Write a synthesis document: what are the main debates in this literature?
  What methodological approaches appear? What is missing?
  Save to literature_synthesis.md

Working with large PDFs

The Read tool handles up to 100 pages per call. Beyond that, you will get an explicit error. There is also a second limit to know about:

The context window limit: Once Claude has read a document (or many documents), the text sits in its context window. For very long documents or large batches, the total can approach the context limit — the amount Claude can hold in mind at once. At that point, earlier content quietly drops.

Signs you are hitting the context limit:

What to do with documents over 100 pages:

  1. Read in page-range chunks. Ask Claude to read a specific range, save the output, then continue with the next range: ```

    Read pages 1–80 of the_register.pdf and extract all named persons with page refs. Save to persons.md `` Next request:> Read pages 81–160 of the_register.pdf, extract named persons, append to persons.md`

  2. Convert to markdown first, then read the markdown. For documents you will process repeatedly, convert once with pymupdf4llm. The resulting markdown file has no page limit and is reusable across sessions: ```

    Convert the_register.pdf to markdown using pymupdf4llm. Save as the_register.md `` Then:> Read the_register.md and extract all named persons.`

  3. Split the PDF into sections. Use a PDF tool (Preview on Mac, Adobe Acrobat, or free tools like Smallpdf or PDF24) to produce separate files, then process each in sequence: ```

    Read the_register_pp1-80.pdf and extract all named persons. Save to persons.md `` Next:> Read the_register_pp81-160.pdf, extract named persons, append to persons.md`

  4. Ask Claude to prioritise for a summary — if you just need the overall argument of a long document without full extraction: ```

    Read the_report.pdf. It is long — focus on the introduction, section headers, and conclusion. Give me the overall argument and structure. ```

Saving and organising output

By default, Claude Code's output appears in the terminal. To save it:

Save to a new file:

> Read paper.pdf and write a summary to paper_summary.md

Append to an existing file:

> Read paper2.pdf, write a summary, and append it to reading_notes.md

Save as structured data (CSV):

> Read the depositions and extract [fields]. Save as depositions.csv

A useful folder structure for PDF work:

project/
  sources/        ← original PDFs (never modified)
  transcriptions/ ← text files of transcribed/extracted content
  notes/          ← summaries, first-pass notes, reading notes
  output/         ← structured data, CSVs, final extractions
  CLAUDE.md       ← tells Claude about this structure

Put this structure in your CLAUDE.md so Claude knows where to write things:

## Folder structure

- /sources/ — original PDFs, read-only

- /notes/ — summaries and reading notes, write here

- /output/ — structured data extractions, write here

Telling Claude how to handle uncertainty

Claude will sometimes encounter:

You can instruct Claude explicitly about how to handle these:

> When you are uncertain about a name identification, write the variants
  and mark with [?] rather than guessing.

> If a date is given in an indirect form, convert it to a calendar year
  and note the conversion.

> If text appears damaged or unreadable in the source, write [gap] and
  continue.

> Do not infer information not present in the source. If something is
  unclear, say so.

Building these instructions into your CLAUDE.md saves you from repeating them each session.

Common issues and solutions

"Claude says it cannot find the file" You are probably in the wrong folder. Type pwd to see where you are. Navigate to the right folder with cd, then try again. Or use the full path: Read /Users/yourname/Documents/project/paper.pdf

"Claude read the PDF but the output is garbled / full of strange characters" The PDF may have encoding issues or unusual fonts. Try: "The previous output had encoding errors. Please re-read the file and ignore characters you cannot decode — just skip them and continue with readable text."

"Claude says the PDF has no text / is empty" The PDF is probably an image scan without an OCR layer. You need to run OCR before Claude can read it. See the section above on what Claude can and cannot read.

"The summary seems superficial — Claude missed important sections" For long documents, Claude may have prioritised certain sections. Be more specific: name the sections you need, or ask Claude to read and report chapter by chapter.

"Claude made up a fact that is not in the document" This is hallucination — Claude confabulating plausible-sounding content. This is a real risk, especially for proper nouns, dates, and citation details. Always verify specific claims against the source. See A.critical.limitations for a fuller treatment.

Related