Thunderegg

Thunderegg — Obsidian Plugin

Convert any attachment in your vault — PDF, Word, Excel, PowerPoint, email, image, even meeting recordings (transcribed on-device) — to clean Markdown with YAML frontmatter, 100% on your Mac. Plus the Refinery: track note maturity, discover connections, and surface hub notes automatically.

The plugin is free and MIT-licensed. The app it drives is not. Thunderegg for macOS is converting is free and unlimited. Thunderegg Pro — recording meetings, transcription, the AI write-up and sync — is $19.95, once, no subscription and no account. This plugin is the Obsidian half; the Thunderegg app does the converting, and it is what you buy. thunderegg.ai

Disclosures

Stated plainly, in the order Obsidian's developer policies list them.

• Payment. This plugin is free, and so is everything it does: converting files with the Thunderegg app is free and unlimited. The app's paid tier, Thunderegg Pro, is $19.95 once and covers recording meetings, transcription, the AI write-up and sync, after three free recordings. Without the app installed the plugin converts nothing, but the app itself costs nothing to convert with.
• Account. None. There is no Thunderegg account. A purchase gives you a licence key, entered in the app.
• Closed-source code. This plugin is MIT-licensed and everything it runs inside Obsidian is in this repository. The Thunderegg app it calls is closed source and is installed separately, by you, from thunderegg.ai. The plugin never downloads, installs or updates it.
• Running a local program. To convert a file the plugin runs the app's converter, ~/Library/Application Support/MarkItDownDroplet/convert.sh, through Node's child_process. This is why the plugin is desktop-only and macOS-only.
• Files outside your vault. The plugin reads and writes notes inside your vault. It reads one path outside it, the converter above, and keeps the optional Canvas-publishing device token in the app's support folder rather than in your vault, so the token is never synced or shared with the vault.
• Network use. The plugin makes no network requests by default. The optional Canvas publish and fork commands contact a map server only if you enter one in Settings, and only when you run them. No public server exists today, so the field ships empty. Separately, if you connect a cloud AI provider inside the Thunderegg app, the app, not this plugin, sends note text to that provider to write summaries. Leave it unconnected, or mark the vault Local in the app, and nothing leaves your Mac.
• Telemetry and ads. None, client-side or server-side.

Three ways in

1. Right-click a file in the file explorer → Convert to Markdown (Thunderegg).
2. Right-click a folder → Thunderegg: convert all attachments (recursive).
3. ⌘P → Thunderegg: Convert clipboard — copy anything (a web page selection, an email, a table), run the command, and Thunderegg converts it into a new note called Clipboard <date>.md and opens it. Nothing to save to disk first.

The clipboard command is command-palette only — there is no ribbon icon and no menu item for it, so it is easy to miss. It is the fastest way to get something you are reading in a browser into your vault as clean Markdown.

Features

Conversion

• File menu: right-click a file → Convert to Markdown (Thunderegg)
• Folder menu: right-click a folder → Thunderegg: convert all attachments (recursive)
• Command palette:
  • Thunderegg: Convert file — convert the active attachment
  • Thunderegg: Convert clipboard — paste clipboard content (HTML or text), run it through Thunderegg, and create a new note
• Status bar: live indicator showing whether the Thunderegg engine is available (🟢 Ready / 🔴 Unavailable)
• Output is written next to the source as report.md for report.pdf (or report.pdf.md when that name is taken), with title/source/type/created/tags frontmatter.
• Recordings become meeting summaries: drop an audio or video file (mp3, m4a, wav, aiff, aac, flac, opus, mp4, mov, m4v, mkv, webm — Zoom, OBS, Discord and browser recordings included) and the engine transcribes it on-device and writes a structured summary — action items, decisions, notable quotes. Transcription takes a few minutes per recording; nothing is uploaded.
• To record a meeting, use the Mac app. This plugin converts recordings that already exist; it does not record. Click the microphone icon in the macOS menu bar → Start Recording (macOS 15 or later), then convert the saved file here or let the app write the note.

Refinery

Enable the Refinery in settings for Thunderegg's knowledge-management layer. It adds three concepts:

When Refinery is enabled:

