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.

• 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.
• 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 task lines inline; tasks are parsed across all notes.

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 — zen CLI

Install from Settings → CLI, then run zen 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, and the external file app are desktop-only. Everything else 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 zen 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).

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

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]]) 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.
• 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.

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.

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.

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 zen --help for the live command list, or zen --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

zen 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 zen CLI (zen 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 zen 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 zen 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, 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.

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).

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.

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.

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.

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 `zen` 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 `zen` 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.

Lumary Labs

About section links to lumarylabs.com.