PDFs in Claude Code: warum du doppelt zahlst und wie ein Hook das abstelltPDFs in Claude Code: why you pay twice and how a hook fixes it

Du gibst Claude Code einen Vertrag als PDF und wunderst dich, wie schnell das Kontextfenster voll ist. Das liegt am Format. Eine PDF beschreibt, wo jedes Zeichen auf der Seite steht. Den Inhalt musst du dir daraus erst zurückholen.

Sebastian Kauffmann von SKAILE hat dazu eine gute Übersicht veröffentlicht und empfiehlt Markitdown von Microsoft. Ich gehe einen Schritt weiter. Hier baust du dir einen Hook, der jede PDF vor dem Lesen selbst umwandelt. In Claude Code und in Codex. Danach musst du nicht mehr daran denken.

was eine pdf in claude kostet

Anthropic beschreibt den Ablauf offen. Schickst du eine PDF an Claude, zieht das System zuerst den Text heraus. Danach wandelt es jede Seite in ein Bild. Claude bekommt beides. So kann es Diagramme und Tabellen auch dann verstehen, wenn der Text allein nicht reicht.

Das ist klug, wenn du wissen willst, wie ein Diagramm aussieht. Für einen Mietvertrag ist es Verschwendung. Die Dokumentation rechnet mit 1.500 bis 3.000 Text-Token pro Seite, je nach Dichte. Das Seitenbild wird wie jedes andere Bild zusätzlich berechnet. Bei 40 Seiten zahlst du also 40 Bilder mit, die dir nichts Neues sagen.

SKAILE schätzt für eine 20-seitige PDF mit Logo und zwei Tabellen rund 50.000 Token direkt und rund 12.000 Token als Markdown. Die Seite nennt das selbst eine Faustregel aus typischen Dokumenten. Ich übernehme die Zahl nicht als Messwert. Die Richtung passt aber zu dem, was Anthropic beschreibt: Wer das Seitenbild weglässt, spart den größeren Teil.

warum markdown reicht

Eine PDF kennt keine Tabelle. Sie kennt Linien und Textstücke an bestimmten Koordinaten. Dass daraus eine Tabelle wird, sieht erst dein Auge. Claude muss diese Ordnung bei jedem Lesen neu erraten.

Markdown schreibt die Struktur direkt hin. Eine Überschrift beginnt mit #, eine Tabellenzeile steht zwischen senkrechten Strichen. Das Modell muss nichts rekonstruieren. Es liest, was da steht. Das spart Token und senkt die Zahl der Stellen, an denen es sich verschätzen kann.

markitdown in zwei minuten

Markitdown ist ein Open-Source-Werkzeug von Microsoft unter MIT-Lizenz. Es wandelt PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, ZIP-Archive und EPUB in Markdown. Die Installation braucht Python ab Version 3.10.

# Python 3.10 oder neuer. pipx hält Markitdown in einer eigenen Umgebung.
pipx install 'markitdown[all]'

# Alternative ohne pipx
pip install 'markitdown[all]'

# Probe: eine PDF, eine Markdown-Datei
markitdown vertrag.pdf -o vertrag.md

Öffne danach die erzeugte vertrag.md. Stehen Überschriften und Absätze sauber untereinander, bist du startklar. Steht nichts drin, hast du vermutlich einen Scan erwischt. Dazu gleich mehr.

was markitdown nicht kann

An dieser Stelle weiche ich von vielen Anleitungen ab, auch von SKAILE. Dort steht, Markitdown erkenne Bilder per OCR und laufe komplett lokal. Beides zusammen stimmt nicht.

Die Umwandlung von Text-PDFs läuft lokal. Texterkennung in Bildern gibt es über das Plugin markitdown-ocr. Laut Microsoft nutzt es dafür ein Vision-Modell über einen LLM-Client, im Beispiel gpt-4o von OpenAI. Deine Seiten verlassen dann den Rechner. Bei Verträgen mit Personendaten klärst du das vorher mit deinem Datenschutz.

Ich habe es an einem eingescannten Zertifikat ausprobiert. Markitdown ohne Plugin liefert eine leere Datei. Der Hook unten fängt genau diesen Fall ab: Kommt nichts heraus, darf Claude die PDF normal lesen.

vom prompt zur automatik

Die meisten Anleitungen enden bei einem Prompt wie „Konvertiere mir diese PDF“. Das funktioniert, solange du daran denkst. Ein Agent, der mitten in einer Aufgabe eine PDF im Projektordner findet, denkt nicht daran. Er liest sie einfach.

Claude Code hat dafür Hooks. Ein Hook ist ein Skript, das vor oder nach einem Werkzeugaufruf läuft. Der PreToolUse-Hook sieht, welche Datei gelesen werden soll, und kann den Aufruf ablehnen. Mit Begründung. Genau das nutzt du hier.

Zuerst ein kleines Skript, das eine PDF umwandelt. Es legt die Markdown-Datei neben die PDF und schreibt eine Markerzeile an den Anfang. Ist die .md jünger als die PDF, passiert nichts. Eine .md ohne Marker hat jemand anderes geschrieben, die fasst das Skript nicht an.

