nutritious.md

Give Claude better documents.

nutritious-md is a Claude Code plugin that automatically converts PDFs, Word documents, PowerPoint presentations, Excel sheets, HTML, audio and other supported formats into clean Markdown before Claude reads them.

Built on top of Microsoft's MarkItDown, it improves document understanding, reduces unnecessary tokens, and works completely transparently—you keep using Read exactly as before.

MarkItDown is consumed as an installed dependency (pip install "markitdown[all]" into an isolated, plugin-local virtualenv) — it is never forked or vendored into this repo.

Why

Claude Code's built-in Read tool hands the model raw bytes for binary formats. For PDFs, Word/Excel/PowerPoint documents, and HTML, that means the model either can't parse the file at all or wastes context tokens on non-textual noise. nutritious-md intercepts those reads and hands back clean Markdown instead — automatically, with no change to how you ask Claude to read a file.

What it does

• Automatic interception. A PreToolUse hook watches every Read call. If the target file matches .pdf, .docx, .pptx, .xlsx, .xls, .html, or .htm, the hook converts it via MarkItDown and transparently redirects the read to the converted Markdown — the model never sees the original bytes.
• Explicit fallback. A convert skill and a /nutritious-md:convert <path> slash command cover cases the hook doesn't — e.g. a file referenced by URL, or read through a tool other than Read.
• Isolated dependency. MarkItDown installs into a virtualenv scoped to the plugin directory (plugins/nutritious-md/.venv), created lazily on first use. It never touches your system Python or Claude Code's own environment.
• Fails open, never blocks. If conversion fails for any reason (corrupt file, unsupported format, missing dependency, scanned PDF with no text layer), the original Read behavior is used instead — you always get a result, just not always Markdown.

Repository layout

nutritious.md/                          
├── .claude-plugin/
│   └── marketplace.json                
├── plugins/
│   └── nutritious-md/                  # the plugin
│       ├── .claude-plugin/plugin.json  # plugin manifest
│       ├── hooks/hooks.json            # PreToolUse hook registration
│       ├── skills/convert/  # explicit-invocation skill
│       ├── commands/convert.md         # /nutritious-md:convert
│       ├── scripts/                    # setup_env.sh, convert.py, pre_read_convert.sh
│       ├── requirements.txt            # markitdown[all]
│       ├── NOTICE.md                   # MarkItDown attribution
│       └── README.md                   # plugin-specific docs
├── LICENSE
├── CHANGELOG.md
└── README.md                           # you are reading me

See plugins/nutritious-md/README.md for implementation details (hook contract, file-by-file breakdown, manual test commands).

Requirements

• Claude Code CLI with plugin support.
• Python 3 with the venv module available.
  • Debian/Ubuntu: if python3 -m venv fails with ensurepip is not available, install the matching version package first:

    sudo apt install python3.10-venv   # match your `python3 --version`

• No other setup — setup_env.sh bootstraps everything else on first use.

Install

1. Launch Claude Code.

2. Run /plugins (plugins).

3. Move to Marketplaces tab.

4. Select + Add Marketplace.

5. Choose From GitHub Repository.

6. Paste the repository URL:

   https://github.com/om-mega/nutritious.md
   

7. Install nutritious-md from the newly added marketplace.

That's it. Restart Claude Code (or start a new session) if it was already running so the plugin hooks are loaded.

Verify

Run:

claude /plugin

You should see:

nutritious-md • om-mega
Convert PDFs/Office files to Markdown automatically before...

listed as enabled.

Usage

Automatic (no action needed): just ask Claude Code to read a matching file — e.g. "read report.pdf and summarize it." The hook converts it behind the scenes; Claude sees Markdown.

Explicit, via the skill: reference a document file in conversation ("convert this docx to markdown") — Claude will invoke the convert skill directly.

Explicit, via the slash command:

/nutritious-md:convert path/to/file.pdf

If a file has no extractable text (e.g. a scanned PDF with no OCR layer), Claude will tell you the extraction came back empty rather than silently failing or hanging.

Uninstall

claude plugin uninstall nutritious-md@om-mega
claude plugin marketplace remove om-mega

Limitations (v0.1.0)

• No OCR — scanned/image-only PDFs return an empty-text warning, not text.
• No caching — every matching Read re-runs the MarkItDown conversion.
• Bash-only hook scripts — no Windows/PowerShell equivalent yet.
• No pagination/truncation for very large source files.

Full rationale and planned follow-ups: docs/nutritious-md-spec.md §6.

Contributing

This is a small, single-purpose plugin — issues and PRs for bug fixes, additional format support, or the v0.2 items above are welcome. Please keep changes scoped: this repo intentionally does not vendor or modify MarkItDown, and any new binary-format handling should go through it rather than a bespoke parser.

Attribution

This plugin depends on Microsoft's MarkItDown (MIT licensed) as an installed dependency — see plugins/nutritious-md/NOTICE.md for full attribution. MarkItDown is not forked or vendored; it is installed via pip install "markitdown[all]" into a plugin-local virtualenv. Use of the MarkItDown name here is descriptive only and does not imply Microsoft endorsement.

License

MIT - see LICENSE. MarkItDown itself is separately MIT licensed by Microsoft Corporation.