Searchable PDF OCR and Text Extraction

Turn scanned PDFs on a Mac into searchable documents with selectable, copyable text, and extract Markdown when needed. Processing runs locally and offline through Apple Vision / Live Text, for papers, books, and scanned reference material.

Use it as an Agent Skill or run the command-line scripts directly. Download the complete package from this site. The documentation identifies the version as 1.0.1; this site packages the verified source commit bed2dc8. This does not establish that a corresponding GitHub Release was published.

Features

• Searchable PDFs: preserve page layout and add an invisible text layer. The default preservation preset does not re-encode scanned images.
• Markdown extraction: organize headings and paragraphs from text positions and section features, join scanned line breaks, and filter some headers, footers, and page numbers. PDFs with an existing text layer can be extracted directly.
• Multiple languages: support Simplified Chinese, Traditional Chinese, English, Japanese, Korean, and other languages, subject to the recognition mode and system environment.
• Batch and incremental processing: accept multiple files and directories, and skip repeated OCR when newer outputs already exist.
• Preservation, deskewing, and compression: choose a processing preset for the material’s intended use.
• Automatic red-box repair: remove supported AppleOCR debugging boxes, including from existing outputs, while preserving file permissions and extended attributes such as macOS Finder tags.

Installation

Requires macOS, Homebrew, and uv. Live Text depends on system support; if unavailable, select --mode accurate. Downloading the ZIP from this site does not require Node.js or the skills CLI.

Ask your agent to install it

Give the detail-page URL to an online coding agent:

Read this page and its installation guide, then install pdf-ocr-searchable for my current host: https://www.lumenghe.com/en/skills/pdf-ocr-searchable/ . Download the complete ZIP linked on this page, verify its SHA-256, preserve any existing installation and local changes, and report whether the host discovers the skill.

The plain-text installation guide lists the package, shared installation path, prerequisites, and verification steps. It does not require access to my GitHub repositories.

Install the ZIP manually

1. Download the complete ZIP. Compare its SHA-256 with the package information on the detail page before extracting it. On macOS, run shasum -a 256 "$HOME/Downloads/pdf-ocr-searchable-1.0.1-20261024-bed2dc8.zip" if the file is in Downloads.
2. Extract the archive into a temporary working folder. It contains one pdf-ocr-searchable/ folder with SKILL.md, supporting files, and the license. Move that folder to ~/.agents/skills/pdf-ocr-searchable/. If a file, directory, or symlink already exists there, inspect and back it up before choosing how to update it; do not merge or overwrite it blindly.
3. Configure discovery for your host. Codex reads personal skills from ~/.agents/skills. For Claude Code personal skills, add a symlink under ~/.claude/skills/ as shown below. Other hosts follow their own documented discovery rules; this shared directory is not automatically discovered everywhere.

mkdir -p ~/.claude/skills
if [ ! -e ~/.claude/skills/pdf-ocr-searchable ] && [ ! -L ~/.claude/skills/pdf-ocr-searchable ]; then
  ln -s ~/.agents/skills/pdf-ocr-searchable ~/.claude/skills/pdf-ocr-searchable
else
  printf '%s\n' 'An entry already exists; inspect it before making changes.'
fi

Keep the canonical files under ~/.agents/skills/pdf-ocr-searchable/: existing skill instructions and scripts refer to this path. After installation, check that SKILL.md exists and confirm the skill in the host’s list or a new session; a file on disk does not prove that it is loaded. The ZIP contains skill files, not the OCR runtime. Install the dependencies below separately.

Install dependencies

OCRmyPDF and the AppleOCR plugin must be installed in the same Python environment. These commands use Python 3.12:

uv tool install --python 3.12 ocrmypdf --with ocrmypdf-appleocr
brew install ghostscript poppler

Check that the plugin is available:

ocrmypdf --plugin ocrmypdf_appleocr --help 2>&1 | grep -q appleocr && echo OK

Quick start

These examples assume the skill is installed at ~/.agents/skills/pdf-ocr-searchable. If you use the scripts independently from another location, adjust the paths accordingly.

S=~/.agents/skills/pdf-ocr-searchable/scripts/ocr_pdf.sh

# Check whether a file needs OCR
"$S" --check "论文.pdf"

# Create 论文.ocr.pdf and retain the original
"$S" "论文.pdf"

# Also produce 论文.md
"$S" --md "论文.pdf"

# Process PDFs in a directory
"$S" ~/Scans/

# Deskew and recognize Traditional Chinese
"$S" --preset deskew --lang chi_tra "扫描件.pdf"

The script uses a text-density criterion to skip OCR for PDFs that already contain a text layer; with --md, it extracts Markdown directly. An existing output newer than the source is reused. Use --force to recognize the document again or change processing parameters; this redoes an existing text layer and rewrites the target output.

Choose a processing preset

"$S" --preset compact "资料.pdf"

By default, outputs are written beside the original with the suffix .ocr.pdf. Use --outdir to choose a destination or --suffix to change the suffix:

"$S" --outdir "./output" --suffix ".searchable" "资料.pdf"

Languages and recognition modes

The default language is Simplified Chinese, chi_sim. Select a language with --lang:

Combined language strings such as chi_sim+eng are not supported. Chinese models may recognize some English within a page; spot-check proper names and references when a document contains substantial English.

--mode accepts livetext (default), accurate, or fast. Some Live Text failures automatically fall back to accurate, which you can also select directly. fast supports fewer languages and is unsuitable for Chinese documents.

"$S" --lang eng --mode accurate "paper.pdf"

Repair OCR debugging boxes

After OCR, supported AppleOCR debugging boxes are removed automatically. To repair an existing output, specify the PDF directly:

# Detect only; do not modify the file
"$S" --strip-boxes --dry-run "论文.ocr.pdf"

# Repair this file
"$S" --strip-boxes "论文.ocr.pdf"

# Repair *.ocr.pdf files in a directory
"$S" --strip-boxes ~/Scans/

The repair supports ordinary form fields and unsigned signature fields. It does not rewrite encrypted or already signed files. If cleanup fails, the script reports an error and stops subsequent Markdown generation for that file. See red-box compatibility and troubleshooting for supported formats and diagnostic steps.

Usage notes

• OCR and Markdown layout reconstruction may contain errors. Check important content against the original pages, especially contents lists, indexes, and complex headings.
• --check determines whether OCR is needed from text density. Spot-check the body when pages with little text are mixed with scanned pages.
• The script prompts for manual review when very few characters are recognized. A successful command exit does not mean every page was recognized correctly.
• The default preset preserves scanned images, but the PDF container is rewritten; the complete file is not guaranteed to remain byte-for-byte identical. Keep the source PDF when you need the original.
• Red-box cleanup targets known AppleOCR formats. If a plugin update triggers a format-compatibility warning, consult the compatibility guide.

Run "$S" --help to see all parameters.

Project files

SKILL.md                    # Agent skill entry point
scripts/ocr_pdf.sh          # PDF OCR and batch-processing entry point
scripts/pdf_to_md.py        # Convert a PDF text layer into Markdown
scripts/strip_ocr_boxes.py  # Repair AppleOCR debugging boxes
references/red-boxes.md     # Repair boundaries and troubleshooting
tests/test_red_boxes.py     # Regression tests for red-box repair

Acknowledgments

• OCRmyPDF: the PDF OCR processing pipeline.
• OCRmyPDF-AppleOCR: the Apple Vision / Live Text engine plugin.
• mac-ocr: an optional OCR tool for individual images.
• Poppler: PDF text and page-layout extraction.

License

MIT