Commonplace

Your notes. Your machine. No accounts, no cloud, no lock-in.

Commonplace is an open-source, local-first Markdown vault — a desktop app and browser tool for building a personal knowledge base where you own everything. Notes are plain .md files in a folder you choose. The app is a viewer, editor, and intelligent index on top of them.

Live site & browser app: https://commonplace-99b.pages.dev/

---

Why Commonplace?

Most note-taking tools make a trade: your data lives on their servers, syncs through their cloud, and requires an account to access. Commonplace makes the opposite bet:

• Notes are plain Markdown files on your disk — readable and editable with any tool forever.
• The app adds intelligence (search, backlinks, graph, semantic memory) as a rebuildable derived layer on top of that Markdown source of truth.
• Nothing about the core experience requires a backend, an account, or a network connection.
• Multi-device sync works with whatever sync tool you already trust (Syncthing, iCloud, Dropbox, Git, etc.).

---

Two Ways to Run It

Desktop App (Electron) — Primary Direction

A native desktop application (macOS, Windows, Linux) backed by a full Node.js main process. Owns all filesystem and SQLite work; the renderer is treated as untrusted and communicates over a narrow IPC bridge.

Browser Fallback

The same React renderer runs in a browser with either the File System Access API (Chrome/Edge on desktop, for real local-folder access) or localStorage (everything else, for quick trials and demos).

---

Feature Overview

Core Editing

• Live Markdown editing with preview and split view
• Wiki links ([[Note Title]]) with autocomplete and hover preview
• Inline H1 rename — click the title in the topbar to rename the file
• Multi-tab workspace with per-tab back/forward history, pinned tabs, tab overflow dropdown, and right-click tab context menu
• Tabs persist across launches — via .commonplace/workspace.json in Electron, localStorage in browser

Organization & Navigation

• Folder-grouped sidebar with a real nested folder tree and per-file-type icons (Markdown, image, audio, video)
• Command palette (Ctrl+K) ranked by recently-opened notes (MRU, capped at 30)
• Resizable sidebar and right rail with widths persisted across sessions
• Multi-vault switcher — auto-detects vaults under ~/Documents/Commonplace/; create or switch via the Vaults dialog

Search

• Full-text search via SQLite FTS5 (Electron) or MiniSearch (browser), with a punctuation-safe query tokenizer
• Semantic search — find notes by meaning using a local embedding model. Toggle between Keyword and Semantic modes in the command palette

Knowledge Graph

• Backlinks panel — see every note that links to the current one
• Graph view with clickable nodes, focus/neighborhood mode, and basic filter
• Related Notes panel — surfaces semantically similar notes from the local embedding index

Local AI (opt-in, fully local)

All AI features run on your machine. No cloud API keys. No data leaves your device.

Feature	How it works
Semantic memory	Embeds your notes with Ollama or a local ONNX model; powers Related Notes, Suggested Links, and semantic search
Suggested wiki links	Recommends [[links]] to add between related notes; you accept or dismiss each one
Duplicate review	Finds notes with high semantic or keyword overlap; side-by-side compare view, explicit-only actions
Transcript import	Paste raw transcripts; Ollama-backed enhancement extracts speakers, action items, and hashtags (desktop only)
Audio transcription	Bring your own Whisper.cpp binary and model, or configure any local command — Commonplace runs it on demand

No automatic file rewrites. Every suggestion requires explicit user approval.

Desktop-only Capabilities

• SQLite metadata index (.commonplace/index.sqlite) covering files, frontmatter, wiki-links, headings, and FTS5 rows — fully rebuildable derived data, never the source of truth
• File watching via chokidar: stale-note banner on external edits; optimistic-concurrency WriteConflictError on save races
• Vault Health panel (Settings → Advanced) — local-only diagnostics across vault, index, semantic memory, review queues, transcript enhancement, and auto-updater; no telemetry
• MCP server — optional read-only local server (mcp:start) for exposing your vault to Claude Desktop or other MCP-compatible agents
• Import Browser Export ZIP — bring a browser-mode export into a desktop vault without manual unzipping
• Auto-updater via GitHub Releases

Shell & UX

