Transmute

by Johannes Kaindl
5
4
3
2
1
Score: 53/100

Description

Search and replace by intent — a local LLM writes the regex, you review every match before it runs.

Reviews

No reviews yet.

Stats

0
stars
431
downloads
0
forks
116
days
4
days
4
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
247
commits

Latest Version

5 days ago

Changelog

Changed

  • The model row follows the endpoint manager more closely (shared library obsidian-kit 0.93.0): when the manager is switched off or comes back, the model row notices within about two seconds and redraws, without a restart.
  • A removed iframe, frame, object or embed in a model answer stays in the page for another 250 ms as a hidden, empty shell (link guard of code-kit 0.73.0). The error box "A JavaScript error occurred in the main process" that Obsidian could show for an iframe with an app:, relative or file: target no longer appears.

README file from

Github

Transmute

🇬🇧 English · 🇩🇪 Deutsch

Describe what to replace in plain language — a local LLM writes the regular expression, and you review every match before anything is written.

License: AGPL-3.0 Docs: CC BY-SA 4.0 Release Platform

Features

  • Natural-language search & replace. Describe the change in your own words; a local OpenAI-compatible LLM (or Claude, through the LLM Endpoint Manager) turns it into a regular expression, a replacement and a plain-language explanation.
  • Preview before anything is written. Every match is shown before/after with its own checkbox — only the checked ones are written.
  • One undo step. Applying goes through the editor, so Cmd+Z reverts it in one step.
  • Refine and go back. Follow up with "but not inside code blocks"; every round is kept in a history you can return to.
  • Scope up to the whole vault, with a snapshot before every vault-wide replacement and a one-click restore.
  • Safety by measurement. Generated patterns are screened for runaway backtracking; hand-written ones are timed on a sample before they run.
  • "Why doesn't this match?" A button that measures relaxed variants of the pattern and explains the miss.
  • A library of saved rules. The panel's "Library" tab lists your saved rules; one click on "Run" loads a rule for the current note or selection and shows the preview, without asking the model.
  • Model-agnostic and bilingual. No model name is hard-coded, endpoints can be local or hosted, reasoning models are handled, the interface is English and German.

All features in detail: Features and usage.

Requirements

  • Obsidian 1.8.7+ (desktop or mobile).
  • An OpenAI-compatible local server (e.g. LM Studio or Ollama) with a chat-capable model loaded. New to local LLMs? The local LLM setup guide walks you through server, model and mobile access end to end. The endpoint and model are configured in the plugin settings — with a local server nothing leaves your machine.
  • Optional: Claude (Anthropic). With the LLM Endpoint Manager plugin and a Claude entry in it, Transmute can use Claude instead of a local model; then the instruction, a text sample (the open note if it is in scope, otherwise up to the first three notes of the scope with their paths, capped by "Text sample sent to the model", 2000 characters by default), and when you refine, your earlier instructions and rules and up to three matching lines go to Anthropic. A vault-wide run sends the same kind of sample, not the whole vault. Transmute sees a Claude entry only through the manager, and with the choice on "Automatic" the first reachable, enabled chat entry in the manager's list order wins, so a Claude entry above your local one is used first; pick your local endpoint explicitly in the settings, or move it up in the manager's list, to stay local. The fixed temperature 0 of a run is not sent to Claude (the API rejects it), so "same input, same rule" is not guaranteed there.
  • On model size, if your interface is not English. Transmute names the target language in every prompt, but a very small model may still drop that instruction while it is busy hitting the JSON format. Measured against a local LM Studio: a 35B mixture-of-experts model answered in German 5 times out of 5, a 2B model 4 out of 5. Patterns are unaffected — this is about the plain-language explanation and diagnosis. If you want reliable explanations in your own language, give it a mid-size model.

Install

Search for Transmute in Settings → Community plugins → Browse, then click Install and Enable.

Manual

Download main.js, manifest.json, and styles.css from the latest release and place them in <vault>/.obsidian/plugins/transmute/, then enable the plugin under Settings → Community plugins. Or download transmute.zip from the release — it contains exactly these files — and unpack it into .obsidian/plugins/; checksums.sha256 lets you verify the download.

From source

