An entire ecosystem for note taking with a docker container overlord.
  • TypeScript 58.7%
  • Kotlin 31.2%
  • JavaScript 6.2%
  • CSS 3.4%
  • Nix 0.2%
Find a file
Matthew Weber 91cded2195
Some checks failed
checks / check (push) Has been cancelled
fix for sync again
2026-11-17 19:22:40 -05:00
.claude ui fix 2026-09-05 15:15:02 -04:00
.forgejo/workflows fixes 2026-11-06 19:36:00 -05:00
.impeccable Client: list sort, sliding indicators, motion, and a rail that folds to icons 2026-11-13 02:37:43 -05:00
android Android: refuse vault switches to vaults the phone does not list 2026-11-14 01:56:19 -05:00
docs Desktop: follow the config of the ultimus that is running 2026-11-17 03:34:34 -05:00
packages fix for sync again 2026-11-17 19:22:40 -05:00
plugins fixes 2026-11-06 19:36:00 -05:00
scripts fixes 2026-11-06 19:36:00 -05:00
.dockerignore initial work phase 0 2026-09-04 01:10:52 -04:00
.env.example secret management 2026-09-05 02:13:13 -04:00
.gitignore add claude to gitignore 2026-09-10 13:28:59 -04:00
docker-compose.yml fixes 2026-11-06 19:36:00 -05:00
Dockerfile plugin store 2026-09-11 21:24:45 -04:00
eslint.config.mjs fixes 2026-11-06 19:36:00 -05:00
flake.lock electron apps 2026-10-30 11:02:04 -04:00
flake.nix electron apps 2026-10-30 11:02:04 -04:00
package-lock.json Client: follow the HeroUI mockup's layout, not just its colours 2026-11-13 01:38:51 -05:00
package.json fixes 2026-11-06 19:36:00 -05:00
PLAN.md knowledge graph 2026-10-11 21:29:36 -04:00
README.md fixes 2026-11-06 19:36:00 -05:00
tsconfig.base.json fixes 2026-11-06 19:36:00 -05:00

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_PROXY so login rate limits are per client.

Documentation