• Settings dialog with filtered section navigation and hotkey rebinding
• Attachment management — files copied into Attachments/ with duplicate filename handling; safe image preview via IPC
• Import / export ZIP flows for full vault backup and migration
• Vault settings — theme, default folders, daily-notes folder, semantic-indexing toggle
• Frameless titlebar with native overlay window controls; native menu bar hidden on Windows

---

Storage Modes

Local-folder vault (recommended)

Uses the File System Access API (browser) or native fs (Electron) to read and write real Markdown files in a folder you pick. Scaffolds Notes/, Daily/, Attachments/, Templates/, and .commonplace/ on first open.

Browser-local fallback

Stores notes in localStorage. Good for demos, quick trials, or browsers without File System Access API support. Import/export keeps data portable.

---

Sync Model

Commonplace has no built-in sync engine — by design. Put your vault folder inside a sync tool you already trust:

• Syncthing (open-source, peer-to-peer)
• iCloud Drive / Dropbox / Google Drive for Desktop / OneDrive
• Nextcloud
• Git (power-user workflow)

---

AI Tool Integration

Three ways to query your vault from AI coding tools, in order of how much setup they need:

• Claude Code plugin (recommended) — one-command install, ships /commonplace:search, /commonplace:context, and /commonplace:stamp slash commands plus the MCP server pre-wired. See plugins/commonplace/README.md.
• Standalone MCP server — @foolish-bandit/commonplace-mcp on npm; the read-only Model Context Protocol server underneath the plugin. Usable from any MCP-aware tool (Cursor, Codex, Claude Desktop, ChatGPT Desktop, Zed, …). See docs/MCP.md.
• CLAUDE.md generator CLI — writes a vault-derived context block into any dev repo, no MCP setup required. See docs/CLAUDE_MD.md.

Quick start for the plugin in Claude Code:

/plugin marketplace add foolish-bandit/commonplace
/plugin install commonplace@commonplace

Then export COMMONPLACE_VAULT="/path/to/your/vault" and run /commonplace:search auth flows.

---

Browser Support

Browser	Experience
Chrome / Edge (desktop)	Full — local-folder + all features
Firefox / Safari	Browser-local fallback mode

---

Getting Started

Install dependencies

npm ci

Run the browser build

npm run dev

Run the Electron desktop app

npm run electron:dev

Run tests

npm run test

Lint

npm run lint

Type-check

npx tsc --noEmit

Build

npm run build             # Static browser bundle → dist/
npm run build:site        # Marketing site + browser app → dist-site/ (Cloudflare Pages)
npm run electron:build    # Electron desktop package → release/

MCP server (optional)

npm run mcp:start         # Compiles and starts the local read-only MCP server

---

Deployment

The live site at https://commonplace-99b.pages.dev/ is deployed by Cloudflare Pages from this repo on every push to main.

Cloudflare Pages build settings:

• Build command: npm run build:site
• Build output directory: dist-site
• Node version: 22

The combined output serves / (marketing landing) and /app/ (browser app) from a single deployment.

---

Security & Privacy

• No backend server required for any core feature
• No user accounts or authentication layer
• No app-owned cloud sync — data never leaves your machine through Commonplace
• All AI features use loopback only — Ollama is accessed at 127.0.0.1:11434; no remote AI host is reachable
• Safe Markdown rendering — intentionally blocks unsafe URL and script vectors
• Narrow IPC bridge — the renderer is treated as untrusted; all filesystem and SQLite operations are owned by the main process

---

Documentation

Doc	What's in it
Architecture	System overview, data flow, component map
Status	Current shell snapshot, recent batches, known issues
Handoff	Deep post-E5b architectural snapshot (IPC map, schema, QA checklist)
Roadmap	Completed phases, active work, anti-roadmap
Electron details	Desktop-specific architecture, IPC bridge, native bindings
Development	Dev environment setup and conventions
Local Intelligence	Three-layer local AI strategy
Runtime Modes	Storage mode reference and browser → desktop migration
MCP	Local MCP server setup and security notes
CLAUDE.md generator	CLI that writes a vault-derived context block into any dev repo
Plugin + npm package	Maintainer notes on the Claude Code plugin and @foolish-bandit/commonplace-mcp publish flow
Packaging	Distribution hardening, platform packaging
Contributing	How to contribute
PR History	Merged PR log

---

License

AGPL-3.0