git clone https://git.jkaindl.de/jkaindl/obsidian-transmute
cd obsidian-transmute
npm install
npm run build   # produces main.js

Then copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/transmute/ and reload Obsidian.

Usage

  1. Point the plugin at your local server and make sure a model is loaded — the endpoint and model are set under Settings → Community plugins → Transmute (see the settings table).
  2. Open the panel with the ribbon icon "Transmute" or the command "Open panel".
  3. Pick a scope: "Whole note", "Selection" or "Whole vault".
  4. Describe the change, e.g. "turn dates like 26.09.2026 into 2026-09-26", and click "Preview".
  5. Review the matches, deselect what you don't want, refine if needed.
  6. Click "Apply" — Cmd+Z reverts it in one step; a vault-wide run writes a snapshot first and offers "Undo".

The full walkthrough, the vault-scope differences and every setting: Features and usage.

Configuration

Open Settings → Community plugins → Transmute; the settings are grouped under "Connection" and "Behaviour". The ones you will touch first:

  • Endpoints — an ordered list of OpenAI-compatible servers (local or hosted, each with an optional API key); the first reachable one is used. With the LLM Endpoint Manager plugin installed, endpoints and keys come from there, and a Claude entry of the manager can be used too (the note content then goes to Anthropic, see Requirements). Enter the base URL without a trailing /v1.
  • Model (per endpoint row) — each row carries its own model; empty lets the server pick whatever is loaded. The model row at the top of the panel (dropdown, refresh button, thinking toggle) writes into the active row.
  • Request — the sampling values and the thinking level that are sent (collapsible).
  • Default scope — "Whole note", "Selection" or "Whole vault".
  • Thinking (in the Request section, also a toggle in the panel) — off by default; faster and more reliable answers from reasoning-capable local models.

Every setting with its default and effect: settings table.

How it works

Transmute sends your instruction, plus a sample of the scope text, to the configured endpoint's /v1/chat/completions and asks for a single JSON object — regex, flags, replacement, explanation — never prose. The answer is parsed leniently (code fences and any <think> block are stripped, the first balanced JSON object is extracted), and one retry with the concrete error is sent back to the model if the first answer doesn't parse or validate.

Before the generated pattern ever runs, a static heuristic screens it for constructs known to cause catastrophic backtracking — nested quantifiers, quantified alternation over identical or overlapping branches, the same item repeated twice in a row, unbounded backreferences — and rejects it with a plain-language reason if it looks dangerous. A pattern that passes is then executed line by line against the scope text under a configurable time budget; multi-line patterns (an s/m flag, or a literal \n in the pattern) run once against the full text instead, since a time budget only makes sense between discrete steps.

Nothing is written to your note until you click "Apply". At that point, only the checked matches are applied — in reverse order, so earlier replacements never shift the offsets of later ones — and the result is written through Obsidian's editor API (editor.replaceRange), which is what puts the change on the normal undo stack.

Documentation

New here? Start with Getting started. Something not working? See Troubleshooting. The documentation index lists everything; it follows the Diátaxis framework:

  • Tutorial — get from zero to your first applied replacement.
  • How-to guides — task-focused recipes (multiple endpoints, refining a rule, undoing, handling an unsafe-pattern error).
  • Reference — settings, commands, error messages, the JSON contract.
  • Explanation — why preview-before-apply is the core of the design, why there is no separate snapshot system, and why the safety guard has no web worker to lean on.

See the changelog for release notes.

ksawl/obsidian-alchemist shares the alchemy/transmutation imagery but a different job: it is a general vault-hygiene toolkit. Transmute is narrowly about turning a plain-language instruction into a reviewed, applied regex replacement — it does not aim to cover vault hygiene more broadly.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the workflow (test-driven, main always green, feature work in feat/<name>, Conventional Commits) and AGENTS.md for the architecture and module conventions. The canonical repository lives on Forgejo; GitHub (johannes-kaindl/obsidian-transmute) is a mirror.

License

  • Code: AGPL-3.0-or-later. A commercial dual-license is available on request if the AGPL copyleft does not fit your use case.
  • Documentation and text: CC BY-SA 4.0.

Copyright © 2026 Johannes Kaindl.