A local-first Markdown and MDX workspace for writing, linking, and extending your notes.
Download · Development · Architecture · Plugin API · Publishing
Neuron treats your notes as durable files, not records trapped in a hosted database. Open any folder of .md or .mdx documents and work with it as a focused desktop knowledge base — that folder is your workspace. It can stay offline, live in Git, or sync through a folder service you already use (OneDrive, Google Drive, Dropbox). You can keep several workspaces and switch between them from the title bar.
- Live Markdown editing with source, split-preview, and reading modes.
- Multiple note tabs, task checkboxes, tables, code blocks, wiki-links, and tags.
- Resizable, VS Code-style docks — drag any divider; layout persists.
- HTMX views (
.nhtml) — build custom local dashboards and tools from plain HTML + htmx, rendered in a sandboxed webview against a capability-scoped workspace API. Bundled htmx, so they work offline; permissions and variables live in an inspectable.neuronfolder. - JSON Canvas (
.canvas) boards — an infinite spatial whiteboard (Obsidian-compatible) with undo/redo, multi-select, alignment, Markdown cards, and per-node styling. - Notion-style
.dbdatabases — typed properties, colored select tags, filtering and sorting — stored as plain JSON in the workspace with atomic writes and live reload on external changes. - Built-in plugin host with commands, MDX components, side peeks, and bottom peeks.
- Optional AI integrations for OpenAI, Anthropic, Gemini, OpenRouter, and local endpoints.
- Full interactive terminal (PTY) and saved command automations for workspace-aware command-line work.
- Graphite, Void, Nord, and Light themes with configurable Markdown colors.
- Local settings and ordinary files; no Neuron account or hosted backend required.
Installers are published on the repository's Releases page. The companion GitHub Pages site always links to the newest release.
| Platform | Release formats |
|---|---|
| Windows | NSIS installer and portable executable |
| macOS | DMG and ZIP for Intel and Apple silicon |
| Linux | AppImage and Debian package |
Release builds are currently unsigned. Windows SmartScreen and macOS Gatekeeper may display a warning until signing certificates and notarization are configured. Do not disable operating-system protections globally.
- Node.js 20 or newer
- npm 10 or newer
- Git
git clone https://github.com/YOUR_ACCOUNT/Neuron.git
cd Neuron
npm ci
npm run devnpm run dev starts Vite, watches the Electron main process, waits for both to become ready, and then opens the desktop app.
npm run build # Clean previous output, then compile main + renderer
npm run dist:test # Create a local beta installer named Neuron Test
npm run release # Build and publish the production NSIS installer
npm run icon:generate # Regenerate build/icon.png from build/icon.svgGenerated output is written to dist/ and release/; both directories are cleared at the start of each build and ignored by Git. Test installers go to release/test/ and production installers go to release/prod/.
- Notes remain in the folder you choose.
- Neuron does not upload workspaces or require an account.
- Network requests occur only when you explicitly use a network-backed plugin.
- Plugin credentials and settings are stored in Electron's local user-data directory.
- The renderer runs with context isolation enabled and Node integration disabled.
Review the architecture for process boundaries and the security policy for vulnerability reporting.
| Document | Purpose |
|---|---|
| Development guide | Setup, commands, debugging, testing, and project layout |
| Architecture | Electron processes, storage, editor, rendering, and plugin boundaries |
| Plugin API | Manifests, panels, commands, runtime capabilities, and examples |
| Distribution | GitHub Actions, Releases, Pages, signing, and release checklist |
| Product brief | Audience, goals, constraints, and product principles |
| Design system | Visual tokens, components, motion, and accessibility |
| Troubleshooting | Common development, packaging, and release problems |
.github/ CI, release, Pages, contribution, and security files
build/ Canonical desktop icon source and generated PNG
docs/ Public documentation and GitHub Pages site
examples/ Demo note repository bundled with the application
public/ Renderer assets copied by Vite
src/main/ Electron main process and secure preload bridge
src/renderer/ React workspace, editor, previews, and plugin host
tools/ Development and asset-maintenance utilities
Bug reports, documentation improvements, and focused pull requests are welcome. Read .github/CONTRIBUTING.md before contributing. Please use private vulnerability reporting for security issues.
Neuron is under active development. Back up important notes and review release notes before upgrading. The file format is plain Markdown/MDX, so workspaces remain usable without Neuron.
Neuron is available under the MIT License.