omapdf

Linux용 Preview.app — 하지만 에이전트가 직접 조종할 수 있습니다.

omapdf는 에이전트 네이티브 PDF 도구입니다: 읽기, 주석 달기, 서명을 위한 빠른 GTK4 편집기, 스크립트 가능한 CLI, AI 에이전트용 MCP 서버, 그리고 이 모든 것을 운영 체제에 연결하는 Omarchy 통합을 제공합니다. 그 아래에는 하나의 op 엔진이 있습니다 — 사람이 손으로 할 수 있는 모든 것을 에이전트는 지시로 할 수 있고, 그 반대도 마찬가지입니다.

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"

Why

"누군가 PDF를 이메일로 보냈는데, 두 군데를 형광펜으로 표시하고, 서명하고, 다시 보내야 한다"는 워크플로는 macOS Preview의 킬러 기능입니다 — 하지만 Linux에는 가벼운 대안이 없습니다. 그리고 어디에서도 AI 에이전트를 일급 PDF 사용자로 취급하지 않습니다. omapdf는 하나의 아키텍처로 두 가지를 모두 해결합니다:

Related MCP server: PDF Manipulation MCP Server

하나의 operations API, 모든 클라이언트는 얇다

모든 작업 — 형광펜, 주석, 필드 채우기, 서명 스탬프, 잉크 그리기 — 은 작은 JSON 연산입니다. 문서 편집은 이러한 연산들의 목록입니다. 편집기, CLI, MCP 서버는 모두 동일한 엔진을 통해 처리됩니다:

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

적용된 모든 op는 해석된 지오메트리를 반환하므로, 어느 쪽이든 상대방에게 무엇이 어디서 변경되었는지 정확히 보여줄 수 있습니다. 작성되는 모든 것은 표준 PDF 주석입니다 — Acrobat, Preview, Evince 사용자는 여러분의 메모와 형광펜을 일반적인 주석으로 볼 수 있습니다.

편집기 (omapdf edit)

네이티브 GTK4 편집기로, Preview만큼 빠르며, Omarchy용으로 설계되었지만 일반 GTK에서도 사용 가능합니다:

• 도구 (손으로 그린 벡터 아이콘 세트): 선택/드래그, 다시 탭하면 색상 팔레트가 나오는 펜, 형광펜, 텍스트, 스티커 메모, 서명 배치, 녹색 체크 및 빨간 십자 스탬프

• 고스트 모델: 배치하는 모든 것은 Save가 op 엔진을 통해 확정할 때까지 드래그하고 미세 조정할 수 있는 대기 항목입니다 — 그리고 실행 취소는 저장 경계를 넘어섭니다: 저장 후 Ctrl+Z를 누르면 파일이 되돌아가고 저장된 항목이 편집 가능한 고스트로 부활합니다

• 읽기 편의 기능: 썸네일 사이드바 (F9), 실시간 뷰포트를 추적하는 너비 맞춤 확대/축소, 확대/축소 프리셋 + Ctrl+스크롤, 일치 항목 순환 기능이 있는 전체 문서 검색 (Ctrl+F), Up/Down, PgUp/PgDn, Home/End 키로 페이지 탐색, Ctrl+G 페이지 이동

• 클릭으로 주석 열기: 저장된 주석을 클릭하면 텍스트를 읽을 수 있습니다 — 에이전트나 다른 사람의 PDF 앱이 남긴 주석도 포함됩니다

• 고스트로 표시되는 에이전트 제안: omapdf edit doc.pdf --ops proposal.json은 에이전트의 dry-run op를 선택된 드래그 가능한 오버레이로 로드합니다 — 미세 조정 후 Save. 에이전트가 제안하고, 사람이 확인합니다.

• 에이전트에게 묻기 (✦): 질문을 입력하면 문서가 첨부된 상태로 OS 기본 에이전트(omarchy agent prompt)가 열립니다. 편집기는 파일을 감시하다가 에이전트가 변경 사항을 저장하면 자동으로 다시 로드합니다.

• 공유 (네이티브, 가짜 공유 시트 없음): 이메일 첨부, LocalSend, 파일(또는 zip)을 클립보드에 직접 복사, 폴더에서 보기 — 선택적 flatten-복사-우선 토글 포함

• 저장 축하 이벤트 포함. 직접 보시면 알게 됩니다.

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

모든 편집 명령은 -o(기본값: 제자리), --dry-run, --json(각 op는 해석된 지오메트리를 반환)을 지원합니다. 좌표는 PDF 포인트 단위이며, 원점은 왼쪽 위, 페이지는 1부터 시작합니다 — read가 보고하는 것과 동일합니다. op 어휘는 docs/ops.md에 명시되어 있습니다.

에이전트

claude mcp add omapdf -- omapdf-mcp

MCP 도구: read_pdf, list_form_fields, apply_ops, highlight, add_note, fill_field, place_signature(기본적으로 dry-run — 잉크 전 확인), list_signatures, flatten_pdf.

skill/의 Claude Code 스킬은 완전한 PDF 어시스턴트 플레이북입니다: 검토 및 형광펜, 양식 작성, 서명, 레드라이닝, 체크리스트, 페이지 인용이 포함된 추출을 위한 레시피를 제공하며 — 정밀도 사다리를 중심으로 구축되었습니다: 텍스트 앵커 → 그리드 스냅샷(페이지 보기) → dry-run → 작성된 결과를 시각적으로 검증 → 취향이 중요할 때 드래그 가능한 고스트를 사람에게 전달.

설치

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

Python ≥ 3.11, PyMuPDF, 그리고 (편집기와 sig draw용) 배포판의 PyGObject + GTK4가 필요합니다. Arch 패키징은 packaging/PKGBUILD에 있습니다.

omapdf를 시스템 PDF 처리기로 설정하세요:

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

Omarchy 통합

• 상단 바 위젯 (shell-plugin/): PDF 알약 — 클릭하면 최근 PDF 메뉴가 열리고, 하나를 선택하면 편집기에서 열립니다 (ln -s .../shell-plugin/omapdf.bar ~/.config/omarchy/plugins/omapdf.bar, 그 다음 omarchy bar put omapdf.bar --section right)

• Ask-agent는 omarchy agent prompt를 사용하므로, 사용자가 선택한 기본 에이전트(omarchy default agent)를 Omarchy의 네이티브 에이전트 창에서 실행합니다; Voxtype 받아쓰기는 다른 텍스트 필드와 마찬가지로 질문 상자에서 작동합니다

• omasnap의 정신을 따라 패키징되었습니다: 집중된 단일 목적의 네이티브 도구

상태 및 로드맵

현재 작동 중: op 엔진, CLI, MCP 서버 + 스킬, 서명 저장소 및 그리기 창, 전체 편집기, 바 위젯, 에이전트 질문/감시 루프, 테스트. 다음 단계는 docs/roadmap.md를 참조하세요 — 주요 항목: 서명 라인 자동 감지 (sign --auto), 저장된 항목의 주석 삭제/편집, 주석 요약 페이지, pyHanko를 통한 암호화(PAdES) 서명.

라이선스

AGPL-3.0-or-later (PyMuPDF 의존성과 일치). LICENSE를 참조하세요.