Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chrisgrieser/shimmering-obsidian/llms.txt

Use this file to discover all available pages before exploring further.

Most issues with Shimmering Obsidian fall into one of a few categories: the Metadata Extractor plugin is not configured or has not run yet, a workflow variable is set incorrectly, or a required external tool is missing. Work through the accordion below that matches your symptom — most problems are resolved in under a minute.
For bugs or feature requests not covered here, please open a GitHub issue at github.com/chrisgrieser/shimmering-obsidian/issues. Include your macOS version, Alfred version, and workflow version when reporting a bug.
Shimmering Obsidian does not search your vault files directly. Instead, it reads JSON metadata files produced by the Metadata Extractor plugin. If those files are stale or missing, recently created or renamed notes will not appear.Steps to fix:
  1. Run oupdate in Alfred. This forces the Metadata Extractor to rewrite its JSON files immediately and refreshes the workflow’s index.
  2. Open Obsidian’s plugin settings for Metadata Extractor and confirm:
    • Write JSON files automatically when Obsidian launches is enabled.
    • The write frequency is set to a reasonable interval (e.g., 30 minutes).
  3. Verify that the metadata files exist on disk: 
    {vault_path}/.obsidian/plugins/metadata-extractor/metadata.json
{vault_path}/.obsidian/plugins/metadata-extractor/canvas.json
  4. If the files are absent even after running oupdate, restart Obsidian and check that the plugin is enabled under Settings → Community Plugins.
Do not rename or move the JSON files produced by Metadata Extractor — the workflow expects them at a fixed location inside the plugin folder.
This error appears in Alfred search results when the metadata.json file produced by the Metadata Extractor plugin cannot be found at the expected path.Common causes and fixes:
  • Metadata Extractor is not installed. Install it from Obsidian’s Community Plugins browser and enable it.
  • Metadata Extractor is installed but auto-write is disabled. Open Settings → Metadata Extractor in Obsidian and enable Write JSON files automatically when Obsidian launches, then restart Obsidian.
  • Obsidian has never been launched since installing the plugin. The plugin only writes its files after Obsidian starts. Restart Obsidian, then run oupdate in Alfred.
  • The plugin has been disabled. Re-enable it under Settings → Community Plugins and restart Obsidian.
After correcting any of the above, run oupdate to immediately regenerate the metadata files.
This error means Alfred cannot locate the Obsidian configuration folder inside your vault. The workflow looks for a folder named by the config_folder variable (default: .obsidian) at the path set in vault_path.Steps to fix:
  1. Open Alfred Preferences → Workflows → Shimmering Obsidian → Configure Workflow.
  2. Check that vault_path points to the root of your Obsidian vault — the folder that contains .obsidian, not a subfolder inside it.
  3. Check that config_folder matches the actual name of your config folder. Unless you have specifically configured a custom config folder in Obsidian’s settings, this should be .obsidian.
  4. If you recently moved or renamed your vault, update vault_path to reflect the new location.
You can verify the correct path by opening Finder, navigating to your vault, and pressing ⌘ + ⇧ + . to reveal hidden folders — you should see .obsidian inside the vault root.
The OCR screenshot feature requires Tesseract and macOS screen recording permission for Alfred.Step 1 — Install Tesseract.If Tesseract is not installed, run:
brew install tesseract tesseract-lang
Confirm the installation succeeded with:
tesseract --version
Step 2 — Grant screen recording permission.macOS requires explicit permission for any app that captures screen content. To grant it:
  1. Open System Settings → Privacy & Security → Screen Recording.
  2. Ensure Alfred is listed and its toggle is enabled.
  3. If Alfred does not appear, trigger the OCR screenshot hotkey once — macOS should prompt you automatically.
Step 3 — Check the ocr_languages variable.Open Alfred Preferences → Workflows → Shimmering Obsidian → Configure Workflow and verify that ocr_languages is set to a valid Tesseract language code (e.g., eng). Use + to combine multiple languages (e.g., eng+deu). Language codes are listed on the Tesseract data files page.If you installed only tesseract (without tesseract-lang), additional language packs may be missing. Re-run brew install tesseract-lang to install the full set.
Shimmering Obsidian uses macOS’s native Quick Look to preview Markdown notes (triggered by ⇧ or ⌘ + Y on any search result). Markdown preview requires a Quick Look extension that understands .md files.Option 1 — QLMarkdown (free)
  1. Download and install QLMarkdown.
  2. Important: Launch QLMarkdown.app at least once by right-clicking → Open to allow macOS to trust it. The app does not need to stay open.
  3. To enable correct rendering of YAML front matter, open QLMarkdown’s preferences and enable the YAML header option in the Advanced section.
Option 2 — Peek (paid, ~€5)Peek supports Markdown and many other file types with no additional setup.Tip — avoid accidental triggeringIf previews open unintentionally while browsing results, disable the ⇧ Quick Look activator in Alfred Preferences → Features → Previews and use ⌘ + Y exclusively.
The ow workspace switcher reads workspaces stored by Obsidian’s core Workspaces plugin. If the list is empty, either the plugin is off or no workspaces have been saved yet.Steps to fix:
  1. In Obsidian, open Settings → Core Plugins and enable the Workspaces plugin.
  2. Arrange your panels the way you want, then open the Workspaces panel (ribbon icon or command palette) and save the current layout as a named workspace.
  3. Return to Alfred and run ow — your saved workspace should now appear.
Shimmering Obsidian controls exactly one vault at a time, determined by the vault_path workflow variable.To switch control to a different vault:
  1. Run ov in Alfred to open the vault switcher.
  2. Find the vault you want to control, then press ⇧ + ⏎ on it. Alfred will update vault_path automatically.
If the vault switcher itself shows the wrong vault:Open Alfred Preferences → Workflows → Shimmering Obsidian → Configure Workflow and manually correct vault_path.Requirements for each vault:Every vault you want to control with Shimmering Obsidian must have both the Advanced URI and Metadata Extractor plugins installed, enabled, and — for Metadata Extractor — configured with auto-write enabled. These plugins cannot be shared across vaults.
The o search respects the Excluded Files list configured in Obsidian Settings → Files & Links → Excluded Files. Files and folders on that list are filtered out from search results.Limitations to be aware of:
  • Only simple path and filename prefix exclusions work. If you have entered a regex-based filter (a filter beginning with /) in Obsidian’s excluded files list, the workflow will not apply it — regex patterns are not supported by Shimmering Obsidian’s search logic.
  • Exclusions are applied at the time the Metadata Extractor writes its JSON files. If you added a new exclusion recently, run oupdate and restart Obsidian to ensure the metadata reflects the updated list.
If a file you expect to be excluded still appears, double-check its exact path against the entries in Obsidian’s excluded files list and confirm you are not using a regex pattern.

Build docs developers (and LLMs) love

Get started for freeTalk to us