Docs

Run the desktop app

Best if you want ZenNotes as a native desktop app on your own machine, with either a local vault or a remote ZenNotes server.

• Requires Node.js 22+ and npm.
• Open a local vault from Settings -> Vault, or use Quick Connect… / Connect to Remote Vault… to point the desktop app at a self-hosted ZenNotes server.
• Desktop can save multiple remote workspaces, repoint the active remote with Change Remote Vault…, and return to local mode later.
• Export Note as PDF… is available from the command palette and the Shift+Mod+E shortcut.
• For packaged desktop builds, use npm run build:prod and then npm run pack.

Run the published Docker image

The fastest way to self-host in the browser. Pull the prebuilt multi-arch image from Docker Hub — no git checkout or local build required.

• Permissions: the container runs as a non-root user (UID 65532), and Docker bind mounts keep the host owner — so the mounted vault and data folders must be writable by the user the container runs as. The --user "$(id -u):$(id -g)" flag above runs it as you; without it you may see "vault init: mkdir /workspace/inbox: permission denied". As an alternative to --user, chown the folders to 65532.
• The image is multi-arch (linux/amd64 and linux/arm64); docker pull adibhanna/zennotes selects the right build automatically.
• Pin a release with a version tag, e.g. adibhanna/zennotes:2.0.1, instead of :latest.
• Your vault stays on the host as ordinary .md files; the /data volume holds the server config.
• This runs the same server as the make up flow below, so every ZENNOTES_* environment variable there applies here too.
• Prefer ZENNOTES_AUTH_TOKEN_FILE over ZENNOTES_AUTH_TOKEN for Docker or Kubernetes secrets so the token never lives in shell history or .env.
• Drop the 127.0.0.1 prefix on -p to reach it from your LAN, but put a TLS reverse proxy in front and set ZENNOTES_BEHIND_TLS=1 first.

Build and run with Docker from source

Build the image yourself from a local checkout with make up — use this when you want to modify the source or have the auth token generated for you. To just run it, use the published image above.

• The vault stays on the host. Docker is only serving it; your notes are not stored inside the container.
• On first load, ZenNotes asks for the token stored in ./data/auth-token, then asks you to choose the vault folder from the mounted content root.
• After the first browser login, ZenNotes uses a session cookie, so reloads should not keep asking for the token.
• The desktop app can connect to the same Docker-backed server, so browser and desktop can point at one host-mounted vault.
• Docker can only browse folders you mounted. If you want to browse an Obsidian or iCloud folder from the web picker, mount that folder as CONTENT_ROOT or mount a parent directory that contains it.
• The default Docker setup binds to localhost and is meant to sit behind a reverse proxy or private network gate if you expose it remotely.
• For public exposure, set ZENNOTES_BEHIND_TLS=1 once a TLS proxy is in front; that flips on Secure cookies and HSTS.
• Set ZENNOTES_TRUSTED_PROXIES to the proxy CIDR (e.g. 127.0.0.1/32 or your bridge network) so X-Forwarded-Proto and X-Forwarded-For are only honoured from the proxy, not arbitrary clients.
• Prefer ZENNOTES_AUTH_TOKEN_FILE over ZENNOTES_AUTH_TOKEN for Docker / Kubernetes secrets so the token never lives in .env.
• Restarting the container logs everyone out — sessions are held in memory. Set ZENNOTES_PERSIST_SESSIONS=1 to persist browser logins to sessions.json on the /data volume (mode 0600, opt-in) so you stay logged in across restarts instead of re-entering the token.
• Notes default to 0600 and dirs to 0700; tune with ZENNOTES_VAULT_FILE_MODE and ZENNOTES_VAULT_DIR_MODE if you intentionally share the vault with another local user.
• Body size caps are enforced server-side: ZENNOTES_MAX_NOTE_BYTES (default 10 MiB) and ZENNOTES_MAX_ASSET_BYTES (default 50 MiB).

Run the web app from source

Best for development. For normal self-hosted use, prefer the Docker flow above.

• The web client and Go server are separate processes in dev mode.
• If auth is enabled, the browser will prompt for the server token before protected routes work.
• Browser auth now uses the bootstrap token once and then an HttpOnly session cookie instead of keeping the token in the URL.
• If backend routes change, restart the Go server and reload the page.
• If Connect to server vault appears dead in dev mode, the Go server is usually missing or stale. Restart npm run dev:server and reload.

Use desktop with a remote ZenNotes server

Best if you want the native desktop app, but the vault itself lives on another machine running the ZenNotes server.

• Remote connections can be saved and reused later from Settings and the command palette as Saved Remote Workspaces.
• Settings -> Vault also exposes Change Remote Vault…, Return to Local Vault, and Open Local Vault….
• When connected remotely, ZenNotes shows a Remote indicator in the sidebar and title bar.

How to use this index

Press Cmd+F (macOS) or Ctrl+F (Windows/Linux) to search this page for a feature name, a shortcut, or an ex command. Each group below covers one domain; jump to the matching group, then scan its table.

