OMD.EXE // PUBLIC BETA 0.3.0b2

OMD.EXE

A local AI context inbox for Markdown, Obsidian, and agents.

Turn documents, web pages, screenshots, audio, folders, and selected public URLs into traceable Markdown that stays in folders you control.

Live demo · Install · Walkthrough · Documentation · Report an issue

Walkthrough

Related MCP server: MarkItDown MCP Server

How conversion stays recoverable

Core conversion never depends on AI. Optional model work is isolated, so a missing model or failed call leaves the raw Markdown intact.

Quick start

brew install omd-local/omd/omd
omd doctor
omd-ui

Choose Markdown file for a normal export or Capture to vault note for an Obsidian folder. An Obsidian vault is just a local folder; OMD does not require an Obsidian plugin or account.

For quick personal thoughts and exact highlights, open Inbox / review. The screen follows three steps: save the text, review the unchanged original, then choose Create note in Notes or Mark as not needed. Creating a note makes a traceable derivative under Notes/; either choice leaves the original under Inbox/. Saving and reviewing do not call AI.

The custom Homebrew tap includes the project organisation in the command. omd-local is the project owner, not a personal account. The beta installs the CLI, MCP server, local browser UI, common document converters, and yt-dlp. Large transcription and local-model tools remain optional.

Manual install

git clone https://github.com/omd-local/markdown-everything.git omd
cd omd
pip install -e '.[all]'
omd doctor

Python 3.10 or newer is required. A minimal pip install -e . registers omd and omd-mcp; the all extra adds the UI, MarkItDown, and Python yt-dlp.

Optional local model

OMD never downloads Ollama models automatically. Install and start Ollama, then run the model install command in Terminal. OMD recommends a conservative instruct model from the machine's total memory; this is a 16 GB example:

ollama pull qwen3:4b-instruct

Keep the UI host at http://localhost:11434 for fully local model calls. Core conversion still works when Ollama is absent or stopped.

Optional AI draft for one Inbox item

Inbox review can optionally ask local Ollama to draft a takeaway, quote exact evidence, and suggest tags. It reads the Inbox original by default. You may instead explicitly select one read-only Markdown file from the unified vault source list; OMD then uses only that file and can add its vault-relative [[wikilink]] to the derived note. It never opens a URL or reads an unselected file. Results without exact evidence are rejected, and the draft is not included in a note unless you choose it.

You can instead send the selected text directly to the OpenAI API, Anthropic API, or DeepSeek API using your own developer API key. Cloud providers show a one-request preview and consent action with the exact provider, model, destination, content size, and current policy link. This is never required for capture or conversion; OMD does not use consumer ChatGPT/Claude login sessions, route through OpenRouter, or silently fall back to another provider. UI credentials use macOS Keychain when available or remain session-only. OMD checks a conservative request budget before reading the credential or contacting the provider; an oversized Inbox item is left unchanged and must be split rather than being silently truncated.

Optional transcription and OCR

# Apple Silicon speech-to-text for audio, podcasts, and supported videos
brew install pipx
pipx install mlx-whisper

# Text recognition inside screenshots and article images
brew install tesseract tesseract-lang

OCR means optical character recognition: it reads visible text from an image. English uses eng; mixed Chinese and English can use chi_sim+eng. mlx-whisper is Apple-Silicon only and is intentionally excluded from the base install because its model stack is large.

• Documents: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPUB, and ZIP use MarkItDown.

• Images: PNG, JPG, WEBP, TIFF, and BMP use Tesseract OCR.

• Audio: MP3, WAV, M4A, FLAC, and OGG use local Whisper when installed.

• Web: articles, WeChat, and public webpages use a source adapter or web conversion.

• Public posts: Reddit, X, Bluesky, Mastodon, Threads, Hacker News, and Telegram use bounded public adapters.

• Media: Apple Podcasts, YouTube, TikTok, and Bilibili preserve metadata and use local transcription when available.

• Local batches: folders and saved one-item-per-line lists route each item independently.

OMD does not bypass paywalls, login gates, captchas, access controls, or platform restrictions. Public posts can be deleted, private, quarantined, region-blocked, or rate-limited; a URL that opens in your signed-in browser may still reject an anonymous converter.

Douyin and Xiaohongshu / Rednote

These advanced local-only routes normally need separate Netscape cookies.txt exports. Export cookies only from an account and content you are authorised to use, then select the matching file in the UI:

