zennotes

ZenNotes

[!NOTE] I build ZenNotes with a lot of help from AI tools like Claude and Codex. They let me move much faster, but I still go through some of the code before I ship it. The architecture, the technical decisions, and the trade-offs are things I still spend a lot of time thinking about. AI helps me write code faster, but it doesn't replace understanding how the system works.

ZenNotes is a keyboard-first Markdown notes app with a shared product core and multiple runtimes:

• a desktop app built with Electron
• a self-hosted web app backed by a Go server
• a future hosted deployment mode built on the same web/server stack

ZenNotes keeps your notes as ordinary Markdown files on disk. It adds Vim-friendly editing, split and preview workflows, tasks, tags, archive/trash, diagrams, search, daily notes, CSV databases (Notion-style Table + Board views over plain .csv files), and MCP integration on top of the files you already own. On macOS, the first-party zen CLI also powers launcher workflows such as the Raycast extension.

Grab the latest build from GitHub Releases — see Install below.
Website: zennotes.org Support development: GitHub Sponsors

Detailed in-repo documentation lives under docs/README.md.

Install

All desktop installers are attached to each GitHub Release. The app auto-updates, so you only download once. (Replace <version> with the current release, e.g. 2.2.0.)

macOS

Homebrew (recommended):

brew install --cask zennotes/tap/zennotes

Or download the .dmg for your chip, open it, and drag ZenNotes to Applications. Builds are signed and notarized.

• Apple Silicon: ZenNotes-<version>-mac-arm64.dmg
• Intel: ZenNotes-<version>-mac-x64.dmg

Windows

Download and run ZenNotes-<version>-win-x64.exe.

Linux

Pick whatever suits your distro:

• Arch / CachyOS / Manjaro — AUR (recommended):
  bash复制

  yay -S zennotes-bin     # or: paru -S zennotes-bin

  Installs cleanly without libfuse2.
• Arch — native package:
  bash复制

  sudo pacman -U ZenNotes-<version>-linux-x86_64.pacman

• Debian / Ubuntu:
  bash复制

  sudo apt install ./ZenNotes-<version>-linux-amd64.deb

• Nix / NixOS: Read packaging/nix/README.md for installation instructions
• Any distro — AppImage:
  bash复制

  chmod +x ZenNotes-<version>-linux-x86_64.AppImage
  ./ZenNotes-<version>-linux-x86_64.AppImage

  AppImages need FUSE 2. On distros that ship only FUSE 3 (Arch, CachyOS, Fedora), either install it (sudo pacman -S fuse2, sudo dnf install fuse) or run without FUSE:
  bash复制

  ./ZenNotes-<version>-linux-x86_64.AppImage --appimage-extract-and-run

  (Or just use the AUR / .pacman / .deb package, which sidestep this entirely.)

zen CLI

The desktop app installs a zen command-line companion from Settings → CLI — list, read, search, capture, edit, archive/trash notes, plus tasks, folders, and MCP. On macOS it can also install the Raycast extension locally.

Self-hosted web app

ZenNotes also runs as a self-hosted web app backed by a Go server. See Local development to run the web client and server.

What ZenNotes is for

• writing and organizing plain-file Markdown notes without a database
• moving quickly with keyboard-first navigation and Vim motions
• working across edit, split, and preview modes without losing context
• keeping tasks, tags, search, archive, trash, and quick capture inside the same vault
• rendering math and diagrams directly from Markdown
• exposing the vault to MCP-capable tools through a first-party server
• searching and opening notes from terminal scripts or Raycast on macOS
• self-hosting the app on your own machine or home server

Product modes

ZenNotes now ships from one monorepo with one shared app core.

• desktop: Electron shell, native menus, updater, floating windows, desktop packaging
• self-hosted: browser frontend plus Go server, suitable for home servers and LAN use
• hosted: planned as the same web/server stack with auth and multi-user storage added later

The source of truth for user-facing features is the shared UI in packages/app-core.

Core ideas

Plain files first

Every note is a normal .md file inside a chosen vault. ZenNotes does not store note content in a hidden database.

Keyboard-first by default

ZenNotes assumes you want to move fast:

• first-class Vim mode
• leader-key flows
• command palette
• pane and tab motion
• local ex commands
• built-in help

Preview is part of the workflow

ZenNotes supports:

• edit mode
• preview mode
• split mode
• pinned reference panes
• detached note windows on desktop

Shared vault, shared tooling

ZenNotes includes a first-party MCP server and desktop install flows for compatible clients, so tools can work on the same vault you do instead of a copy.

Feature overview

Notes, folders, and lifecycle

ZenNotes can:

• create, rename, duplicate, move, archive, unarchive, trash, restore, and reveal notes and folders
• watch the vault for external changes
• reopen your workspace layout with tabs and panes

System folders still exist, but the vault model is more flexible now:

• quick, archive, and trash remain built-in lifecycle areas
• the main notes area can be either:
  • inbox/
  • the vault root directly, for Obsidian-style flat vaults

The built-in folder labels are also customizable in the UI without changing the underlying internal ids.

Daily and weekly notes

Daily and weekly notes are optional and can be enabled from Settings.