#!/bin/bash
# ~/bin/pdf2md.sh — legt neben jeder PDF eine gleichnamige .md an.
# Aktuelle .md wird nicht neu erzeugt. Fremde .md ohne Markerzeile
# wird nie überschrieben.
MARKER='<!-- pdf2md:markitdown -->'
MARKITDOWN="${MARKITDOWN:-$(command -v markitdown)}"
for p in "$@"; do
  [ -f "$p" ] || continue
  md="${p%.[Pp][Dd][Ff]}.md"
  [ "$md" = "$p" ] && continue
  if [ -f "$md" ]; then
    head -1 "$md" | grep -qF "$MARKER" || continue
    if ! [ "$p" -nt "$md" ]; then echo "$md"; continue; fi
  fi
  tmp="$(mktemp "$(dirname -- "$md")/.pdf2md.XXXXXX")" || continue
  raw="$(mktemp)" || { rm -f "$tmp"; continue; }
  if "$MARKITDOWN" "$p" -o "$raw" 2>/dev/null && [ -s "$raw" ] &&
     { echo "$MARKER"; cat "$raw"; } > "$tmp"; then
    mv "$tmp" "$md" && echo "$md"
  fi
  rm -f "$tmp" "$raw"
done

Dann der Hook selbst. Er liest den geplanten Aufruf als JSON, holt den Dateipfad heraus und ruft das Skript. Entsteht eine .md, lehnt er das Lesen der PDF ab und nennt den Pfad. Claude liest im nächsten Schritt die Markdown-Datei.

#!/bin/bash
# ~/.claude/hooks/pdf2md-pretool.sh — läuft vor jedem Lesezugriff.
# Ist das Ziel eine PDF mit Text, entsteht die .md daneben und das
# Lesen der PDF wird mit Verweis auf die .md abgelehnt.
# Bild-PDFs ohne Text lässt der Hook unverändert durch.
[ "${PDF2MD_OFF:-0}" = 1 ] && exit 0
in=$(cat)
p=$(jq -r '.tool_input | (.file_path // .path // empty)' <<<"$in")
case "$(tr '[:upper:]' '[:lower:]' <<<"$p")" in *.pdf) ;; *) exit 0 ;; esac
[ -f "$p" ] || exit 0
[ -L "$p" ] && exit 0   # Symlink: nicht konvertieren
md=$("$HOME/bin/pdf2md.sh" "$p" | head -1)
[ -n "$md" ] || exit 0
jq -n --arg r "PDF nicht direkt lesen: Markdown liegt unter $md. Lies diese Datei." \
  '{hookSpecificOutput:{hookEventName:"PreToolUse",
    permissionDecision:"deny",permissionDecisionReason:$r}}'

Mach beide Dateien ausführbar mit chmod +x. Dann trägst du den Hook in deine Einstellungen ein. Steht dort schon ein hooks-Block, ergänzt du nur den neuen Eintrag unter PreToolUse.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/pdf2md-pretool.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Zum Testen legst du eine beliebige Text-PDF in einen Ordner und bittest Claude, sie zu lesen. Du siehst eine Hook-Meldung mit dem Pfad zur .md, danach liest Claude die Markdown-Datei. Einen Scan liest Claude wie bisher als PDF.

derselbe hook in codex

Codex versteht dasselbe Hook-Format. Die Einträge stehen in ~/.codex/hooks.json, eingeschaltet werden sie mit hooks = true in der config.toml. Du brauchst kein zweites Skript.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/DEIN-NAME/.claude/hooks/pdf2md-pretool.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

[features]
hooks = true

Beim nächsten Start fragt Codex, ob du dem neuen Hook vertraust. Das ist Absicht. Ein Hook führt Code aus, also soll er nicht still dazukommen. Trag den Pfad absolut ein, so wie deine übrigen Codex-Hooks.

einen ganzen ordner umwandeln

Hast du einen Ordner mit fünfzig Rechnungen, musst du nicht warten, bis der Agent jede einzeln anfasst. Gib ihm diesen Auftrag. Er nutzt dasselbe Skript und meldet dir die Scans, bei denen nichts herauskam.

Wandle alle PDFs in diesem Ordner mit ~/bin/pdf2md.sh in Markdown um.
Arbeite danach nur noch mit den .md-Dateien.
Melde mir jede PDF, bei der keine .md entstanden ist:
das sind meist Scans ohne Textebene, die brauchen OCR.

wann die pdf direkt rein darf

Markdown verliert das Aussehen. Das ist meistens ein Gewinn und manchmal ein Fehler. Wenn du prüfen willst, ob ein Diagramm die richtige Achse hat, ob eine Unterschrift an der richtigen Stelle sitzt oder ob ein Angebot so aussieht, wie es soll, braucht Claude das Seitenbild.

Für diese Fälle startest du die Sitzung mit PDF2MD_OFF=1. Dann hält sich der Hook heraus. Alternativ lässt du Claude über den PDF-Skill einzelne Seiten als Bild rendern. Das kostet gezielt die Seiten, die du wirklich sehen musst.

das setup als datei

Alle Skripte, beide Hook-Einträge, die Prüfschritte und die Grenzen aus diesem Beitrag gibt es als Markdown-Datei und als PDF. Die Markdown-Fassung legst du in dein Projekt und sag deinem Agenten, er soll das einrichten. Sie ist so geschrieben, dass Claude Code und Codex sie Schritt für Schritt abarbeiten können. Beide Dateien liegen danach in deinem Konto unter „Dateien & Downloads“ und kommen zusätzlich per Mail.

quellen und stand

• Anthropic: PDF support, Abschnitte zur Verarbeitung und zu den Kosten.
• Anthropic: Claude Code Hooks, PreToolUse und permissionDecision.

Stand 23.09.2026. Getestet mit Markitdown 0.1.7 auf macOS.