- TypeScript 58.7%
- Kotlin 31.2%
- JavaScript 6.2%
- CSS 3.4%
- Nix 0.2%
|
|
||
|---|---|---|
| .claude | ||
| .forgejo/workflows | ||
| .impeccable | ||
| android | ||
| docs | ||
| packages | ||
| plugins | ||
| scripts | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| eslint.config.mjs | ||
| flake.lock | ||
| flake.nix | ||
| package-lock.json | ||
| package.json | ||
| PLAN.md | ||
| README.md | ||
| tsconfig.base.json | ||
Notes
A self-hosted note ecosystem. Notes are plain Markdown files with YAML frontmatter; one server syncs them, and every client works against the same protocol: web, an Electron desktop shell, a CLI, a TUI, an Android app, a browser clipper and an MCP server for agents.
The files outlive the app. On the server the visible notes/ tree is
materialised from a content-addressed object store, and SQLite is only an
index that can be rebuilt from the commit log. Each note has its own
append-only commit chain, and edits that diverge are merged three-way on the
server. A real conflict comes back with all three sides, and nothing picks a
winner.
Layout
| Path | What it is |
|---|---|
packages/shared |
Types, schemas and note parsing every package uses |
packages/vault |
The storage core: object store, commit chain, merge, index |
packages/server |
Express API, sync socket, auth, plugins, the media worker |
packages/client |
The React web client, also served by the server at / |
packages/desktop |
The Electron shell around the web client |
packages/cli, packages/tui |
note and notes-tui, on a local or served vault |
packages/mcp |
notes-mcp, the vaults as MCP tools |
packages/clipper |
The browser extension |
plugins/ |
Bundled plugins, installable from the app |
android/ |
The Kotlin Android client (Gradle, separate from npm) |
Working on it
On NixOS enter the dev shell first (nix develop): npm's own Electron binary
cannot run there.
npm install
npm run build # every workspace, in dependency order
npm test # every package's suite, then the plugins'
npm run typecheck
npm run lint
npm run check # all of the above plus a dependency audit, as CI runs it
npm run coverage # line and branch coverage across the packages
npm run dev -w @notes/client # Vite with HMR, proxying /api to a server
npm run check is scripts/check.sh, which is also the whole of CI
(.forgejo/workflows/checks.yml). Android has its own suite:
cd android && ./gradlew test.
Running the server
docker compose up -d --build # API and web client
docker compose --profile media up -d --build # plus ffmpeg and whisper
Configuration is environment variables in docker-compose.yml, each one
explained where it is set. The signing secret is a file, not an environment
variable; see docs/SECRETS.md.
Security model, briefly
- Registration stays open until
NOTES_ALLOW_REGISTRATION=false. Set it once your own account exists, or anyone who can reach the server can make one. - Passwords are Argon2id. Device and API tokens are stored hashed, and refresh tokens rotate on every use.
- API tokens are scoped (
notes:read,notes:write,capture, and per vault). Installing plugins and using the plugin network proxy need the account itself (a session or a paired device), never a token. - Server-side fetches refuse private and link-local addresses unless you opt
in (
NOTES_MIRROR_ALLOW_PRIVATE,NOTES_PLUGIN_ALLOW_PRIVATE). - The web client runs under a strict CSP, and rendered Markdown goes through a DOMPurify allowlist.
- Behind a reverse proxy, set
NOTES_TRUST_PROXYso login rate limits are per client.
Documentation
- PLAN.md: the phased build plan and the reasoning behind it
- docs/SYNC.md: the sync protocol, merging and offline
- docs/VAULTS.md: local and served vaults
- docs/SECRETS.md: secrets and deployment settings
- docs/PLUGINS.md: writing a plugin
- docs/DESIGN.md: the design system
- docs/DESKTOP.md, docs/TUI.md, docs/MCP.md, docs/CLIPPER.md, docs/ANDROID.md: the clients
- docs/STICKERS.md, docs/STICKER-LICENCES.md: the sticker pack