LocalOCR
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
ocr tool 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.
Install (DeepSeek Harness)
dsh plugin --profile web add local-ocr-cli
Then restart dsh. The ocr tool appears on every request.
Install (anywhere)
See INSTALL.md — the Node CLI plus the Python engine (PaddleOCR-VL
venv + llama.cpp GGUF server, tesseract optional).
Releases (maintainers)
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 npm
Usage
local-ocr analyze shot.png --engine paddleocr --json
local-ocr analyze invoice.jpg --engine tesseract
local-ocr doctor
Output: 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.
Engines
| 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.
Examples
| 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 |
Docs
Releasing (maintainers)
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.
License
MIT
