omapdf

Preview.app para Linux — pero tu agente puede manejarlo.

omapdf es una herramienta PDF nativa para agentes: un editor GTK4 rápido para leer, anotar y firmar; una CLI programable; un servidor MCP para agentes de IA; y una integración con Omarchy que los une a todos con el sistema operativo. Un único motor de operaciones debajo: cualquier cosa que un humano pueda hacer a mano, un agente puede hacerla por instrucción, y viceversa.

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"

Por qué

El flujo de trabajo de «alguien me envió un PDF por correo, necesito resaltar dos cosas, firmarlo y devolverlo» es la función estrella de macOS Preview — y Linux no tiene un equivalente ligero. Y nadie en ningún lugar trata a los agentes de IA como usuarios PDF de primera clase. omapdf hace ambas cosas, con una arquitectura:

Related MCP server: PDF Manipulation MCP Server

Una API de operaciones, cada cliente es delgado

Cada acción — resaltar, comentar, rellenar un campo, estampar una firma, dibujar tinta — es una pequeña operación JSON. Una edición de documento es una lista de ellas. El editor, la CLI y el servidor MCP pasan todos por el mismo motor:

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

Cada operación aplicada devuelve su geometría resuelta, para que cualquiera de los lados pueda mostrar al otro exactamente qué cambió y dónde. Todo lo escrito es una anotación PDF estándar — los usuarios de Acrobat, Preview y Evince ven tus notas y resaltados como comentarios normales.

El editor (omapdf edit)

Un editor GTK4 nativo, tan rápido como Preview, diseñado para Omarchy pero portable a GTK simple:

• Herramientas (conjunto de iconos vectoriales dibujados a mano): seleccionar/arrastrar, lápiz con paleta de colores al tocar de nuevo, resaltador, texto, notas adhesivas, colocación de firmas, sellos de marca verde y cruz roja

• Modelo fantasma: todo lo que colocas es un elemento pendiente arrastrable y ajustable hasta que Guardar lo procesa a través del motor de operaciones — y deshacer cruza el límite de guardado: Ctrl+Z después de guardar revierte el archivo y resucita los elementos guardados como fantasmas editables

• Comodidades de lectura: barra lateral de miniaturas (F9), zoom de ajuste al ancho que sigue la ventana gráfica en vivo, ajustes preestablecidos de zoom + Ctrl+scroll, búsqueda en todo el documento (Ctrl+F) con ciclo de coincidencias, navegación de páginas con Arriba/Abajo, RePág/AvPág, Inicio/Fin, Ctrl+G ir a página

• Los comentarios se abren al hacer clic: haz clic en cualquier anotación guardada para leer su texto — incluidos los comentarios dejados por agentes o por las aplicaciones PDF de otras personas

• Propuestas de agentes como fantasmas: omapdf edit doc.pdf --ops proposal.json carga las operaciones de prueba de un agente como superposiciones seleccionables y arrastrables — ajusta y luego Guarda. El agente propone, el humano confirma.

• Pregunta a tu agente (✦): escribe una pregunta, abre el agente predeterminado de tu sistema operativo (omarchy agent prompt) con el documento adjunto. El editor vigila el archivo y se recarga solo cuando el agente guarda cambios.

• Compartir (nativo, sin hoja de compartir falsa): adjuntar por correo, LocalSend, copiar el archivo (o un zip de él) directamente al portapapeles, mostrar en carpeta — con una opción opcional de aplanar-copiar-primero

• Celebración de guardado incluida. Ya lo verás.

La 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

Cada comando de edición acepta -o (por defecto: en el lugar), --dry-run y --json (cada operación devuelve su geometría resuelta). Las coordenadas son puntos PDF, origen arriba a la izquierda, páginas basadas en 1 — idénticas a lo que informa read. El vocabulario de operaciones se especifica en docs/ops.md.

Agentes

claude mcp add omapdf -- omapdf-mcp

Herramientas MCP: read_pdf, list_form_fields, apply_ops, highlight, add_note, fill_field, place_signature (prueba por defecto — confirmar antes de la tinta), list_signatures, flatten_pdf.

La habilidad de Claude Code en skill/ es un manual completo de asistente PDF: recetas para revisar y resaltar, rellenar formularios, firmar, marcar en rojo, listas de verificación, extracción con citas de página — construido alrededor de una escalera de precisión: anclas de texto → instantánea de cuadrícula (mirar la página) → prueba → verificar el resultado escrito visualmente → entregar un fantasma arrastrable al humano cuando el gusto importa.

Instalación

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

Requiere Python ≥ 3.11, PyMuPDF y (para el editor y sig draw) PyGObject + GTK4 de tu distribución. Empaquetado de Arch en packaging/PKGBUILD.

Haz de omapdf tu manejador de PDF del sistema:

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

Integración con Omarchy

• Widget de barra superior (shell-plugin/): una píldora PDF — haz clic para un menú de PDFs recientes, elige uno, se abre en el editor (ln -s .../shell-plugin/omapdf.bar ~/.config/omarchy/plugins/omapdf.bar, luego omarchy bar put omapdf.bar --section right)

• Preguntar al agente usa omarchy agent prompt, por lo que lanza el agente predeterminado que el usuario eligió (omarchy default agent), en la ventana de agente nativa de Omarchy; el dictado de Voxtype funciona en el cuadro de preguntas como cualquier campo de texto

• Empaquetado con el espíritu de omasnap: una herramienta nativa enfocada y de un solo propósito

Estado y hoja de ruta

Funcionando hoy: motor de operaciones, CLI, servidor MCP + habilidad, almacén de firmas y ventana de dibujo, el editor completo, widget de barra, bucle de preguntar/vigilar del agente, pruebas. Consulta docs/roadmap.md para lo que viene — titulares: detección automática de línea de firma (sign --auto), eliminación/edición de anotaciones de elementos guardados, página de resumen de comentarios, firma criptográfica (PAdES) mediante pyHanko.

Licencia

AGPL-3.0-o-posterior (coincidiendo con nuestra dependencia de PyMuPDF). Consulta LICENSE.