ZenNotes: a Vim-first Markdown vault that also speaks MCP
Keyboard-first local Markdown notes with Vim motions, diagrams, and MCP integration.
At a glance
- What is it?
- ZenNotes is an MIT-licensed Electron and web notes app that keeps every note as a plain .md file and adds Vim motions, panes, CSV databases and a first-party MCP server. The interesting part is the shared app core across desktop and self-hosted modes; the awkward part is that the README itself admits the code is written with heavy AI assistance.
- Who is it for?
- Adopt ZenNotes if you already keep a folder of .md files and want Vim motions, split panes and an MCP server reading that same vault without importing anything into a database. Skip it if you need multi-user sync or a hosted service today, since the README lists hosted deployment only as planned, and if you require a conventional review process, note that the author states the code is written with heavy AI assistance and only partly reviewed before shipping.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem ZenNotes targets: a vault you can drive without a mouse
Most note apps treat the file on disk as an export format. ZenNotes inverts that. The README states that every note is a normal .md file inside a chosen vault and that ZenNotes does not store note content in a hidden database. That single constraint decides who the app is for: people who already have a folder of Markdown, who want to open it in a text editor or grep it from a shell, and who do not want their notes locked behind a proprietary store. The second constraint is input speed. Vim mode is described as first-class, alongside leader-key flows, a command palette, pane and tab motion, local ex commands and built-in help. The third is that the vault should be readable by other tools. A first-party MCP server exposes the same vault to MCP-capable clients, so an assistant works on your files rather than a copy. If none of those three matter to you, the app is probably the wrong shape.
One core, three runtimes: how the desktop and web builds relate
The repository is a monorepo with a shared product core. The README names three modes. desktop is the Electron shell with native menus, an updater, floating windows and desktop packaging. self-hosted is a browser frontend plus a Go server, aimed at home servers and LAN use. hosted is listed as planned, described as the same web and server stack with auth and multi-user storage added later. The README is explicit that the source of truth for user-facing features is the shared UI in packages/app-core, which explains why the web client and the desktop client are expected to behave the same way. The trade-off is visible in the same paragraph: the Go server exists for the web mode, so a self-hosted deployment carries a second runtime and a second language that a desktop-only user never touches. The desktop app is also where the extras live. Detached note windows and the zen CLI install flow are desktop features, and the Raycast extension is macOS-only.
Vault layout, lifecycle folders and the flat-vault option
ZenNotes models note lifecycle with folders rather than a database column. quick, archive and trash are described as built-in lifecycle areas. The main notes area can be either inbox/ or the vault root directly, which the README calls out as the Obsidian-style flat vault arrangement. Folder labels are customizable in the UI without changing the internal ids, so renaming a label does not break the underlying structure. The app watches the vault for external changes and reopens your workspace layout with tabs and panes, which matters if you edit the same files in another editor while ZenNotes is open. Daily and weekly notes are optional and must be enabled from Settings. When enabled, the default daily title is an ISO date such as 2026-04-21 and the default weekly title is an ISO week title such as 2026-W24, living in directories named Daily Notes and Weekly Notes. Both the directory and the title accept date patterns, including tokens like yyyy, MMM, dd, EEEE and ww, plus single-quoted literals such as 'Daily Notes'/yyyy/MM-MMM. Localized month and weekday names follow system, en-US, pt-BR or another BCP 47 locale. Weekly patterns render tokens from the ISO week's Monday and yyyy is the ISO week-year, a detail that trips people up around New Year.
Installing it: brew, AUR, deb, pacman, Nix or AppImage
The README gives one recommended path per platform. On macOS the Homebrew cask is brew install --cask zennotes/tap/zennotes, or you can download the .dmg for your chip; builds are described as signed and notarized. Windows uses ZenNotes-<version>-win-x64.exe. Linux is the most fragmented: the AUR package is yay -S zennotes-bin or paru -S zennotes-bin, and the README notes it installs without libfuse2. Arch also has a native package via sudo pacman -U ZenNotes-<version>-linux-x86_64.pacman. Debian and Ubuntu use sudo apt install ./ZenNotes-<version>-linux-amd64.deb. Nix and NixOS users are pointed at packaging/nix/README.md. The AppImage path needs FUSE 2, and on distros shipping only FUSE 3 the README offers two escapes: install fuse2, or run ./ZenNotes-<version>-linux-x86_64.AppImage --appimage-extract-and-run. The app auto-updates, so the release page is a one-time download. The zen CLI is installed separately from Settings, CLI. It covers list, read, search, capture, edit, archive and trash, plus tasks, folders and MCP, and on macOS it can install the Raycast extension locally.
Where ZenNotes is the wrong tool
The README is candid about one thing that deserves attention: the author states that ZenNotes is built with a lot of help from AI tools like Claude and Codex, that they move much faster this way, and that only some of the code is reviewed before shipping. That is an unusual disclosure and it should shape how you evaluate the project. It does not tell you the code is bad. It does tell you that the usual signal of a maintainer having read every line does not apply, so the burden shifts to you: read the parts of packages/app-core you depend on, and test the upgrade path before pointing the app at a vault you care about. The second limitation is structural. hosted mode is planned, not shipped, so there is no multi-user or account-based deployment described in the material. If your team needs shared editing with permissions, this is not that product. Third, the platform surface is uneven: the Raycast extension is macOS-only, and the Linux install story requires picking among five packaging routes, one of which (AppImage) fails outright on FUSE 3 systems unless you pass an extra flag. Finally, the README does not describe a sync mechanism. Plain files on disk are the model, so moving a vault between machines is your problem to solve.
How it differs from Obsidian and from a plain Vim plus plugins setup
The obvious comparison is Obsidian. Both keep Markdown on disk, both support a flat vault root, and both have a plugin ecosystem. The difference stated in the README is where the logic lives: ZenNotes ships a Go server so the same UI runs in a browser against a self-hosted backend, which Obsidian does not offer in the material here. The other difference is the MCP server being first-party rather than a community plugin, so the vault is exposed to MCP-capable tools through code the project maintains. The comparison in the other direction is a bare Vim or Neovim setup with a Markdown plugin. That gives you the motions and nothing else: no preview panes, no archive and trash lifecycle, no daily note scaffolding with ISO week tokens, and no MCP server. ZenNotes is the bet that you want the Vim editing model wrapped in an application with panes, tabs, diagrams, tasks, tags and CSV-backed table and board views, while the files stay plain. If you only ever edit one file at a time from a terminal, the extra runtime buys you nothing.
Maintenance, releases and what the MIT licence actually covers
The release cadence visible in the material is fast: v2.45.0 on 2026-09-04, v2.46.0 on 2026-09-08, v2.47.0 on 2026-09-09, with the last repository push on the same day as the newest release. Three releases in six days is a signal about how the project is maintained, and it cuts both ways. Fixes arrive quickly. So do changes, and the auto-update path means a desktop install moves forward without you choosing when. If you pin a version for a team, check whether the updater can be held back, because the README does not say. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the extent of what the material supports; it says nothing about trademarks, the zennotes.org domain, or the Raycast extension's own terms, and none of this is legal advice. The self-hosted path adds its own upkeep: a Go server plus a browser frontend that you run and update yourself, which is a different cost profile from an app that auto-updates.
Editorial conclusion
Adopt ZenNotes if you already keep a folder of .md files and want Vim motions, split panes and an MCP server reading that same vault without importing anything into a database. Skip it if you need multi-user sync or a hosted service today, since the README lists hosted deployment only as planned, and if you require a conventional review process, note that the author states the code is written with heavy AI assistance and only partly reviewed before shipping. Before committing a real vault, install via brew install --cask zennotes/tap/zennotes or the AUR package, enable daily notes from Settings, and confirm the date pattern tokens you intend to use, such as yyyy/MM-MMM, produce the directory layout you expect.
Community notes