A TUI markdown manager and knowledge base backed by Perkeep.
mdvault watches a directory of markdown files, indexes [[wiki-links]] and #tags, syncs everything to a Perkeep instance, and gives you a terminal UI to browse, search, and edit your notes.
Two modes, one binary:
mdvault daemon-- watches your notes directory, syncs changes to Perkeep, exposes a Unix socket APImdvault tui-- interactive terminal UI (connects to a running daemon, or runs standalone)
- File tree navigation with folder expand/collapse
- Markdown viewer with syntax highlighting
[[wiki-links]]with a live backlinks panel#tagfiltering- Inline quick-edit and
$EDITORshell-out for longer sessions - Bidirectional Perkeep sync with last-write-wins conflict resolution
- Filesystem watcher with debounced sync
- Daemon mode with Unix socket API
go install github.com/harperreed/mdvault/cmd/mdvault@latestCreate ~/.config/mdvault/config.toml:
[perkeep]
server = "http://localhost:3179"
[workdir]
path = "~/notes"
ignore = ["*.tmp", ".DS_Store"]
[editor]
command = "$EDITOR"
[daemon]
socket = "/tmp/mdvault.sock"
debounce_ms = 500# Start the background daemon
mdvault daemon
# Launch the TUI (connects to daemon if running, otherwise standalone)
mdvault tui| Key | Action |
|---|---|
j/k |
Navigate file tree |
Enter |
Open note |
e |
Edit inline |
E |
Open in $EDITOR |
t |
Filter by tag |
b |
Toggle backlinks panel |
q |
Quit |
Filesystem --> Watcher --> Sync --> Perkeep
^ |
| (on startup) |
+------ pull --------+
| Package | Purpose |
|---|---|
internal/config |
TOML config loading |
internal/index |
In-memory note index, wiki-link/tag parsing, backlink graph |
internal/parser |
Markdown frontmatter and link extraction |
internal/perkeep |
HTTP client for Perkeep permanode CRUD and blob ops |
internal/sync |
Bidirectional sync engine |
internal/watcher |
fsnotify-based file watcher with debounce |
internal/daemon |
Unix socket server/client for TUI-daemon communication |
internal/tui |
Bubbletea app with file tree, viewer, editor, backlinks, tag picker |
MIT