meltify

Turn files of any format into prompt-ready text, with a citation on every block

Agents misread blurry digits, miss text a PDF hides, and can't watch video. meltify turns documents, spreadsheets, slides, mail, chat exports, archives, web pages, images, video, and audio into markdown your agent can quote, and every block says where it came from.

• Images and scans can be cross-checked by more than one OCR engine, your agent's own reading included, and any number they disagree on gets flagged
• PDFs are checked for text a reader can't see
• Videos keep their key frames next to the transcript
• Everything runs locally by default. Paid APIs only run when you ask for them

Quickstart

meltify runs on macOS and Linux with Python 3.11.9 or newer. Windows isn't supported, since the plugin launcher is a POSIX shell script.

Claude Code:

/plugin marketplace add jeon-jihyeon/meltify
/plugin install meltify@meltify

Codex, Gemini CLI, Cursor, and other agents that read Agent Skills:

npx skills add jeon-jihyeon/meltify

Command line:

uvx meltify read ./inputs

Python, after pip install meltify:

import meltify

env = meltify.read("./inputs", out="melted")
for row in env.results:
    print(row["cite"], row["out"], row["needs"])

The plugin comes with two skills: meltify-read tells your agent when to melt files and how to use the result, and meltify-doctor checks what's installed. If the meltify command isn't on your path, the plugin runs it through uvx, so uv is all you need.

What you get

Point read at a folder with a PDF and an email that carries a spreadsheet:

$ meltify read inputs
kind   chars  needs              out                                         cite
mail   133                       meltify-out/read/handover.eml.md            inputs/handover.eml
sheet  151    hidden sheets Old  meltify-out/read/handover.eml__cal.xlsx.md  inputs/handover.eml#att=cal.xlsx
pdf    99                        meltify-out/read/report.pdf.md              inputs/report.pdf
artifact results: meltify-out/read/index.jsonl
3 items melted into meltify-out/read, 0 errors, 1 need more work

The attachment became an item of its own, and every block in its markdown starts with the cite to quote:

<!-- meltify source: inputs/handover.eml#att=cal.xlsx -->
## inputs/handover.eml#att=cal.xlsx#Calendar
| row | A | B |
|---|---|---|
| 1 | date | event |
| 2 | 2025-07-21 | handover meeting |
| 7 |  | budget review |

The needs column tells you what's still unread and why, like a hidden sheet, a password, or OCR that ran out of time. Add --json for the full result. The reference covers every field, every cite format, and the exit codes.

Cites look like this:

Taking a closer look

read handles most files with no flags at all. When one image, PDF, or video needs more attention:

Supported formats

A few things that happen along the way:

• Attachments, archive members, and downloads become items of their own, up to three levels deep
• Pictures inside documents are OCR'd in place, and charts turn into tables built from the values the file saved
• Each picture is also saved as a small WebP beside the markdown and linked from its block, so you can look at a chart or photo the text can't capture. --no-pictures skips it
• A file no converter reads gets another shot through LibreOffice, Pillow, ffprobe, or Quick Look on macOS
• Engine results are cached by content hash, so a rerun only pays for what changed. --budget caps new OCR and speech work at 600 seconds by default, and --shallow skips it entirely
• Encrypted files open with --password-file PATH or MELTIFY_PASSWORD. DRM-protected HWP files and pre-2014 binary Hancom files can't be read, and the reference lists the other gaps
• URLs get the page's main text, or the document or video behind them. Private addresses are refused and robots.txt is respected. See SECURITY.md

Engines

auto only uses local engines and endpoints you serve. Paid engines run when you name them in meltify.toml or on the command line. Your agent can also hand in its own reading of an image with meltify read IMAGE --reading agent=FILE, and meltify cross-checks it against the local engines, no API key needed.

meltify doesn't bundle or download models. To add one, serve it behind an OpenAI-compatible endpoint and point meltify at it. For example, PaddleOCR-VL on Apple Silicon:

uvx --from mlx-vlm mlx_vlm.server --model PaddlePaddle/PaddleOCR-VL-1.6 --port 8111

[ocr.endpoints.paddle-vl]
base_url = "http://127.0.0.1:8111/v1"
model = "PaddlePaddle/PaddleOCR-VL-1.6"

Each endpoint is an engine named after its table, and auto runs it next to Apple Vision with no key. It's still a vision LLM that can guess, so a value it reads counts as agreed only when a local engine like Apple Vision reads it too. Only loopback and private addresses qualify, even when you name the endpoint, so a hosted API runs only as the claude, gemini, or openai engine. key_env, timeout, and prompt are there when a server needs them, [asr.endpoints.NAME] does the same for speech without prompt, and meltify doctor checks that each one answers.

Agreement means the engines read the same value, not that the value is right, and a value only LLM engines read is never marked agreed. With a single engine every reading is marked unchecked, and on Linux, where there's no Apple Vision, LLM readings stay unchecked or disputed.

Run meltify doctor to see what's available. meltify doctor --install NAME adds an optional part: under the plugin, it installs into the plugin's own venv, and anywhere else it prints the right command for your setup, like uv tool install 'meltify[office]'. With uvx, use uvx --from 'meltify[office]' meltify ....

all bundles office, archive, parquet, crypto, and media. Recordings need ffmpeg, and YouTube downloads need deno. LibreOffice covers PowerPoint 95, formula recalculation, and the fallback renderer, and meltify doctor --install libreoffice downloads a portable copy.

Configuration

Settings stack up from lowest to highest precedence:

1. Built-in defaults
2. ~/.config/meltify/config.toml (or under $XDG_CONFIG_HOME)
3. The nearest meltify.toml, from the working directory up to the git root, or the file passed with --config
4. MELTIFY_<KEY> and MELTIFY_<SECTION>_<KEY> environment variables
5. Command-line flags

examples/meltify.toml shows the settings you're most likely to change, and defaults.toml lists every one. Misspelled keys show up as warnings. A few worth knowing:

• lang: the language OCR expects, ko by default. --lang overrides it for one run (ko, en, ja, zh, de, fr, or es)
• asr.lang: the spoken language, auto by default so Whisper detects it per recording instead of translating
• render.quicklook = false: keeps Quick Look and Spotlight out of every render

License

MIT. meltify depends on PyMuPDF, which is AGPL-3.0, so distributing a product that bundles it comes with AGPL obligations. The pi-heif wheels bundle libheif and libde265 (LGPL-3.0), and the iwork extra pulls in enum-tools (LGPL-3.0) through numbers-parser. The programs doctor --install downloads keep their own licenses: LibreOffice is MPL-2.0, and 7-Zip is LGPL-2.1 with the unRAR restriction.