omapdf

Preview.app für Linux – aber Ihr Agent kann es steuern.

omapdf ist ein agenten-natives PDF-Tool: ein schneller GTK4-Editor zum Lesen, Kommentieren und Signieren; eine skriptbare CLI; ein MCP-Server für KI-Agenten; und eine Omarchy-Integration, die alles mit dem Betriebssystem verbindet. Darunter liegt eine einzige Op-Engine – alles, was ein Mensch von Hand tun kann, kann ein Agent per Anweisung tun, und umgekehrt.

omapdf edit lease.pdf                       # the editor
omapdf sign lease.pdf --page 4 --at 120,540 --date -o signed.pdf
# …or just tell your agent: "fill out this lease, highlight anything
#  unusual, and get it ready for my signature"

Warum

Der Workflow „Jemand hat mir eine PDF gemailt, ich muss zwei Dinge markieren, unterschreiben und zurückschicken“ ist das Killer-Feature von macOS Preview – und Linux hat kein leichtgewichtiges Äquivalent. Und niemand behandelt KI-Agenten als erstklassige PDF-Nutzer. omapdf macht beides, mit einer Architektur:

Related MCP server: PDF Reader MCP Server

Eine Operations-API, jeder Client ist dünn

Jede Aktion – markieren, kommentieren, ein Feld ausfüllen, eine Signatur stempeln, Tinte zeichnen – ist eine kleine JSON-Operation. Eine Dokumentbearbeitung ist eine Liste davon. Der Editor, die CLI und der MCP-Server laufen alle durch dieselbe Engine:

     human                            agent
       │                                │
 ┌─────┴─────┐                 ┌────────┴────────┐
 │  editor   │                 │  MCP server /   │
 │  (GTK4)   │                 │  Claude skill   │
 └─────┬─────┘                 └────────┬────────┘
       │          ops (JSON)            │
       └──────────────┬─────────────────┘
              ┌───────┴───────┐
              │   op engine   │  validate → resolve → apply → report
              │   (PyMuPDF)   │
              └───────┬───────┘
                 document.pdf

Jede angewendete Op gibt ihre aufgelöste Geometrie zurück, sodass jede Seite der anderen genau zeigen kann, was sich wo geändert hat. Alles Geschriebene ist eine Standard-PDF-Annotation – Acrobat-, Preview- und Evince-Benutzer sehen Ihre Notizen und Markierungen als normale Kommentare.

Der Editor (omapdf edit)

Ein nativer GTK4-Editor, so schnell wie Preview, für Omarchy entwickelt, aber auch mit reinem GTK portabel:

• Werkzeuge (handgezeichnetes Vektor-Icon-Set): Auswählen/Ziehen, Stift mit erneuter Tipp-Farbpalette, Textmarker, Text, Haftnotizen, Signaturplatzierung, grüner Haken und rotes Kreuz als Stempel

• Geistermodell: Alles, was Sie platzieren, ist ein ziehbares, fein verschiebbares ausstehendes Element, bis Speichern es durch die Op-Engine backt – und Rückgängig überschreitet die Speichergrenze: Strg+Z nach dem Speichern macht die Datei rückgängig und erweckt die gespeicherten Elemente als bearbeitbare Geister wieder.

• Lesekomfort: Miniaturansichten-Seitenleiste (F9), Breitenzoom, der dem Live-Viewport folgt, Zoom-Voreinstellungen + Strg+Scrollen, Volltextsuche (Strg+F) mit Trefferwechsel, Seitennavigation mit Auf/Ab, BildAuf/BildAb, Pos1/Ende, Strg+G Gehe-zu-Seite

• Kommentare per Klick öffnen: Klicken Sie auf eine gespeicherte Annotation, um ihren Text zu lesen – einschließlich Kommentaren, die von Agenten oder anderen PDF-Apps hinterlassen wurden.

• Agentenvorschläge als Geister: omapdf edit doc.pdf --ops proposal.json lädt die Trockenlauf-Ops eines Agenten als ausgewählte, ziehbare Overlays – verschieben, dann Speichern. Agent schlägt vor, Mensch bestätigt.

• Fragen Sie Ihren Agenten (✦): Geben Sie eine Frage ein, er öffnet Ihren Standard-Agenten des Betriebssystems (omarchy agent prompt) mit dem angehängten Dokument. Der Editor beobachtet die Datei und lädt sich neu, wenn der Agent Änderungen speichert.

• Teilen (nativ, kein Fake-Share-Sheet): E-Mail-Anhang, LocalSend, Datei (oder ein ZIP davon) direkt in die Zwischenablage kopieren, im Ordner anzeigen – mit optionalem Umschalter „Zuerst flachkopieren“.