Mod means Cmd on macOS and Ctrl on Windows/Linux. Bindings shown are defaults — every shortcut, Vim binding, and sequence is remappable in Settings → Keymap. Leader bindings (Space prefix) and ex commands (typed after :) require Vim mode; the equivalent command-palette entry works in any mode.

Many features have more than one access path. Where that is true, the row lists all of them: shortcut and ex command and palette entry. Use whichever fits your current context.

Feature groups at a glance

Six domains. Jump to the one that matches what you are looking for.

Editing — view modes

Switch how the active note is shown. Each mode has a shortcut, an ex command, and a palette entry.

Editing — inline authoring aids

Insert structure and resolve links without leaving the keyboard.

Editing — formatting, folding & cleanup

Editing — rendering, math & diagrams

Markdown rendering features. All are GFM-based and theme-aware; diagrams expand to a pan/zoom modal.

Editing — search, comments & PDF

Workspace — panels & layout toggles

Show, hide, and arrange the chrome around the editor.

Workspace — panes, tabs & splits

Multi-pane editing. Split and pane commands work via Vim Ctrl+W, ex commands, and the palette.

Workspace — reference pane & floating windows

Workspace — palettes & search

Fast finders. Each has a shortcut and a Vim leader binding.

Workspace — appearance & navigation extras

Notes — built-in views

Special views that gather notes and tasks across the vault.

Notes — create, template & journal

Notes — manage, move & organize

Notes — folders, tags & assets

Notes — task metadata & sorting

Annotate inline task lines, or make a whole note a task; tasks are parsed across all notes.

Notes — databases (CSV)

Any .csv in the vault is a full database, with zero new dependencies. Create one with 'New Database' in the command palette or by right-clicking a folder → New database.

Keyboard — global shortcuts

Mode-independent shortcuts. All remappable in Settings → Keymap.

Keyboard — Vim leader (Space)

Vim mode only. Press Space, then the next key; enable which-key hints in Settings → Editor to see options.

Keyboard — Vim motions & panes

Keyboard — list & view navigation

Active when a list or panel (not the editor) has focus.

Keyboard — ex commands & the keymap editor

Type : in Vim normal mode, then a command. Tab cycles completions in a wildmenu. Every palette command is also reachable as an ex command (kebab-case to underscores).

Settings — appearance & typography

Open with Mod+, then choose a tab.

Settings — editor behavior & vault

Integrations — zn CLI

Install from Settings → CLI, then run zn in any terminal. Override the target vault with ZENNOTES_VAULT; most commands accept --json.

Integrations — MCP, Raycast & server

Connect AI agents, Raycast, and remote servers. MCP and Raycast are set up in Settings → MCP and Settings → CLI.

This is the reference for moving around ZenNotes and arranging its windows: which panels to toggle, how to split the editor, how tabs and history work, and how the layout persists.

ZenNotes is built around a single editing surface that you can frame with panels, divide into panes, and strip down to nothing. Most navigation is available three ways: a default shortcut, the command palette (Shift+Mod+P), and — if you use Vim mode — a leader key (Space) or ex command (the colon prompt). Throughout this section, Mod means Cmd on macOS and Ctrl on Windows/Linux.

Bindings marked Vim-only require Vim mode (Settings, Editor, Vim mode). Quick capture, floating windows, the external file app, and a few asset actions (duplicating, deleting, and pasting an image from the clipboard) are desktop-only. Everything else — including recoloring folders and moving or renaming attachments — works on both desktop and the self-hosted web app.

The workspace at a glance

ZenNotes has four framing surfaces around the editor, plus the editor's own pane tree. You toggle each one independently.

Toggle panels

Each panel has its own binding and works from anywhere in the app.

Multi-pane layout

The editor is a tree of panes. You can split it vertically or horizontally, navigate between panes with the keyboard, resize the dividers, and close panes you no longer need. Each pane keeps its own tab list, active tab, and undo history.

Pane and split shortcuts

Tabs

With tabs enabled (Settings, Editor, Note tabs), each pane shows a tab strip you can click, scroll, pin, and prune. Disabling tabs reverts to single-note mode, where the buffer palette (Space o) becomes the main way to switch notes.

Switching tabs from the keyboard

When you focus the tab strip (Ctrl+W k from the editor), the tab row becomes keyboard-navigable:

