privatenumber/mac-ocr

What it solves

mac-ocr is a command-line tool and Node.js API that enables local, private OCR (Optical Character Recognition) on macOS. It allows users to extract text from images and PDFs without uploading data to external servers, providing a free and private alternative to cloud-based vision tokens for AI agents and human users.

How it works

The tool is a native Swift binary that leverages Apple's Vision framework (VNRecognizeTextRequest and RecognizeDocumentsRequest). It processes images and PDFs locally on-device. For searchable PDFs, it uses Core Graphics and Core Text to draw an invisible text layer over the original image, placing words exactly where the Vision framework detected them.

Who it’s for

• Developers building AI agents who want to reduce costs by running OCR locally instead of using multimodal LLMs.
• macOS users who need to convert scanned documents or images into searchable, selectable PDFs or plain text/JSON files.
• Node.js developers who want to integrate local OCR capabilities into their applications via a typed API.

Highlights

• Privacy-First: Runs entirely on-device with no data uploads.
• Searchable PDFs: Converts images or scanned PDFs into PDFs with a selectable text layer.
• Structured Data: Supports extracting paragraphs, tables, and lists (on macOS 26+).
• Flexible Output: Supports plain text, JSON, and JSONL for streaming large documents.
• Partitioned OCR: An advanced strategy that recursively splits large pages to recover small text that standard full-page passes might miss.
• Crosspackage Support: Ships as an npm package with a prebuilt binary, requiring no Xcode or Swift toolchain for installation.