• when enabled, ZenNotes can open or create today's daily note and this week's weekly note automatically
• the default daily title is a simple ISO date like 2026-04-21
• the default weekly title is an ISO week title like 2026-W24
• date notes live in dedicated directories under your primary notes area
• the default directories are Daily Notes and Weekly Notes
• the directory and title can use date patterns such as yyyy/MM-MMM and yyyy-MM-dd-EEE
• weekly title patterns can use ISO week tokens such as yyyy-'W'ww
• localized month and weekday names can follow system, en-US, pt-BR, or another BCP 47 locale

Supported date note pattern tokens:

• yyyy / yy for 2026 / 26
• M / MM / MMM / MMMM for 6 / 06 / Jun / June
• d / dd for 9 / 09
• EEE / EEEE for Tue / Tuesday
• w / ww for ISO week numbers like 24
• single-quoted literals, such as 'Daily Notes'/yyyy/MM-MMM

Weekly notes render date tokens from the ISO week's Monday, and yyyy is the ISO week-year for weekly patterns.

Editor and preview

The editor stack is CodeMirror 6 with a Markdown-oriented workflow:

• live preview behavior in the editor
• heading folding
• outline extraction and jumps
• configurable line numbers
• configurable line-height and typography controls
• syntax highlighting for fenced code blocks
• desktop-installed TextMate grammars for custom fenced-code languages
• wiki links, callouts, tables, footnotes, and local embeds
• Vim block cursor and keyboard navigation

Preview and split mode support:

• GitHub-flavored Markdown
• KaTeX math
• Mermaid
• TikZ
• JSXGraph
• function-plot
• callouts
• footnotes
• wiki links and backlinks

Search, tasks, tags, and built-in views

ZenNotes includes:

• note search by title and path
• vault-wide text search
• tags view
• tasks view
• archive view
• trash view
• quick notes view
• built-in help/manual

Vault text search can use the built-in engine, ripgrep, or fzf, with auto-detection and optional custom binary paths.

The desktop app also ships a zen command-line companion for list, read, search, capture, edit, archive/trash, task, folder, and MCP workflows. On macOS, ZenNotes can install its Raycast extension locally from Settings -> CLI, avoiding the Raycast Store review path. The integration uses the CLI plus zennotes:// deep links to search notes, open them in the main app, open them in floating windows, archive/unarchive, move notes to Trash, reveal files in Finder, and copy note paths or wikilinks.

Obsidian-friendly vault support

ZenNotes now works better with existing Obsidian-style vaults.

• primary notes can live at the vault root instead of requiring inbox/
• loose files anywhere in the vault are surfaced as files/assets
• embedded files like ![[image.png]] resolve more like Obsidian
• new referenced files default to the vault root instead of a required attachments folder
• legacy attachements/ and _assets/ folders are still recognized

This means imported vaults with top-level notes, folders, and loose images/files behave much more naturally.

Files and local assets

ZenNotes supports local files in notes and in the sidebar/list views.

• local images and files can appear directly in the vault tree
• images, SVGs, videos, audio, PDFs, and other media open inside ZenNotes tabs or reference panes instead of being handed off to the OS by default
• desktop context menus include reveal-in-file-manager actions
• desktop uses Finder on macOS and the platform file manager on Windows/Linux
• watcher updates now include non-Markdown file changes, so deleting files externally updates the UI without a manual refresh

Sidebar multi-select supports platform modifiers: use Cmd/Ctrl-click to toggle individual notes or folders, Shift-click to select a visible range, then use the context menu to apply actions such as open in tabs, move, archive, trash, restore, delete folders, copy paths, or drag the selected group to a folder.

Themes, fonts, and customization

The settings surface includes:

• theme families and light/dark/auto modes
• interface, text, and monospace font selection
• editor font size and line-height controls
• preview and editor width controls
• content alignment
• keymap overrides
• Vim toggles and leader hint behavior
• search backend selection
• vault layout settings
• daily notes settings
• system-folder display labels

Desktop vs web

Both runtimes share the same core app, but they do not expose identical platform features.

Desktop-only features include:

• native menus
• app updater
• floating note windows
• zen CLI install/uninstall flow
• local Raycast extension installation on macOS
• MCP install/uninstall flows for supported clients
• reveal in Finder / platform file manager
• packaging and signed releases

Web/self-hosted mode includes:

• the same shared note UI and workflows
• a Go backend for vault access and file watching
• a server-side vault picker/browser
• browser access on a LAN or home server

Monorepo layout

ZenNotes now uses a single monorepo.

apps/
  desktop/   Electron shell, preload, updater, packaging
  web/       Vite/PWA shell and HTTP bridge
packages/
  app-core/        Shared React application and renderer logic
  bridge-contract/ Typed runtime contract between UI and host
  shared-domain/   Shared types and note/task/view models
  shared-ui/       Reusable UI primitives
tooling/
  scripts/         Shared tooling hooks and migration scripts
docs/

Read docs/monorepo-architecture.md for the architectural boundary between the shared app core and the platform-specific shells.

Quick start

Requirements

• Node.js 22+
• npm
• Go 1.22+ for the server build path
• Docker optional, for self-hosting

Install dependencies

npm ci

Local development

Desktop app

npm run dev:desktop

or:

make desktop

Web client

npm run dev:web

or:

make web-dev

Go server

The server lives in its own repository, [ZenNotes/znserver](https://github.com/ZenNot