• h or arrow-left moves to the previous tab; l or arrow-right moves to the next tab.
• j, arrow-down, or Enter drops focus back into the editor.
• Cycle tabs without focusing the strip using ]b (next) and [b (previous), or the ex commands :bn / :bnext and :bp / :bprev. When only one tab is open, these jump to the most recent note instead.

Finding and cycling open buffers

Every open tab is a buffer. Two tools span all of them.

Tab history

Each pane keeps its own back/forward history of the notes you have viewed, so you can retrace a chain of links the way a browser does.

Tab and history shortcuts

Pinned reference pane

The reference pane is a companion view docked to the right of the active pane, outside the normal pane tree. Pin a note (or a PDF) there to keep it visible while you draft against it. Only one reference can be pinned at a time.

Floating and quick-capture windows

Desktop only. Detach a note into its own OS window, or open a small capture window to jot something without leaving what you are doing.

Focus modes and zoom

Strip the interface down for writing, or scale the whole UI up and down.

Jumping with the keyboard

Two Vim-mode aids let you move without reaching for the mouse or memorizing positions.

Sidebar and list navigation

The sidebar and note list share a Vim-style navigation model and render large vaults smoothly.

Sidebar / list navigation keys

Active when the sidebar or note list has focus.

Session and window persistence

You should never have to rebuild your layout. ZenNotes saves it for you.

ZenNotes organizes your vault into a handful of system areas you move notes through over their lifetime, plus folders you create freely. This section covers every view in the sidebar, how to sort, filter, and group what you see, and every operation you can perform on a note or folder.

Your vault is a normal directory of Markdown files on disk. On top of it, ZenNotes defines four built-in lifecycle areas: Inbox, Quick Notes, Archive, and Trash. These areas exist conceptually even if you rename their sidebar labels. Tags and Files give you two more ways to slice the same notes and assets without moving anything.

Most actions described here are reachable several ways: a default shortcut, a command-palette title (open it with Shift+Mod+P), an ex command (type ':' in Vim normal mode), a right-click or 'm'-key context menu, and the zn CLI. Pick whichever fits your flow.

The system views

Six destinations in the sidebar. The first four are lifecycle stages a note passes through; the last two are lenses over your whole vault.

Inbox and your primary notes location

Where your main notes live is governed by Settings → Vault → Primary notes location. In Inbox mode (the default), regular notes live in an inbox/ folder and other folders sit under archive/. In Vault root mode (Obsidian-style), notes live at the vault root with no dedicated inbox/ folder. This choice changes how the sidebar is laid out, where new notes are created, and which 'New Note' commands appear (for example, 'New Note in Inbox' versus 'New Note in Vault Root'). The setting persists across sessions.

Inside the Inbox view you can multi-select notes and folders for bulk operations, drag notes into folders or onto other panes, and assign emoji icons to folders. The note list updates automatically as you change the sidebar selection, showing notes and assets for the current folder.

Quick Notes and quick capture

Quick Notes are ordinary Markdown files that live in the quick area, listed in reverse-chronological order so the newest capture is always on top. Create one with Shift+Mod+N, Space q in Vim mode, the '+' button or 'n' key inside the Quick Notes view, or command palette 'New Quick Note'. ZenNotes focuses the title field immediately so you can start typing.

On desktop you can also pop a small floating capture window with Shift+Mod+Space (a system-wide hotkey that works even when ZenNotes is hidden), Space q via the leader, or command palette 'Quick capture'. It remembers its position and size, and notes you jot land in the Quick Notes folder.

Titling is configurable in Settings → Editor. Toggle 'Date-titled Quick Notes' to name notes by ISO date (for example 2026-05-29) instead of a timestamp, and set a 'Quick Note prefix' (default 'Quick Note') that is prepended to the title. Leave the prefix blank for a bare date or timestamp.

Archive and Trash workflows

Tags view

The Tags view shows every hashtag in the vault as a chip strip with per-tag counts. Click chips to select or deselect them; notes matching any selected tag appear below (union logic). A search box filters within the results. Tags can be hierarchical with slashes (for example #project/active), and they work in any script — non-Latin tags like #тест (Cyrillic) or #标签 (CJK) are recognized, render as clickable pills in the editor and preview, and appear here. Headings (# x) and hex colors (#1971c2) are still not treated as tags.

Open the view with command palette 'Open Tags', Space # in Vim mode, or the sidebar Tags section. The :tag ex command opens it, and :tag foo bar replaces the current selection with those tags in one step. Inside the view, j/k navigate notes, Enter or o opens, '/' focuses the filter, and ':' opens a view-local ex prompt. The view live-extracts tags from the active editor buffer as you type.

Tag operations across the vault

Files and assets

ZenNotes treats your vault as a file-based, Obsidian-compatible store: loose files anywhere in the vault count as assets. Images, SVGs, PDFs, audio, video, and generic files can open in tabs or the reference pane. New referenced files default to the vault root rather than a forced attachments folder, though legacy locations such as attachements/ and _assets/ are still recognized.

Embed an asset with  or the Obsidian-style ![[image.png]], or paste/drop an image into the editor to auto-insert it. Wikilink autocomplete ([[) also completes asset paths. Reach the asset views from the Files link in the sidebar footer (command palette 'Go to Files') or the Assets tab that appears when a folder or asset is selected.

Assets render in two layouts you switch from the note-list header: a grid of thumbnail cards (grid icon) and a compact list with names, paths, and sizes (list icon). Your layout choice persists for the session. From the asset views you can sort, filter, search, drag assets into notes, delete unused assets, and on desktop right-click to reveal an asset in the file manager.

Creating notes

Several entry points depending on where you want the note to land.

Note operations

Every operation works from the command palette and most from the right-click / 'm'-key context menu. Multi-select in the sidebar applies compatible operations to the whole group.

Two related folder-path commands round this out: 'Copy Current Folder Path' (vault-relative, like inbox/Work) and 'Copy Current Folder Absolute Path' / '…Server Path' for the full path. On desktop, 'Reveal Note in File Manager' (context menu 'Reveal in Finder') jumps to the note's location in Finder or File Explorer.

Sorting, grouping, and filtering the note list

Sort the note list from the sort icon (gear) in the note-list header, from Settings, or from the command palette. Options are Name (A→Z and Z→A), Updated date (newest or oldest first, the default is newest first), Created date (newest or oldest first), and Manual. Choose Manual to disable automatic sorting and drag notes up and down to set a custom order; the order persists per folder. Your sort choice persists per view.

Toggle 'Group by kind' (command palette 'Group Notes by Kind' / 'Ungroup Notes by Kind') to list folders and assets in their own sections separate from notes, instead of mixing them in a flat list.

Filter the current list by pressing '/' to focus the filter box (or use the filter input in the folder view). Matching is a case-insensitive substring across title, path, and the first-line excerpt, with instant results as you type. An icon indicates when a filter is active; press Esc to clear it. Filtering is available in every list view, including Inbox, Archive, Quick Notes, Tags, and Tasks. The Tasks, Tags, and Trash views also accept '/' to focus their local filter.

Folders

Create as many folders as you like under your primary notes area and Archive. Folder commands live in the sidebar context menu and Settings → Folders.

Reorganizing with multi-select and drag-and-drop

• Select one item with a click, a range with Shift+click, and toggle individual items with Cmd+click (macOS) or Ctrl+click (Windows/Linux). The sidebar shows the count of selected items.
• With a selection made, right-click or press 'm' to run a batch operation: open in tabs, move, archive/unarchive, trash, restore, duplicate, copy paths, or delete folders together.
• Drag a note or folder within the sidebar to move it; drops snap to folder targets and show a visual drop zone. Dragging a selected item moves the whole group.
• Dragging toward the sidebar edges auto-scrolls to reveal off-screen targets, and the scroll position is preserved after the drop.

Importing Markdown and the assets model

Bring existing Markdown into the vault by dragging .md or .markdown files onto the window. On desktop the file opens in place (in an external file window) or is imported as a copy; on web its contents are read and a new note is created. The filename becomes the title, and frontmatter and content are preserved. Programmatic import is available through window.zen.importNote().

Attachments and assets follow the file-based model described above: drop or paste images and PDFs to embed them, link documents for download or open, and manage everything from the Files/Assets views. PDFs embed with a viewer (zoom and page navigation) and can be pinned into the reference pane. New referenced files default to the vault root.

Opening notes and the vault in separate windows (desktop)

Doing the same from the command line

Every lifecycle operation has a zn CLI equivalent for scripting and automation: zn list (filter with --folder or --tag), zn create / zn capture, zn rename, zn move (--folder inbox|quick|archive|trash, optional --subpath), zn duplicate, zn archive / zn unarchive, zn trash / zn restore, and zn delete --yes for permanent removal. Folders use zn folder list|create|rename|delete, and tags use zn tag list and zn tag find. Add --json to most commands for machine-readable output. Install the CLI from Settings → CLI.

A database is just a CSV on disk plus a small sidecar file. ZenNotes stores the data as <Name>.csv (with an id column that gives every row a stable identity) and keeps field types, select options, and your saved views in a <Name>.csv.base.json file next to it. Because the data stays a plain CSV, external edits — a script, a spreadsheet, git — round-trip cleanly.

Create a database with 'New Database' from the command palette, or right-click any folder in the sidebar and choose 'New database'. Opening an existing .csv from the vault works too. Switch the raw-CSV toggle at any time to see and edit the underlying file.

Two views, one file

Fields and data

Keyboard grid (Table view)

The grid is fully keyboard-driven, vim-style. It takes focus on open (and after a Ctrl+O jump back, or after reopening the app), so motions work without clicking a row first. Editing a column name no longer swallows h/j/k/l.

Choose by what you are looking for. To jump to a note by name, use the note search palette. To find a word or phrase inside note bodies across the vault, use vault text search. To edit matches in the note you are in, use in-note find and replace. To see which notes point at the current note, use the connections panel. To browse by topic, use the Tags view.

Shortcuts below use Mod to mean Cmd on macOS and Ctrl on Windows and Linux. Vim leader sequences (Space ...) require Vim mode. Every shortcut is remappable in Settings, Keymaps.

Pick the right search

Note search palette

The note search palette is the fastest way to open a known note. It fuzzy-matches across note titles and paths and returns the 20 best matches; press Enter to open the highlighted result and Escape to close.

Filter by tag inline by typing #tag tokens anywhere in your query. Tokens render as chips, and you can mix text and tags (for example, migration #ops #prod) or search by tag alone. Navigate results with the arrow keys or Ctrl+N and Ctrl+P.

Open the note search palette

Vault text search

Vault text search looks inside note bodies across Inbox, Quick Notes, and Archive, returning line-level matches with the note path, line number, and a highlighted excerpt. Results are limited to the 80 best matches, input is debounced by 120ms, and you can open any match at its exact offset in the editor.

The engine is configurable. In Settings, Editor, set the Vault text search backend to Auto, Built-in, ripgrep, or fzf. Auto detects what is installed and prefers fzf, then ripgrep, then the built-in JavaScript search; an explicit choice overrides auto-detection. A backend indicator in the search UI shows which engine ran. If ripgrep (rg) or fzf are not on your PATH, set an absolute path in the ripgrep binary path or fzf binary path fields; leave them blank to use the binary from your PATH.

Open vault text search

Choose the search backend

In-note find and replace

Find and replace searches within the note you are editing. It highlights every match in the document, and you can replace one match or all of them. Toggle case sensitivity, whole-word matching, and regex mode with the buttons in the dialog; regex mode supports pattern replacement. The dialog is available in Edit and Split modes, but not in Preview, and your settings persist across sessions.

Use find and replace

Outline and heading palette

To move within a long note, open the heading outline palette. It shows the note's headings as a searchable tree with indentation by level and line numbers; fuzzy-filter by heading text and press Enter to jump the cursor there. In Split or Preview, the outline syncs with scrolling so the jump matches the visible location. The outline panel is a persistent, dockable version of the same view.

Jump by heading

Connections: backlinks and unresolved links

The connections panel answers what links here. It lists backlinks (other notes that link to the current note through [[wikilinks]] or standard Markdown links like [text](Note.md)) and unresolved links that could be created. Toggle it with Mod+2; it lives on the right side of the active pane.

Navigate the panel with the keyboard: j and k move the selection, gg and G jump to the top and bottom, and Enter or o opens the selected note. Press p to peek a hover preview of the selected connection without leaving the panel, then h or Escape to step back from the preview to the list, and again to return to the editor.

Work in the connections panel

Hover preview peek

Peek lets you read a linked note without fully opening it. Hover over a wikilink in the editor to show a floating preview of the target note (a short grace timer keeps the popover open so you can interact with it), or, in the connections panel, select a link and press p. You can scroll and navigate within the preview overlay.

Tags view as a search surface

When you want to find notes by topic rather than by word, use the Tags view. It shows every tag in the vault with per-tag counts; select one or more tags to list notes that match any of them (union logic), and use the in-view filter to narrow further. Clicking a #hashtag in a rendered note also opens the Tags view with that tag selected. For the full tag model, including hierarchical tags and renaming or deleting tags across the vault, see Organization.

Search by tag

Create a note from a template

Open the picker, choose a template, pick a destination folder, and name the note. ZenNotes substitutes variables and places your cursor.

Built-in templates

A curated starter set for engineering and personal work. Every one is editable — fork it from Settings → Templates to make it your own.

Template variables

Tokens are replaced when the note is created. Unknown tokens are left untouched, so your own braces survive.

Make and manage your own

Custom templates live as plain Markdown files in .zennotes/templates/, so they stay portable and versionable like the rest of your vault.

• Open Settings → Templates and press “New template”. A template is frontmatter (name, description, category, titleTemplate, targetFolder, targetSubpath) plus a Markdown body.
• Use titleTemplate to auto-name dated notes, e.g. {{date:YYYY-MM-DD}}, and targetFolder / targetSubpath to set a default destination.
• Edit a built-in to fork an editable copy that shadows the original everywhere; Reset restores the built-in.
• Hide every shipped template with “Remove Built-in Templates” (Settings → Templates or the command palette, with a confirmation), and bring them all back with “Restore Built-in Templates”. Custom templates and edited built-ins stay.
• From any note, run “Save Current Note as Template…” to capture it as a new custom template.
• Assign a template to daily and weekly notes under Settings → Vault so dated notes start pre-filled.
• Built-in templates work everywhere; custom templates require a local vault.

Markdown task syntax

ZenNotes reads unchecked and checked Markdown task list items outside fenced code blocks.

Inline task metadata

Metadata tokens are stripped from the display title but stay in the Markdown line on disk.

Kanban status columns

Status columns are derived from checkbox state, due date, and @waiting. Dragging between columns rewrites only the affected task line.

Custom statuses

Beyond the derived Status columns, the Kanban “Group by” menu has a Custom status board whose columns are a free-form workflow you define.

• List the columns, in order, in config.toml under [view], e.g. kanban_statuses = ["backlog", "in_progress", "review", "done"].
• Tag a task with an inline @status:<id> token, e.g. - [ ] Ship it @status:review. A note-level status: frontmatter key sets a default for that note’s tasks.
• Dragging a card, or pressing Shift+H / Shift+L, rewrites the @status token; the trailing “No status” column clears it.
• Statuses found on tasks but missing from the config still appear as columns, so nothing is hidden.
• Reorder the columns by dragging a column header, or pressing < / > with a column focused; the arrangement is saved per board (the “No status” column stays last).
• Rename a column by clicking its title (or [kanban_column_titles] in config.toml). The rename is a display label only: the column still shows its underlying @status:<id> beneath the name, and moving a card into it writes that value, not the label.

Kanban column titles

Column titles are editable display labels. Click the title or pencil icon, rename it, and press Enter or click away to save. Clear the field to reset the default label.

• Renaming a column does not change task grouping or task metadata.
• Status columns can be labelled Backlog, Todo, In Progress, Done, or any workflow labels you prefer.
• While dragging, the insertion line marks the exact spot where the card will land.
• Same-column reordering changes the local Kanban order only; it does not rewrite task metadata.

Global shortcuts

These work across the main app shell.

Quick capture window

These apply inside the floating capture window, opened with the quick capture hotkey.

Pane and panel motion

The primary keyboard-first movement patterns. The Vim-style ones assume Vim mode is on.

Palettes and pickers

These apply once a palette, search overlay, or picker already has focus — the command palette, note search, vault text search, outline, buffer switcher, the [[ reference picker, the / slash menu, and the date and template pickers.

Sidebar and list navigation

These bindings work when the sidebar or note list owns focus in Vim mode.

Editor writing aids

Inline completions that appear while you type in the Markdown editor.

Preview and connections

These keys apply when reading preview content or the connections panel.

Tasks, tags, and trash

These virtual views each run their own keyboard loop in the main pane, and the Vim leader works here too (for example Space h for hint mode).

Database grid (Table view)

The CSV database grid is fully keyboard-driven, vim-style. It takes focus on open (and after a Ctrl+O jump back), so motions work without clicking a row first. Editing a column name no longer swallows h/j/k/l.

Install

The CLI is shipped inside the desktop bundle. Open Settings → CLI and click Install — ZenNotes drops a zen shim into the first writable directory it finds on your $PATH (~/.local/bin, ~/bin, or /opt/homebrew/bin). The macOS admin prompt is only used when nothing user-writable is on $PATH.

• The Install / Uninstall / Open CLI Settings actions are also in the command palette under the CLI category.
• ZENNOTES_VAULT overrides the resolved vault root, useful when scripting against a non-default vault.
• --no-color and the NO_COLOR environment variable disable ANSI color in the help output.
• Run zn --help for the live command list, or zn --version for the CLI version.

Notes

Search

Folders, tags, tasks

Vault, capture, MCP

Examples

Common one-liners. Pipe stdin into capture, append, prepend, create, or write with --body -.

MCP via the CLI

zn mcp launches the same MCP stdio server the app uses. New Claude Code, Claude Desktop, and Codex installs prefer this entry whenever the CLI is present, so the server upgrades alongside the app. Existing mcp.js integrations keep working unchanged.

• MCP vault_info reports primaryNotesLocation and an inboxAbsolutePath so assistants pick the right folder for new notes.
• Tool descriptions explain that the returned path is canonical — never prefix inbox/ yourself when the vault is in root mode.

The MCP server exposes your vault to compatible assistants over the Model Context Protocol. Because it operates on the same plain Markdown files as the app, anything an assistant creates or edits shows up immediately in ZenNotes. The server runs locally via the bundled zn CLI (zn mcp).

Open Settings → MCP to see the server status (Ready, Not built, or Checking), reveal the exact launch command, connect clients, and edit the system prompt sent to assistants.

Connect an assistant

One-click install writes a managed ZenNotes entry into each client config. Uninstall removes only that entry.

What an assistant can do

The MCP server exposes the full vault toolset — read, search, create, edit, organize, and manage tasks.

Install

ZenNotes copies the bundled extension into app data, installs its dependencies, builds it, and imports it into Raycast.

• Requirements: the zn CLI installed, Node 22.14+ and npm 7+, and Raycast.
• Open Settings → CLI → Raycast on macOS and press Install (or Update / Reinstall after upgrading the app).
• The extension talks to your vault through the zn CLI, so it always reflects the live files.

Search Notes command

Raycast’s “Search Notes” command lists notes and offers actions on the selected note.

Appearance

Theme, mode, and variant

Pick a theme family — Apple, Gruvbox, Catppuccin, GitHub, Solarized, One, Nord, Tokyo Night, Kanagawa (Wave / Dragon / Lotus), or the monochrome, true-black (OLED-friendly) Black Metal — plus light or dark mode and the active flavor where supported.

Dark sidebar

Tint the sidebar slightly darker than the canvas so chrome reads as a distinct surface.

Sidebar arrows

Show or hide disclosure arrows for collapsible sidebar folders and sections. When hidden, folders and files still stay aligned.

Editor behavior

Vim mode

Turn CodeMirror Vim bindings on or off for the editor and reference pane.

Leader key hints

Show a which-key style guide after pressing Leader. Available when Vim mode is enabled.

Leader hint behavior

Choose between timed auto-hide or a sticky overlay that stays open until dismissed.

Leader hint duration

When timed, control how long the overlay stays visible and how long the pending sequence remains active.

Scroll offset

Vim scrolloff — keep N lines visible above and below the cursor so it never hugs the top or bottom edge. Default 0 (off). Only applies with Vim mode on.

Time format

Clock format the @time / @now macro inserts — 12-hour or 24-hour.

Vault text search backend

Auto, built-in, ripgrep, or fzf. Auto prefers system tools when installed. Settings shows the resolved runtime backend.

Live preview

Hide Markdown syntax on lines you are not actively editing.

Note tabs and wrap tabs

Enable tab-based editing, and wrap the tab strip when it overflows.

Word wrap

Wrap long lines to editor width or let them scroll horizontally (also Alt+Z).

Blinking cursor

Blink the editor caret and Vim block cursor, or turn it off for a solid cursor — e.g. to match the macOS "Prefer non-blinking cursor" accessibility setting.

Smooth preview scroll

Animate Ctrl+D / Ctrl+U half-page scrolling in the preview pane.

PDFs in edit mode

Choose between compact PDF cards or full inline PDF embeds while editing.

Date-titled Quick Notes

Name quick notes by date instead of timestamp-based titles.

Quick Note prefix

Choose the prefix used for new quick note titles, or leave it blank for a bare timestamp/date.

Quick capture hotkey

Record, reset, or disable the system-wide hotkey (default Cmd/Ctrl+Shift+Space) that opens the floating quick-capture window.

Typography and layout

Interface, text, and monospace fonts

Choose different fonts for chrome, reading text, and code blocks.

Font size and line height

Tune reading density in the editor and preview.

Reading and editor width

Cap long lines so wide windows stay readable.

Content alignment

Center note content in its column or left-align to the pane edge.

Line numbers

Off, absolute, or relative gutter numbering.

Line number position

Keep the gutter next to the centered text or pin it to the editor edge.

Keymaps

Shortcut overrides

Remap global shortcuts, Vim bindings, panel navigation, and view actions from one place.

Recorded sequences

Capture single shortcuts or multi-step sequences like Leader flows, pane prefixes, g g, g d, or fold motions — no raw config editing.

Context-menu bindings

The same keymap table controls the context-menu action used across the sidebar, note list, and active-tab menu.

Reset controls

Clear an individual override or reset the entire keymap table to shipped defaults.

Vault

Vault location

Reveal or change the root folder ZenNotes treats as the active vault.

Primary notes location

Choose whether Inbox stays the main notes area or whether the vault root itself becomes the primary notes surface.

Daily notes

Enable daily notes, choose the directory, and assign a template so each day’s note starts pre-filled. Open today’s note with Space d, :daily, or the command palette.

Weekly notes

Enable weekly notes with a YYYY-Www title, choose a directory, and assign a template. Open this week’s note with Space w, :weekly, or the command palette.

Monthly notes

Enable monthly notes with a YYYY-MM title (e.g. 2026-07), choose a directory, and assign a template. One note per calendar month, handy for monthly reviews and reflections. Open this month’s note with Space m, :monthly, or the command palette. Each notes section collapses its fields when its toggle is off.

Folder icons

Right-click a folder in the sidebar and choose a custom icon that follows the current theme colors.

Saved Remote Workspaces

Save multiple remote servers or vaults, reconnect from Settings or the command palette, and edit or remove them later.

Remote workspace controls

When connected remotely, Settings exposes Change Remote Vault…, Return to Local Vault, and Open Local Vault….

Templates

Template library

Browse every template — built-in and custom — in one place.

Create a custom template

Author a new template as Markdown with optional frontmatter (name, description, category, titleTemplate, targetFolder, targetSubpath) and variables. Saved as a .md file in .zennotes/templates/.

Edit or reset built-ins

Press Edit on a built-in to fork an editable copy that shadows the original; Reset removes the copy and restores the built-in. Custom templates can be edited or deleted directly.

Remove or restore built-ins

Hide all the shipped templates with “Remove Built-in Templates” (a button here, or the command palette; it asks first), and bring them back with “Restore Built-in Templates”. Your custom templates — and anything already pointing at a built-in by id, like a daily-note template — keep working.

Save current note as template

The “Save Current Note as Template…” command captures the active note as a new custom template.

MCP

MCP server status

Shows whether the local MCP server is Ready, Not built, or Checking, and reveals the exact launch command.

Client integrations

One-click install/uninstall a managed ZenNotes entry for Claude Code, Claude Desktop, and Codex.

Instructions editor

Edit the system prompt sent to assistants; default or custom, saved to .zennotes/mcp-instructions.md.

CLI

Install zen

Install the bundled `zn` command into a user-writable directory on $PATH (~/.local/bin, ~/bin, or /opt/homebrew/bin preferred). Falls back to the macOS admin prompt only when no user-writable target is on $PATH.

Uninstall zen

Remove the installed shim. Never touches an unmanaged binary that happens to share the same path.

Reinstall / update

Reinstalls the shim against the current desktop build, useful after upgrading the app.

Status and path

Shows whether `zn` is installed, where it lives, and which app build it points to.

About

App identity

App icon, current version, and a short description of ZenNotes.

Configuration file

Portable preferences are mirrored to a plain-text config.toml you can sync across machines. See the Configuration file reference below for its location, full contents, and how to use it.

Lumary Labs

About section links to lumarylabs.com.

Where it lives

What it contains

A trimmed example. The real file lists every option (with allowed values) and every keymap action (defaults commented out).

# ZenNotes configuration  —  portable preferences (theme, editor, vim,
# keymaps, …) you can sync across machines with git, stow, or chezmoi.
# Safe to hand-edit; changes apply live, no restart. Every option is listed
# with its allowed values; a removed option reappears with its default.

config_version = 1

[vim]
enabled = true  # true | false — CodeMirror Vim bindings
insert_escape = ""  # key sequence to leave insert mode, e.g. "jk"; empty disables
yank_to_clipboard = false  # also copy Vim yank/delete/change to the clipboard

[search]
backend = "auto"  # auto | builtin | ripgrep | fzf
ripgrep_path = ""  # absolute path to ripgrep; empty = look on $PATH

[editor]
live_preview = true  # hide markdown syntax on inactive lines
render_tables = true  # render tables as widgets in live preview
font_size = 16  # editor + preview font size (px)
line_height = 1.65  # line-height multiplier
word_wrap = true  # wrap long lines vs. scroll horizontally
# … more editor options …

[appearance]
theme_family = "gruvbox"  # apple | gruvbox | catppuccin | github | nord | tokyo-night | kanagawa | …
theme_mode = "dark"  # light | dark | auto

[typography]
text_font = ""  # editor + preview font; empty = system default
mono_font = ""  # code / monospace font; empty = system default

[view]
tasks_view_mode = "kanban"  # list | calendar | kanban
calendar_week_start = "monday"  # monday | sunday | locale
# … more view options …

# Keymap overrides — uncomment a line and edit the binding to remap.
# Binding syntax: "Mod+P" = Cmd/Ctrl+P, "Shift+Mod+K", "Ctrl+W", "Space",
# or a two-key sequence like "g g".
[keymaps]
"global.focusPaneLeft" = "Ctrl+H"          # an active override
# "global.commandPalette" = "Shift+Mod+P"  # Open command palette
# "global.modePreview" = "Mod+6"           # Switch to preview mode
# "tasks.moveTaskUp" = "K"                 # Move task up
# … every action is listed, defaults commented out …

# Rename the built-in folders (inbox, quick, archive, trash).
[folder_labels]
# inbox = "Notes"

# Kanban column titles, keyed by "<groupBy>:<columnId>".
[kanban_column_titles]
# "status:todo" = "To Do"

How to use it

• Sync it: commit the file to your dotfiles and pull it on another machine — theme, editor, Vim, keymaps, fonts, and search backend all carry over (git, stow, chezmoi, …).
• Live and two-way: hand-edit the file (or git pull a synced copy) and changes apply immediately, no restart; change a setting in the app and the file updates to match.
• Self-documenting: every option shows its allowed values inline, and every keymap action lists its default binding (commented out) — uncomment and edit to remap.
• Nothing to set up: your current preferences are written out automatically on first launch, and a removed option reappears with its default the next time the app rewrites the file.
• Machine-specific layout (window size, pane widths, collapsed folders) is deliberately kept out, so the file does not churn as you work.
• Comments you add yourself may be dropped when the app rewrites the file.

Two ways to customize

A theme is a complete palette you select under Settings → Appearance → Custom. An override is a small CSS file that layers on top of whichever theme is active, toggled on or off under Settings → Appearance → Overrides.

Reach for a theme to design a whole look; reach for an override to change one or two things — a different accent, a darker background — without forking a theme.

Build a custom theme

Settings → Appearance → Custom → New theme scaffolds a folder at ~/.config/zennotes/themes/<name>/ with a manifest.json and a theme.css, reveals it, and adds a card you click to apply. Edits to theme.css apply live.

Only the active theme's CSS is loaded, so you write unscoped selectors: put light or shared values under :root, and dark-mode overrides under :root[data-theme-mode="dark"]. You never put the theme name in a selector. Colors are space-separated RGB triplets, e.g. --z-accent: 255 59 48; (= #ff3b30).

A starter theme.css

:root {
  --z-bg: 255 255 255;        /* space-separated RGB triplets */
  --z-bg-softer: 245 245 247;
  --z-fg-1: 29 29 31;
  --z-accent: 0 122 255;
}
:root[data-theme-mode="dark"] {
  --z-bg: 28 28 30;
  --z-fg-1: 255 255 255;
  --z-accent: 10 132 255;
}

/* Optional: bundle a font next to theme.css and point a token at it */
@font-face {
  font-family: "My Font";
  src: url(zen-theme://my-theme/my-font.woff2) format("woff2");
}
:root { --z-text-font: "My Font", ui-sans-serif, sans-serif; }

Design tokens (--z-*)

The seeded overrides/example.css lists them all with copy-paste recipes.

manifest.json

Overrides — tweak any theme

An override is a .css file in ~/.config/zennotes/overrides/, toggled under Settings → Appearance → Overrides. Enabled overrides inject on top of the active theme in filename order, so they win the cascade — target :root[data-theme] { … } so the rule beats both built-in and custom themes.

Because they sit on top, one override re-themes everything: :root[data-theme] { --z-accent: 255 59 48; } turns the accent hot pink on every theme. Overrides stack, so keep several small ones and flip each independently. The seeded example.css is a commented cookbook with the full token list and ready-to-uncomment recipes.

Fonts, images, and finding what to change

Bundle an asset with a theme by dropping the file in the theme folder and referencing it with the zen-theme:// scheme, where the host is the folder name: url(zen-theme://my-theme/display.woff2). Remote http/https URLs are never loaded, so themes stay self-contained and work offline; small images can also be inlined as data: URIs.

To find which token or class controls an element, use the Developer tools button in Settings → Appearance → Overrides and inspect it.