Muninn

A local-first Markdown vault with an Obsidian-style wikilink graph, built with Rune.

Muninn treats a folder of .md files as the whole database. Every note is a file you can read, move, diff or put in version control. Links are written as [[Note]], [[Note|alias]] or [[Note#heading]]; the app indexes them and draws the result as a graph.

Write	Graph

Quick start

Muninn needs Rust 1.99.1 (the pinned toolchain in rust-toolchain.toml). On Linux, install the usual windowing headers first:

sudo apt-get install -y pkg-config libxcb-render0-dev libxcb-shape0-dev \
  libxcb-xfixes0-dev libxkbcommon-dev libwayland-dev libgl1-mesa-dev

Run it against the committed sample vault:

cargo run -p muninn-app -- --vault vault

Or point it at your own notes:

cargo run -p muninn-app -- --vault ~/notes
MUNINN_VAULT=~/notes cargo run -p muninn-app

Without --vault or MUNINN_VAULT, Muninn reopens the last vault recorded in its settings file (falling back to ~/Muninn, created when needed).

Headless checks

Two commands inspect a vault without opening a window (no GPU context is created):

cargo run -p muninn-app -- --check ~/notes
cargo run -p muninn-app -- --list-links ~/notes

--check prints the note count, every broken link as referrer -> target, duplicate titles with their note counts, the skipped-file count and a folder-depth warning. It exits 0 when clean, 1 when there are broken links or duplicate titles, and 2 when the path is not a readable vault folder. It never creates a missing folder. --list-links prints one sorted referrer -> target line per wikilink, with unresolved targets prefixed missing:. muninn --help prints this usage without starting Rune, and muninn --version (or -V) prints muninn <version>, the workspace version from Cargo.toml.

Settings and vaults

Preferences live in $XDG_CONFIG_HOME/muninn/settings.json (fallback ~/.config/muninn/). The file is small JSON and is updated as you change things; a corrupt or missing file starts from defaults instead of blocking startup. It remembers the theme, collapsed folders, the last vault and note, Write/Read/Graph/Board mode, Global/Local scope, the autosave delay (0.55 s by default), the default note template, the Reduce motion choice, the tray, start-at-login and shortcut switches and up to five recent vaults. Cmd/Ctrl+, opens the in-window Settings modal, split into tabs: Vaults (open or create a vault, or reopen a recent one), Editor (step the autosave delay, 0.05–10 s, and the default note template), Appearance (Omarchy / System / Dark / Light, Show tray icon, Close to tray, Start Muninn at login and Show Muninn with Ctrl+Alt+M), Graph (Reduce motion: System / On / Off) and Sync (provider, remote, Connect, Sync Now and Disconnect; see Sync). Show tray icon is off by default and saved as tray_icon. When on, Linux and Windows show a tray icon with Show Muninn, New note, Sync now (greyed until a provider is connected for this vault, and while a sync runs), the current sync status (a disabled row) and Quit Muninn; clicking the icon shows and focuses the window. On Linux it appears where a StatusNotifierItem tray host runs (KDE, waybar and most bars; GNOME needs an AppIndicator extension). The menu is flat: Rune's tray has no submenus. Close to tray (off by default, close_to_tray) makes closing the window hide it while a tray icon is up; Quit Muninn in the tray saves and quits. Without a tray icon (switch off, icon failed, macOS) closing quits as before. Muninn cannot tell whether a tray host actually shows the icon, so leave Close to tray off on a desktop without one. Only one Muninn runs at a time: launching it again (from the app launcher, or with --vault PATH) brings the running window back, switching to that vault when one is named, instead of starting a second app with a second tray icon. --new-instance starts a separate app anyway. Both switches are disabled on macOS, which Rune's tray does not support yet. Start Muninn at login (off, auto_start) writes $XDG_CONFIG_HOME/autostart/muninn.desktop on Linux and a Muninn value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run on Windows, and removes it when turned off; it is disabled on macOS. Show Muninn with Ctrl+Alt+M (off, ; ⌃⌥M on macOS) registers a system-wide shortcut that shows and focuses the window. On Wayland it goes through the desktop portal, which may ask first or let you pick another key; if the chord is taken or unsupported, the reason shows under the switch. Settings always opens on the Vaults tab; the selected tab is not saved. A non-empty default note template is inserted verbatim at the top of every new note (a trailing newline is added when missing); an empty template keeps the plain body. Choices persist immediately, and returns to the editor or search field that opened it. While Omarchy is followed the modal says so instead of offering a theme choice, matching the hidden sidebar theme toggle.

The default theme follows the shared Omarchy system theme (~/.local/state/omarchy/current/theme/colors.toml), so omarchy theme set recolours the window live and the sidebar theme toggle hides while Omarchy is followed (it is the system theme, not a switcher stop). Off Omarchy it falls back to the system appearance; a diverged session's toggle cycles System → Dark → Light, and muninn --theme omarchy|system|dark|light overrides that for one session. MUNINN_OMARCHY_COLORS can point at a palette file.

This is the beginning of the README. Read the rest at the original. Read the full README ↗