watchdoc

Watch a folder for PDFs and run OCR so Spotlight can index them.

---

Scanned PDFs are just images — Spotlight can't search their text. watchdoc runs OCRmyPDF on them automatically, adding a searchable text layer in-place.

Install

curl -fsSL https://raw.githubusercontent.com/clstaudt/watchdoc/main/install.sh | sh

This single command installs everything: Homebrew (if missing), uv (if missing), system dependencies (tesseract, ghostscript, terminal-notifier), and the watchdoc CLI.

Usage

One-shot: process existing PDFs

watchdoc run ~/Documents/Scans

Processes all *.pdf files in parallel (one per CPU core), then exits.

Watch mode: process new PDFs as they arrive

watchdoc watch ~/Documents/Scans

Stays running and OCRs each new PDF dropped into the folder. Stop with ctrl-c.

Persistent: install as a launchd agent

watchdoc install ~/Documents/Scans

Installs a macOS launch agent that triggers automatically whenever the folder contents change.

watchdoc uninstall

Removes the launch agent.

Options

Flag	Commands	Description
--output-dir DIR	run, watch	Write OCR'd copies to a separate folder instead of replacing in-place

System dependencies

brew install tesseract ghostscript terminal-notifier

Check what's missing with:

watchdoc deps

• tesseract — OCR engine
• ghostscript — PDF rasterizer
• terminal-notifier — optional, shows a notification with the watchdoc icon when processing completes

How it works

PDF added to folder
        │
        ▼
   watchdoc run
        │
        ▼
  ocrmypdf (mode=redo)
        │
  ┌─────┴─────┐
  │ tesseract  │  ← extracts text from page images
  │ghostscript │  ← rasterizes PDF pages
  └─────┬─────┘
        │
        ▼
  PDF with text layer
        │
        ▼
  Spotlight indexes it

License

MIT