• A Refinery info bar appears at the top of each note showing the note's Grade badge, Bond count, Condenser flag, and links to any Condensers that reference it.
• The status bar displays Grade / Bond / Condenser metadata for the active note.
• The bond graph is built from Obsidian's own metadata cache — zero parsing overhead.

How Grades work

Add a grade field to any note's YAML frontmatter:

---
grade: rough
---

Valid values: blank, rough, polished, crystal, gem (plus synthesis on generated map pages). Notes from before the 2026-07 rename (vapor, crude, distillate, refined, essence) are read forever and shown under their new names. The plugin reads Obsidian's metadata cache for instant display.

Requirements

• macOS (desktop-only — uses the on-device Thunderegg engine).
• The Thunderegg app — free to convert with, $19.95 once for Pro — installed, which provides ~/Library/Application Support/MarkItDownDroplet/convert.sh. The engine path is configurable in plugin settings.
• Image OCR uses the Apple Vision ocr helper that ships with the Thunderegg app. If image conversion fails with an OCR message, reinstall the Thunderegg app — that restores the helper.

Settings

How it works

The plugin shells out to the local Thunderegg engine via Node's child_process (allowed for desktop-only plugins). Conversion and transcription are entirely on-device — nothing is uploaded to convert. Frontmatter can be toggled off in settings (passes DISTILL_FRONTMATTER=0); the plugin also passes your vault's path (DISTILL_VAULT_PATH) so the engine's bond discovery links against this vault.

The Refinery reads from Obsidian's metadataCache.resolvedLinks to build the bond graph — no custom file parsing, no background workers.

Publish & Community (optional, off by default — and the one feature that CAN upload)

The plugin can publish an Obsidian Canvas as a signed concept map to a server you configure (Settings → Publish & Community), and import maps others share via obsidian://distill-fork links. No server is configured by default, so out of the box the plugin makes no network call at all. Once you set one, this is the only network call the plugin itself makes: nothing is sent by the plugin unless you explicitly run a Publish command, publishing sends only the selected Canvas (after a redaction scan for blocked tags), and the device token is stored outside your vault.

That is a claim about the plugin, not about the whole pipeline, and the difference matters. Conversion, OCR and transcription run entirely on your Mac. But if you have connected a cloud model in the Thunderegg app, the engine's AI enrichment step sends part of each converted note to that provider — the plugin never sees that request and cannot prevent it. Mark the vault Local in Thunderegg (or connect no cloud model) to keep everything on-device. The hosted community server is not currently online; the feature works against any server implementing the protocol.

Build from source

npm install
npm run build      # produces main.js

Install into a vault (manual / dev)

Copy manifest.json, main.js, and styles.css into:

<your-vault>/.obsidian/plugins/thunderegg/

Then enable Thunderegg in Settings → Community plugins.

Releasing an update (the plugin is already in the community catalog)

The plugin is listed in the official Obsidian directory as thunderegg. To ship an update:

1. Bump version in manifest.json and add the same version to versions.json — always, even when minAppVersion did not change. Obsidian picks the newest version whose versions.json entry its app version satisfies, so a MISSING key does not mean "unchanged", it means "skip this release". 0.2.1-0.2.3 were absent for exactly this reason and every Obsidian 1.4.0-1.6.5 user silently resolved back to 0.2.0.
2. npm test && npm run build.
3. Tag a release named exactly the version, with manifest.json, main.js, and styles.css as assets — Obsidian serves updates from the GitHub release, no new catalog PR needed. ⚠️ This step has been forgotten twice: a fix committed to the repo reaches nobody until a release is cut under a bumped version.

Note: Obsidian's review guidelines require desktop-only plugins that run shell commands to clearly disclose it. The description and this README state that the plugin executes a local helper script; keep that disclosure if you edit copy.

Status

v0.2.12. On top of the v0.1.0 conversion features: the Refinery (rock-ladder grades with permanent legacy-name reads), audio/video → on-device meeting summaries, .doc/.rtf support, vault-aware bond discovery (DISTILL_VAULT_PATH), clipboard conversion, status-bar indicators, and the Canvas publish/verify/fork surface (disclosed above).