WitNote: a local-first Markdown editor with an optional Ollama or cloud AI layer

The problem WitNote targets: writing tools that keep your files

Most writing applications that add AI features also add a database. Notes go into a proprietary store, exports are lossy, and the AI layer becomes the reason the app exists rather than a tool inside it. WitNote takes the opposite position. The README describes the project as "a clean, lightweight, and local-first Markdown companion" and states that all files remain on local disk. You open a folder as a workspace, and the folder is the workspace. There is no import step and no index to rebuild.

The intended user is someone who already writes in Markdown and wants two things the usual editors do not combine: a live preview pane that handles GFM and LaTeX, and an assistant that can run without sending text to a server. The README frames the AI as "an offline encyclopedia, translator, and writing assistant" rather than an agent that edits your document on its own. That is a deliberate scope limit, and it is the most interesting design decision in the project.

How the Electron build is put together

The repository is a Vite plus React application wrapped in Electron. The package.json main field points at dist-electron/main.js, and the renderer is built by Vite from index.html and src/. Development runs the two processes side by side: the electron:dev script starts Vite and then launches Electron once http://localhost:5173 responds.

The dependency list shows how the preview is assembled rather than hand-written. marked handles Markdown parsing, katex handles math, dompurify sanitises the rendered output, and react-resizable-panels provides the split view. File watching uses chokidar, so external edits to an open file are noticed. Document import is covered by mammoth for .docx and pdfjs-dist with react-pdf for PDFs. State that needs to survive a restart goes through electron-store.

AI is split across two paths. @mlc-ai/web-llm runs models inside the renderer, and Ollama plus cloud providers are reached over the network. The build scripts reveal a constraint the README does not spell out: build:win and build:linux both set DISABLE_WEBLLM=true before running tsc and vite build. In other words, the WebLLM in-browser model path is compiled out of the Windows and Linux release builds. On those platforms the local option is Ollama, not a bundled model.

Building WitNote from source and opening a vault

The README gives the source build directly. Clone the repository, install dependencies, and start the development server. The first command below is the clone and install sequence as written in the README.

# Clone repository
git clone https://github.com/hooosberg/WitNote.git
cd WitNote

# Install dependencies
npm install

# Start development mode
npm run dev

After npm run dev, a Vite dev server starts and the Electron window opens pointing at it. If you prefer the two processes separated, the package.json defines electron:dev, which runs concurrently "vite" and wait-on http://localhost:5173 && electron . The port to expect is 5173.

Packaging is per platform and the scripts differ. Windows and Linux builds disable WebLLM as noted above.

# Package for Windows
npm run build:win

# Package for Linux
npm run build:linux

There is a separate ARM64 Windows target, build:win:arm64, which appends --arm64 to electron-builder. On macOS the relevant scripts are build:mac:dmg and build:mas, and there is a build:mac:dmg-test variant that sets SKIP_NOTARIZE=true. Notarisation reads credentials from environment variables, and .env.example lists them: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD and APPLE_TEAM_ID, with optional CSC_LINK and CSC_KEY_PASSWORD. The file warns not to use your main Apple ID password.

Once the app is running, the README says to open any local .md or .txt file or a folder as a vault. The left pane is the editor, the right pane is the live render. To use a local model, install Ollama separately and point WitNote at it; the README lists Ollama and a Cloud API option (DeepSeek, OpenAI and similar) as the two AI connections. It does not document the exact settings screen or the default endpoint, so expect to find the connection fields in the app's settings rather than in the README.

Where WitNote is the wrong tool

The most concrete limitation is architectural. The README states that macOS, iOS and iPadOS have moved to "a 100% pure native architecture written in Swift & SwiftUI", distributed through the Mac App Store. The open-source TypeScript repository you can read and build is the Windows and Linux edition. If your reason for choosing an open-source editor is that you can inspect the code running on your machine, the macOS build does not satisfy that, and the README's own note that Mac users "who prefer the open-source Electron build can still compile and run it from source" confirms the two are separate artefacts.

The second limitation is the WebLLM path. Because the Windows and Linux build scripts set DISABLE_WEBLLM=true, the promise of an in-app local model applies to the macOS Electron build, not to the released Windows and Linux packages. On those platforms, local AI means running Ollama as a separate service. That is a reasonable trade, since Ollama gives you larger models, but it is not what a reader skimming the feature list would assume.

The third gap is collaboration. Nothing in the README, the package.json or the repository layout describes sync, multi-user editing, or a server component. This is a single-user, single-machine editor. If you need shared documents with revision history, WitNote is not that product and there is no documented roadmap toward it.

How WitNote differs from Obsidian and from plain VS Code

Obsidian is the closest comparison and the difference is in where the AI sits. Obsidian is also a local Markdown vault editor, but its core product has no built-in assistant; AI arrives through community plugins that you install, configure and trust individually. WitNote ships the AI connection as part of the application, with Ollama and cloud providers listed as first-class options in the README, and adds sanitisation through DOMPurify in the render path. The trade is the reverse of Obsidian's: fewer extensions, more opinion, and a smaller surface to reason about.

VS Code with a Markdown preview extension is the other realistic alternative. It gives you a mature editor, a huge extension ecosystem and the same file-on-disk model. What it does not give you is a two-pane writing surface designed around prose, or a settings screen that treats a local model as a normal option. If your Markdown lives inside a repository you already edit in VS Code, adding WitNote means a second application for the same files.

Maintenance, licence and the cost of staying current

The last push to the repository was on 2026-08-23, the same day as the v2.0.1 release. The release notes for v2.0.1 are titled "Returning to Simplicity: Security Hardening & Dual-Arch Releases", which matches the README's claims about DOMPurify sanitisation and about x86_64 and ARM64 packages from v2.0.1 onward. Before that, v1.3.2 and v1.3.3 landed in January 2026, so the gap between release trains was roughly seven months. The README states that the open-source edition "will continue active, long-term development", but the release history is the more useful signal for planning upgrades.

The licence is MIT. The README states it, the badge says MIT, and package.json carries "license": "MIT". The repository's top-level file list includes a LICENSE file, so the text is in the tree, though its contents are not reproduced in the README. MIT permits commercial and private use and modification with attribution and no warranty, which is the usual arrangement for a desktop editor. That is a description of the licence, not legal advice; read the LICENSE file before you rely on it.

Upgrade cost is mostly the Electron toolchain. The devDependencies pin Electron ^28.0.0 and the build depends on electron-builder plus @electron/notarize for macOS. Rebuilding after a dependency bump means re-running tsc and vite build, and on macOS re-supplying the Apple credentials from .env.example. End users on Windows and Linux install from the .exe, .AppImage or .deb assets on the Releases page, so the upgrade path is a reinstall rather than a package manager update unless your distribution packages it.

Editorial conclusion

WitNote suits writers who want a dual-pane Markdown editor that never holds their files hostage and who are willing to point it at Ollama or paste a cloud API key when they want AI help. It is the wrong choice if you need a single cross-platform codebase you can audit end to end, because the macOS build is a separate Swift application, and if you need collaborative editing or a sync service, neither is documented. Before adopting it, check the release assets for your architecture, confirm the MIT licence text in the repository, and decide whether the Electron build on macOS is acceptable to you.

Frequently asked questions

Official sources

1. hooosberg/WitNote on GitHub
2. Issues
3. Project website
4. README
5. Releases