Fully-local OCR for text-only LLMs. PaddleOCR-VL first-tier engine, tesseract fallback. Images never leave your machine.
简体中文 · Install guide · CLI manual · Troubleshooting · Output contract · Security
LocalOCR gives a text-only model (DeepSeek, GLM, any of them) real OCR sight, entirely on your machine. It reads local images with the first-tier PaddleOCR-VL-1.6 pipeline (layout analysis + VLM: text, tables, formulas, charts — SOTA on OmniDocBench) and falls back to tesseract when you want something lighter.
- Local by design. No API keys, no cloud, no network. Images never leave the machine.
- First-tier engine. PaddleOCR-VL-1.6, quantized and run through llama.cpp — fits comfortably on a 6GB GPU.
- Evidence, not guesses. Full transcription + reading-order layout regions + per-block coordinates + confidence scores, saved as both Markdown and structured JSON.
- Drop-in for dsh. One plugin row registers an
ocrtool a text-only DeepSeek Harness model can call directly. - Hermes-compatible. Ships a
skills/local-ocr-hermes/skill in the agentskills.io format, so NousResearch's hermes-agent can drive the same local engine.
dsh plugin --profile web add local-ocr-cliThen restart dsh. The ocr tool appears on every request.
See INSTALL.md — the Node CLI plus the Python engine (PaddleOCR-VL venv + llama.cpp GGUF server, tesseract optional).
Publishing to npm is fully automated via Trusted Publishing (OIDC) — no
tokens, no 2FA prompts, automatic provenance. Pushing a vX.Y.Z tag triggers
.github/workflows/release.yml, which runs
typecheck + test + build and then npm publish --provenance.
npm version patch # bumps version and tags vX.Y.Z
git push --tags # GitHub Actions publishes to npmlocal-ocr analyze shot.png --engine paddleocr --json
local-ocr analyze invoice.jpg --engine tesseract
local-ocr doctorOutput: JSON with text (markdown transcription), saved_to (md file),
json_to (structured JSON: blocks with bbox/order, layout boxes with
confidence). See the output contract.
| engine | what | needs |
|---|---|---|
paddleocr (default) |
PaddleOCR-VL-1.6: layout + VLM, SOTA | Python venv + llama.cpp GGUF server |
tesseract |
classic OCR, light | tesseract binary |
Both run locally. local-ocr doctor checks what is available.
| demo | what it shows |
|---|---|
| Japanese Instrument of Surrender | dense 1945 historical document: printed clauses + handwritten signatures + multi-nation signature block; 33 structured blocks, 39 layout boxes |
| Diamond Sutra Calligraphy | vertical traditional-Chinese Song-dynasty calligraphy, read in correct column order |
| doc | read when |
|---|---|
| CLI manual | every flag, subcommand |
| Configuration | setting up engines |
| Troubleshooting | a run failed |
| Capability boundaries | what the engine can and cannot read |
| Output contract | consuming the JSON |
| Security | what LocalOCR never does |
This project publishes to npm automatically via OIDC Trusted Publishing — see
the engineering-playbook npm OIDC guide
for the general recipe and failure modes. Short form: npm version patch && git push --tags.
MIT