• Douyin cookies: export while signed in to douyin.com.

• Xiaohongshu cookies: export while signed in to xiaohongshu.com.

• Do not reuse one platform's cookie file for the other platform.

• Cookies are disabled in the hosted demo and should never be committed.

Use Inspect source / cookies before starting. OMD warns when the current source list contains one of these platforms but its matching cookie file is missing.

Direct Markdown

omd report.pdf -o report.md
omd screenshot.png -o screenshot.md --lang eng
omd bilingual.png -o bilingual.md --lang chi_sim+eng

Obsidian-compatible vault capture

omd capture report.pdf --vault ~/Obsidian/AI-Memory --tags research,pdf
omd capture "https://example.com/article" --vault ~/Obsidian/AI-Memory

Capture writes a readable note under Sources/<source type>/, updates Index/OMD Captures.md, and keeps hashes, route diagnostics, model errors, and other debug metadata in the adjacent .omd.json sidecar.

Optional local AI sections

omd report.pdf -o report.md --polish-md --polish-md-keep-raw
omd capture report.pdf --vault ~/Obsidian/AI-Memory --memory-cards

--polish-md cleans parser/OCR noise. --memory-cards adds a summary, useful tags, [[links]], and evidence-oriented cards above the preserved ## Full Content. Review all generated content before relying on it.

Read the Obsidian guide and memory cards guide. The optional provider boundary is documented in the privacy model.

# Inspect routing, tools, cookies, and local readiness without converting
omd inspect "<url-or-file>" --with-readiness

# Convert a folder or reusable one-item-per-line list
omd batch sources.txt -o out/
omd capture ~/Downloads/sources/ --vault ~/Obsidian/AI-Memory --batch

# Quiet deterministic output for agent-facing runs
omd --agent-safe report.pdf -o report.md

# Read-only vault-aware note enrichment proposal
omd enrich-note Inbox/example.md --vault ~/Obsidian/AI-Memory --json-events
omd enrich-note --request-json - --json-events < request.json
omd capabilities --json

enrich-note returns a validated proposal on stdout and never edits the vault. The complete v1 stdin/response/event contract is documented in the enrich-note contract. Obsidian plugin authors should also follow the plugin integration guide for capability negotiation, subprocess isolation, response validation, and the hash-checked Vault API write boundary.

omd-mcp exposes four tools:

• convert_to_markdown(uri, output?, output_format?, lang?, reel_options?)

• inspect_source(uri, include_readiness?, cookies?, cookies_from_browser?)

• capture_to_vault(uri, vault, lang?, tags?)

• list_supported_formats()

Minimal MCP configuration:

{
  "mcpServers": {
    "omd": {
      "command": "omd-mcp"
    }
  }
}

Treat converted Markdown as untrusted input. MCP restricts local paths and private-network URLs by default; use narrow OMD_MCP_ALLOWED_ROOTS only for folders you intend the client to access.

Run omd doctor for local capability checks. For a reproducible report, include a non-sensitive sample, the warning text, and --verbose output. Verbose logs are shown in the process log and are not added to the user-facing Markdown note.

git clone https://github.com/omd-local/markdown-everything.git omd
cd omd
pip install -e '.[all,test,audit]'
make smoke
make test

OMD builds on Microsoft MarkItDown, yt-dlp, f2, MLX Whisper, Ollama, and Tesseract.

Issues and focused pull requests are welcome. Read SECURITY.md before reporting a vulnerability. OMD is released under the MIT License.

Local-first, with explicit boundaries

Personal note use only. OMD is designed for personal research, note-taking, and AI-assisted knowledge workflows. It is not a legal, compliance, evidentiary, or archival system. Output may omit, reorder, or reformat source content. You are responsible for ensuring you have the right to access, process, and store each source. OMD does not bypass paywalls, access controls, or platform restrictions. Review AI-generated summaries, tags, Evidence, and [[links]] before relying on them.

Local-first does not mean every URL workflow is offline: URLs contact their source platform, and explicitly configured remote model endpoints receive the content sent to them. Keep private material in the local app with loopback Ollama. See the privacy model and security policy.

Documentation

LOCAL SOURCES -> TRACEABLE MARKDOWN -> CONTEXT YOU CONTROL

Star this repository · Open the demo · Report a bug · MIT License