ZenNotes keeps notes as plain files and ships its server from a separate repository
Keyboard-first local Markdown notes with Vim motions, diagrams, and MCP integration.
At a glance
- What is it?
- ZenNotes is a keyboard-first Markdown notes app with three product modes sharing one core: an Electron desktop build, a browser frontend over a Go server, and a hosted mode still on the plan. The notes stay as .md files you own, but the server binary is not in the repository you clone, and the container defaults to an unpinned tag.
- Who is it for?
- ZenNotes fits people who want their notes to stay as Markdown files and want Vim motions, CSV table and board views, and MCP access without moving the vault into a database, and it delivers that on a desktop build and a browser frontend over the same core.
- 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 last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- ZenNotes/zennotes2,588 ★ · +174
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| ZenNotes/zennotes | 2.4k | 2.6k |
174 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Plain files on disk, three runtimes sharing one core
ZenNotes stores every note as an ordinary `.md` file inside a vault you choose, and says plainly that note content never lands in a hidden database. What is not ordinary is how many places the same app runs. One monorepo produces three product modes: `desktop`, an Electron shell with native menus, an updater, floating windows and desktop packaging; `self-hosted`, a browser frontend over a Go server, meant for home servers and LAN use; and `hosted`, described as planned on that same web and server stack with auth and multi-user storage added later. None of the three is a native mobile app, and the README names no mobile build, so phone use depends on what you have deployed already.
The feature surface comes from one place. User-facing behaviour lives in the shared UI under `packages/app-core`, which is how an Electron shell and a Go-backed server agree on what a note list looks like. The vault model keeps `quick`, `archive` and `trash` as built-in lifecycle areas, while the main notes area is either `inbox/` or the vault root directly, the layout the project calls Obsidian-style flat vaults. Built-in folder labels can be renamed in the interface without changing the internal ids underneath, and the app watches the vault for external changes.
The editor is CodeMirror 6, and the README names it and then stops: the bullet list under the editor and preview heading is empty. That is the thinnest spot in an otherwise specific document. Around the gap sit first-class Vim mode, leader-key flows, a command palette, pane and tab motion, local ex commands, built-in help, and edit, preview and split modes with pinned reference panes and detached windows on desktop.
The container image is built in another repository
The first comment in `docker-compose.yml` settles a question the rest of the tree leaves open. The image is published from ZenNotes/znserver, the Go server's own repository, and nothing here builds it. The top-level entries confirm the absence: no Go source directory appears anywhere, only `apps/`, `packages/`, `src/`, `integrations/`, `packaging/`, `tooling/` and a `vault/`, with the root package.json naming the package `zennotes-monorepo` and describing it as the home of desktop, web and self-hosted server builds.
The practical consequence is version pinning. Both the compose file and the Makefile default to `adibhanna/zennotes:latest`, and the compose comment says to pin a version with `ZENNOTES_IMAGE` or `make up IMAGE=...`. Because the default tag is `latest`, `make rebuild`, which pulls the newest image and restarts, can replace the server underneath a running install without anything in your vault recording that it happened. `make server-dev` has the same shape: the Makefile's own help says it runs the pinned ZenNotes/znserver release, or a checkout supplied through `ZENNOTES_SERVER_DIR`.
So treat the image tag as the version you actually control. Contributors get the same split: `make clean` removes downloaded server binaries, and `make nuke` tears down the container together with its image, data and build output, which is a heavier operation than an upgrade needs to be.
A loopback port, an empty token, and ZENNOTES_ALLOW_INSECURE_NOAUTH
The self-hosted compose file is more careful than most, and the hardening is worth reading before you change anything. The published port binds loopback only. The root filesystem is read only, `/tmp` is a tmpfs, `no-new-privileges:true` is set, every capability is dropped through `cap_drop: ALL`, and the process runs as uid and gid 1000 by default. None of that covers your notes. Two bind mounts stay writable: the content root at `/workspace` and `./data` at `/data`, with `ZENNOTES_CONFIG_PATH` pointing at `/data/server.json`. A read-only root filesystem does nothing for the directory where the Markdown files actually live, and that is also the directory an MCP-capable client writes to.
Authentication is where the gap sits:
environment:
ZENNOTES_AUTH_TOKEN: "${ZENNOTES_AUTH_TOKEN:-}"
ZENNOTES_ALLOW_INSECURE_NOAUTH: "${ZENNOTES_ALLOW_INSECURE_NOAUTH:-0}"The token defaults to an empty string, the flag that permits running without one defaults to `0`, and the Makefile repeats that default as `ALLOW_INSECURE_NOAUTH ?= 0`. The two files agree on the safe posture, and neither explains in prose what the server does when the token is empty.
For a home server this is the part that matters, because the project calls the self-hosted mode suitable for home servers and LAN use while the published port accepts loopback connections only. Reaching it from a LAN address means editing that binding, and at that moment the empty token is the only thing between your vault and the network. Set a token before you do it. One more default to know: `ZENNOTES_ALLOWED_ORIGINS` lists `http://localhost:7878,http://127.0.0.1:7878`, so a browser arriving by hostname or LAN IP sits outside the default allow list.
make up serves the vault directory that sits in the repository
`make up` mounts a directory from your own checkout. The Makefile sets `CONTENT_ROOT ?= ./vault`, and the compose file repeats that value as the default host content root, so a fresh clone serves whatever lives in the repository's own `vault/` entry as the note content root unless you override `ZENNOTES_HOST_CONTENT_ROOT`. The same default flows into `ZENNOTES_DEFAULT_VAULT_PATH`, which is what the server treats as the vault to open, and into `ZENNOTES_BROWSE_ROOTS`, which bounds what the interface can browse. The repository gives no description of what that folder contains, so anyone evaluating the app on their own notes should point the variable at a copy of those notes before the first start rather than after.
Two smaller defaults sit beside it. `DATA ?= ./data` is the other mount, the one holding the server config at `/data/server.json`, and neither the Makefile nor the compose file creates that directory for you. And the container runs as `${ZENNOTES_CONTAINER_UID:-1000}:${ZENNOTES_CONTAINER_GID:-1000}`, so whatever you bind has to be readable by that uid, and the data directory has to be writable by it. Both variables accept overrides, which is the difference between a clean first run and a container that cannot see your files.
The rest of the Makefile follows the same pattern of declared defaults: `PORT ?= 7878`, `APP_URL ?= http://localhost:$(PORT)`, and a compose binary chosen at parse time by probing for `docker compose` and falling back to `docker-compose`.
AppImage on Arch, CachyOS or Fedora needs FUSE 2
Every desktop installer is attached to a GitHub release, and the app auto-updates, so the download happens once. macOS gets a cask the README marks recommended:
brew install --cask zennotes/tap/zennotesOr the disk image for your chip, `ZenNotes-<version>-mac-arm64.dmg` or `ZenNotes-<version>-mac-x64.dmg`, and those builds are signed and notarized. Windows gets a single `ZenNotes-<version>-win-x64.exe`. Linux has five routes, and one of them has a real snag: the AppImage needs FUSE 2, while Arch, CachyOS and Fedora ship only FUSE 3.
chmod +x ZenNotes-<version>-linux-x86_64.AppImage
./ZenNotes-<version>-linux-x86_64.AppImageThe documented answers are to install `fuse2`, to run the image without FUSE, or to sidestep the whole question with a native package:
./ZenNotes-<version>-linux-x86_64.AppImage --appimage-extract-and-runThe AUR package is singled out as installing cleanly without `libfuse2`:
yay -S zennotes-bin # or: paru -S zennotes-binArchitecture coverage is narrower than the install list implies. Every Linux artifact named is x86_64 or amd64, and the only arm64 build is the macOS disk image, so no Linux arm64 package is offered. The Nix route sends you to `packaging/nix/README.md` for instructions, even though the repository root carries `flake.nix` and `flake.lock`. The `zen` command line companion arrives by a different route again: the desktop app installs it from its settings panel, covering list, read, search, capture, edit, archive and trash operations plus tasks, folders and MCP, and on macOS it can also install the Raycast extension locally.
Weekly notes read yyyy as the ISO week-year
Daily and weekly notes are off until you enable them in Settings, and their naming is where the configuration gets interesting. The default daily title is a plain ISO date such as `2026-04-21`, while the default weekly title is an ISO week title such as `2026-W24`. Both live in dedicated directories under the primary notes area, `Daily Notes` and `Weekly Notes` by default, and both the title and the directory accept date patterns such as `yyyy/MM-MMM` or `yyyy-MM-dd-EEE`. Single-quoted text passes through literally, which is how a pattern like `'Daily Notes'/yyyy/MM-MMM` embeds a folder name. Localized month and weekday names can follow `system`, `en-US`, `pt-BR` or another BCP 47 locale.
The token list is fixed and short: `yyyy` and `yy` for the year, `M`, `MM`, `MMM` and `MMMM` for month, `d` and `dd` for day, `EEE` and `EEEE` for weekday, `w` and `ww` for ISO week numbers, plus quoted literals. Weekly titles can use `yyyy-'W'ww` to build the default style.
Then the rule that will bite. Weekly notes render their date tokens from the Monday of the ISO week, and `yyyy` is the ISO week-year for weekly patterns rather than the calendar year of any day inside that week. A weekly note whose Monday falls in late December therefore gets a title in the following year, and the same pattern drives its folder path. Anyone filing by week has to read those two rules together before choosing a layout, because the year in the filename is a property of the week number, not of the date you are looking at.
Three tag formats inside one release window
The release feed is where this repository stops looking like a single versioned product. Three tags were published on 2026-10-02: `v2.61.0`, `web-2.60.4-web.ha0258ecc7b3c0133` and `core-2.60.4-core.hae0e49f9e5397fc2`. One is a plain application version. The other two name a component, carry their own semantic version, and append a hash suffix, and their base versions trail the newest tag. Pinning is therefore not a single decision: you pick an app tag or you pick per-component tags, and the two schemes do not share a number to compare.
Inside the tree the numbers do line up. The root package.json declares `zennotes-monorepo`, marked private, at version 2.61.0, so the monorepo root matches the newest release tag rather than trailing it. What lags is the install documentation, which tells you to replace `<version>` and offers `2.2.0` as the example, well behind the shipped tag. Anyone scripting artifact names should read the current tag instead of copying that example.
Neither fact touches a self-hosted install. Because the compose file defaults to the `latest` tag, release naming has no effect on what a container pulls unless you set `ZENNOTES_IMAGE` yourself. The last push to the default branch landed on 2026-10-03, the repository is not archived, and the root carries an MIT license alongside `CONTRIBUTING.md` and `SECURITY.md`.
postinstall runs patch-package and can fail the install
Contributing is where the monorepo shows its weight. The root package.json pins `[email protected]` as its package manager, requires Node 22 or newer, declares workspaces for `apps/*` and `packages/*`, and runs this on every install:
"engines": {
"node": ">=22"
},
"postinstall": "cd apps/desktop && patch-package --error-on-fail",That last line is the one to know about. Every dependency install applies patches to the Electron app's packages and fails outright when a patch no longer applies, so an install can break on dependency drift rather than on anything you typed. The `overrides` block does the same job by hand, holding `nanoid` at 3.3.18 for `@excalidraw/excalidraw` and `nanoid` 5.1.16 alongside `@mermaid-js/parser` 1.2.1 for `@excalidraw/mermaid-to-excalidraw`, which is why two major versions of one package are pinned side by side.
The remaining scripts show the project's own priorities. `turbo` drives typecheck, test and build, and `build:prod` chains all three in that order. Server and web development run through `tooling/scripts/run-server-dev.mjs` and `tooling/scripts/dev-web-stack.mjs`. The web artifact is packed by `pack-web-artifact.mjs` with a matching test, contract fixtures are checked against `sync-contract-fixtures.mjs`, and two performance scripts exist for a large vault and for desktop runtime. The README's opening note says the author builds with AI tooling and still goes through code before shipping, which is worth weighing against a postinstall that hard fails.
Editorial conclusion
ZenNotes fits people who want their notes to stay as Markdown files and want Vim motions, CSV table and board views, and MCP access without moving the vault into a database, and it delivers that on a desktop build and a browser frontend over the same core. It does not fit someone looking for a hosted service today, a native mobile app, or a server whose source sits in the repository they clone, because the hosted mode is still planned and the container image is built in ZenNotes/znserver. Before the first make up, set ZENNOTES_AUTH_TOKEN, point ZENNOTES_HOST_CONTENT_ROOT at a copy of your notes rather than at the vault directory inside the checkout, and pin ZENNOTES_IMAGE to a tag instead of latest. For contributors, expect npm install to run patch-package with --error-on-fail on Node 22 or newer.
Frequently asked questions
Does ZenNotes store my notes in a database?
No. Every note is a normal .md file inside a chosen vault, and the project states it does not store note content in a hidden database. The app can also watch the vault for external changes made outside it.
Is there a hosted version of ZenNotes yet?
Not yet. The project ships a desktop app and a self-hosted web app, and describes a hosted deployment mode as planned on the same web and server stack, with auth and multi-user storage to be added later.
How do I secure the self-hosted ZenNotes server before putting it on my LAN?
Set ZENNOTES_AUTH_TOKEN before you widen the port binding. It defaults to an empty string, while ZENNOTES_ALLOW_INSECURE_NOAUTH defaults to 0, the container publishes port 7878 to 127.0.0.1 only, and ZENNOTES_ALLOWED_ORIGINS lists just the loopback names, so a LAN address changes both the origin and the exposure.
Which ZenNotes Linux install avoids the FUSE 2 requirement?
The AUR package, installed with yay or paru, is documented as installing cleanly without libfuse2. Native packages sidestep FUSE entirely, and the AppImage can be run with --appimage-extract-and-run on distros that ship only FUSE 3.
Where does the zen command line tool come from in ZenNotes?
The desktop app installs it from its CLI panel in settings rather than from a package manager. It covers listing, reading, searching, capturing, editing and archiving notes, plus tasks, folders and MCP, and on macOS it can also install the Raycast extension locally.
Does ZenNotes have a mobile app?
The three product modes named are an Electron desktop app, a self-hosted browser frontend over a Go server, and a hosted mode still planned, and no mobile build is listed among the installers. Phone access depends on reaching the self-hosted web app over your own network.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/zennotes-zennotes)Star history chart for your README
[](https://hysenlabs.com/projects/zennotes-zennotes)Was this useful?