• Speicher-Feier inklusive. Sie werden sehen.

Die CLI

omapdf read doc.pdf                  # structured JSON: text+bboxes, fields, annots
omapdf read doc.pdf --text-only      # just the words
omapdf fields form.pdf               # fillable fields with names and rects
omapdf snapshot doc.pdf --page 2 --grid 50   # page PNG with a labeled
                                     # coordinate grid — agents read placement
                                     # coordinates straight off the image

omapdf annotate doc.pdf --page 2 --match "termination clause"
omapdf note doc.pdf --page 2 --at 400,300 --text "negotiate this"
omapdf fill form.pdf --field tenant_name "Peter Bergin" --field rent "1800"
omapdf apply doc.pdf --ops edits.json        # atomic batch of ops

omapdf sig draw                      # draw your signature once (GTK window)
omapdf sig add ~/sig.png --name work # …or import an image
omapdf sign doc.pdf --page 4 --at 120,540 --date -o signed.pdf
omapdf flatten doc.pdf -o final.pdf  # bake everything in for any viewer
omapdf open doc.pdf                  # opens the omapdf editor

Jeder Bearbeitungsbefehl akzeptiert -o (Standard: an Ort und Stelle), --dry-run und --json (jede Op gibt ihre aufgelöste Geometrie zurück). Koordinaten sind PDF-Punkte, Ursprung oben links, 1-basierte Seiten – identisch mit dem, was read meldet. Das Ops-Vokabular ist in docs/ops.md festgelegt.

Agenten

claude mcp add omapdf -- omapdf-mcp

MCP-Tools: read_pdf, list_form_fields, apply_ops, highlight, add_note, fill_field, place_signature (standardmäßig Trockenlauf – Bestätigung vor Tinte), list_signatures, flatten_pdf.

Die Claude-Code-Skill in skill/ ist ein vollständiges PDF-Assistenten-Playbook: Rezepte für Überprüfen-und-Markieren, Formularausfüllen, Signieren, Redlining, Checklisten, Extraktion mit Seitenzitaten – aufgebaut um eine Präzisionsleiter: Textanker → Raster-Snapshot (Seite ansehen) → Trockenlauf → das geschriebene Ergebnis visuell verifizieren → dem Menschen ein ziehbares Geist übergeben, wenn Geschmack zählt.

Installation

git clone https://github.com/pbergin11/omapdf && cd omapdf
python -m venv --system-site-packages .venv    # system gi for the GTK editor
.venv/bin/pip install -e '.[mcp]'
ln -s "$PWD/.venv/bin/omapdf" ~/.local/bin/omapdf
ln -s "$PWD/.venv/bin/omapdf-mcp" ~/.local/bin/omapdf-mcp
ln -s "$PWD/bin/omapdf-pick" ~/.local/bin/omapdf-pick

Erfordert Python ≥ 3.11, PyMuPDF und (für den Editor und sig draw) PyGObject + GTK4 aus Ihrer Distribution. Arch-Paketierung in packaging/PKGBUILD.

Machen Sie omapdf zu Ihrem systemweiten PDF-Handler:

cp share/omapdf.desktop ~/.local/share/applications/
xdg-mime default omapdf.desktop application/pdf

Omarchy-Integration

• Top-Bar-Widget (shell-plugin/): eine PDF-Pille – klicken für ein Menü der letzten PDFs, eines auswählen, es öffnet sich im Editor (ln -s .../shell-plugin/omapdf.bar ~/.config/omarchy/plugins/omapdf.bar, dann omarchy bar put omapdf.bar --section right)

• Ask-Agent verwendet omarchy agent prompt, startet also den vom Benutzer gewählten Standard-Agenten (omarchy default agent) im nativen Agentenfenster von Omarchy; Voxtype-Diktat funktioniert im Fragfeld wie in jedem Textfeld.

• Verpackt im Geiste von omasnap: ein fokussiertes, zweckgebundenes natives Werkzeug

Status & Roadmap

Heute funktionsfähig: Op-Engine, CLI, MCP-Server + Skill, Signaturspeicher und Zeichenfenster, der vollständige Editor, Bar-Widget, Agent-Fragen/Beobachten-Schleife, Tests. Siehe docs/roadmap.md für das, was als Nächstes kommt – Highlights: automatische Erkennung von Signaturlinien (sign --auto), Löschen/Bearbeiten von Annotationen gespeicherter Elemente, Kommentar-Zusammenfassungsseite, kryptografisches (PAdES) Signieren über pyHanko.

Lizenz

AGPL-3.0-or-later (passend zu unserer PyMuPDF-Abhängigkeit). Siehe LICENSE.