pi-ocr

⚡ Zero setup. Works out of the box.

Default backend is MinerU — a free cloud API. No GPU, no API key, no pip install. Just pi install and /ocr.

OCR for Pi Coding Agent. Bridges the multimodal gap for non-vision LLMs like DeepSeek: when your model can't see images, pi_ocr reads them for you.

Quickstart

pi install npm:pi-ocr
/ocr ./screenshot.png
/ocr ./paper.pdf

That's all. MinerU (free cloud API) is the default — zero config.

The pi_ocr tool takes only a file path. Backend, model, and task are configured by the user via /ocr settings — the AI doesn't need to manage them.

Backends

Switch anytime with /ocr (no args).

| | Backend | Best for | Setup | |---|---|---|---| | ☁️ | MinerU (default) | PDFs, general docs | None | | ☁️ | MinerU Pro | Large PDFs, vlm accuracy | API token | | 🦙 | Ollama | Math formulas → LaTeX | GPU + 2.2GB model | | 🔤 | Tesseract | Plain text (~30MB) | brew install tesseract | | 📐 | Pix2Text | Math + text, GPU/CPU | pip install pix2text |

💡 Unsure which backend to pick? See the benchmark with real test results and the ground truth for comparison.

MinerU (default)

Free cloud API. Images are wrapped as PDF so language-aware OCR applies.

Limits: ≤10MB, ≤20 pages/request. PDFs >20 pages auto-split via pypdfium2.

MinerU Pro (vlm model)

Higher accuracy via token-based precision API. ≤200MB, ≤200 pages — no splitting needed.

Get a free token at mineru.net/apiManage, then set it in /ocr settings. 1000 pages/day high-priority.

Ollama

Local GPU OCR via glm-ocr — state-of-the-art formula recognition (94.6 OmniDocBench). Outputs LaTeX.

# macOS
brew install ollama && ollama pull glm-ocr
brew install poppler   # multi-page PDFs

# Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama pull glm-ocr
sudo apt install poppler-utils

Tesseract

Classic OCR engine. Ultra-lightweight (~30MB). No formula support — use Ollama or Pix2Text for math.

brew install tesseract              # macOS
sudo apt install tesseract-ocr      # Linux

Supports Chinese: brew install tesseract-lang (auto-installed on macOS).

Pix2Text

Mathpix alternative — handles text + formulas on GPU (CUDA/MPS) or CPU. Auto-detects best device.

pip install pix2text

First run downloads ONNX models (~50MB).

Settings

Open with /ocr (no args).

| Setting | Description | |---|---| | OCR Backend | Switch between MinerU, Ollama, Pix2Text, Tesseract | | MinerU: Split PDF >20 pages | Auto-split large PDFs into free-tier chunks | | MinerU Pro Token | API token from mineru.net/apiManage | | Ollama Model | Vision model (glm-ocr, minicpm-v, etc.) | | Clear OCR temp files | Remove cached OCR output from /tmp |

Output Behavior

Results ≤2000 chars are returned inline in the tool response. Longer results are written to a temp file (/tmp/pi-ocr-*.md); the tool response includes the file path for the AI to read.

Commands

| Command | | |---|---| | /ocr | Open settings (backend, model, split toggle, clear cache) | | /ocr <file> | OCR a file | | /ocr <file> formula | Math LaTeX output (Ollama backend) |

Troubleshooting

MinerU 429 → Wait a minute or switch backend.

MinerU Pro 401 → Regenerate token at mineru.net/apiManage.

"Is Ollama running?" → ollama serve

"pdftoppm not found" → brew install poppler / sudo apt install poppler-utils

"python3 not found" (Pix2Text) → pip install pix2text

"tesseract not found" → brew install tesseract / sudo apt install tesseract-ocr

License

MIT