Notes

Notes is a local-first Markdown desktop app. Your documents live in a folder you control and are never bundled into the application.

Install

On macOS 13 or newer with Apple Silicon, install with Homebrew:

brew install --cask nkzw-tech/tap/notes

To update Notes, run brew update && brew upgrade --cask nkzw-tech/tap/notes.

You can also download Notes from GitHub Releases:

• macOS (Apple Silicon): Extract the Notes-darwin-arm64-*.zip archive and drag Notes.app to Applications.
• Windows (x64): Extract the Notes-win32-x64-*.zip archive and run Notes.exe.
• Linux (x64): Install the .deb or .rpm package for your distribution.

Using Notes

Use ⌘P to search and switch between files. Use ⌘K for the full command palette, including file navigation and document actions. On Windows/Linux, use Ctrl instead of ⌘.

Use ⌘ShiftC to copy the entire active note as Markdown, including unsaved edits. Ordinary ⌘C still copies the selection.

Open another window with File → New Window or ⌘N (CtrlN on Windows/Linux) to view notes side by side. New windows start blank with the document picker focused: type to search and press Enter to open a note, or Escape to leave the window blank. Each window navigates independently, and saved edits update other windows on the same workspace. Concurrent edits require resolving a conflict before saving. Each window keeps its own crash recovery draft.

New windows inherit the focused window's sidebar layout. Quitting the app restores all open windows on the next launch, including their notes, sidebar visibility and width, expanded sections, and window positions. Closing a window with ⌘W removes it from that session. If you close every window, the next window uses the last closed window's layout.

Workspaces

On first launch, choose an existing workspace or an empty folder. Notes remembers the selection in ~/.config/nkzw-notes/config.json. Switch workspaces at any time with File → Open Workspace… or ⌘O.

An empty folder is initialized with privacy-safe templates and this structure:

AGENTS.md
config/
  people.json
  workspace.json
docs/
interviews/
meetings/
people/
reports/

The command menu can create regular documents, interviews, people, and reports. Markdown files remain the source of truth and can be edited with any other editor.

You can also select a workspace when starting the app from a terminal:

NOTES_WORKSPACE=/absolute/path/to/workspace pnpm dev
pnpm electron -- --workspace=/absolute/path/to/workspace

Development

Notes requires Node.js 23 or newer and pnpm 12.

Vite+ runs development, builds, tests, linting, formatting, and type checks, using the same tooling setup as Codiff. Run pnpm check to validate the repository or pnpm exec vp check --fix to apply formatting and lint fixes. pnpm install configures the staged checks that run before commits.

pnpm install
pnpm test
NOTES_WORKSPACE=/absolute/path/to/workspace pnpm dev

In another terminal, launch Electron against the development renderer:

pnpm dev:app

Build the standalone application and distributable for your current platform with:

pnpm make

On Apple Silicon, the packaged app is written to out/Notes-darwin-arm64/Notes.app, and its ZIP is written under out/make/. Use pnpm package:app to create only the unpacked application. Signing and notarization are enabled when the corresponding Apple environment variables are provided.

On macOS, development and packaging also compile the optional Clear Liquid Glass bridge using the public AppKit API. Building it requires an Xcode or Command Line Tools SDK for macOS 26 or newer and Node.js development headers (NOTES_NODE_HEADERS can override their location). pnpm native:build builds the universal Node-API binary separately; pnpm exec electron scripts/glass-smoke.cjs checks native attachment, clipped corners, focus changes and typing, resizing, movement, visibility, toggling, and window isolation on macOS 26+. The glass lives in a non-activating child panel immediately behind the editor, so taking keyboard focus doesn't change its frosting. Its decorative edges extend beyond a clip matching the window corners; Transparency mode disables the foreground window shadow to avoid text-shaped shadows at high transparency. Other platforms skip this bridge. Cmd+K offers two independent toggles: Transparency mode (Clear Liquid Glass at 99% background transparency) and Keep window on top. Both start off when Notes opens; normal appearance remains the default.

Persistence changes must preserve the save ownership rules and stress tests. After building, pnpm test:soak exercises six real minutes of typing and a save-aware quit in a disposable Electron workspace.

Measure startup with pnpm exec electron scripts/startup-benchmark.cjs 500 6 after building. It opens six real Electron windows against 500 fictional notes in a temporary workspace, reports time to editable content and whether a loading screen appeared, and quits through the save-aware lifecycle. See Startup for the startup path and measurement limits.

Releases

Pushing a version tag such as v0.1.0 builds Linux x64 DEB/RPM packages and a Windows x64 portable ZIP, attaches them to a GitHub Release, and publishes it after both builds succeed. The tag must match the version in package.json.

See Distribution for the release commands, rebuilding existing release assets, and signing and uploading the macOS app.

Privacy

Workspace Markdown and metadata are loaded at runtime and excluded from the application bundle. The repository contains only generic starter templates and fictional test data. Please do not include personal workspaces in issues or pull requests.

Contributing

See CONTRIBUTING.md.

License

MIT © Nakazawa Tech