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](https://github.com/ZenNotes/zennotes/releases/latest) — see [Install](#install) below. Website: [zennotes.org](https://zennotes.org) Support development: [GitHub Sponsors](https://github.com/sponsors/adibhanna) Detailed in-repo documentation lives under [docs/README.md](docs/README.md). ## Install All desktop installers are attached to each [GitHub Release](https://github.com/ZenNotes/zennotes/releases/latest). The app auto-updates, so you only download once. (Replace `` with the current release, e.g. `2.2.0`.) ### macOS **Homebrew (recommended):** ```sh 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--mac-arm64.dmg` - Intel: `ZenNotes--mac-x64.dmg` ### Windows Download and run `ZenNotes--win-x64.exe`. ### Linux Pick whatever suits your distro: - **Arch / CachyOS / Manjaro — AUR (recommended):** ```sh yay -S zennotes-bin # or: paru -S zennotes-bin ``` Installs cleanly without `libfuse2`. - **Arch — native package:** ```sh sudo pacman -U ZenNotes--linux-x86_64.pacman ``` - **Debian / Ubuntu:** ```sh sudo apt install ./ZenNotes--linux-amd64.deb ``` - **Nix / NixOS:** Read [packaging/nix/README.md](packaging/nix/README.md) for installation instructions - **Any distro — AppImage:** ```sh chmod +x ZenNotes--linux-x86_64.AppImage ./ZenNotes--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: ```sh ./ZenNotes--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](#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. ```text 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](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 ```bash npm ci ``` ## Local development ### Desktop app ```bash npm run dev:desktop ``` or: ```bash make desktop ``` ### Web client ```bash npm run dev:web ``` or: ```bash make web-dev ``` ### Go server The server lives in its own repository, [ZenNotes/znserver](https://github.com/ZenNot