Note taking, done right
  • TypeScript 97.1%
  • CSS 1.3%
  • Nix 1%
  • JavaScript 0.4%
  • Shell 0.1%
  • Other 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
marti b01858807e
All checks were successful
ci / check (push) Successful in 8m25s
publish / publish (push) Successful in 5m20s
refactor(web): share one TreeRow between the file tree and the tag tree
The tag tree's file rows had flex-1 inside a column flex, so they shrank
below h-8 and the tag tree looked denser than the file tree. Both trees
now render their rows through components/TreeRow, which owns the height,
indent and the chevron, icon, label and trailing slots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 00:45:55 +01:00
.agents/skills/quartz style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
.claude refactor: make packages/shared the one source of shared rules 2026-11-17 00:21:48 +01:00
.codex style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
.forgejo/workflows chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
.opencode/plugins style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
.trail refactor: give each rule, workflow and list one home across server and web 2026-11-17 00:21:48 +01:00
apps refactor(web): share one TreeRow between the file tree and the tag tree 2026-11-17 00:45:55 +01:00
docs refactor: close the last traps the final survey found 2026-11-17 00:22:08 +01:00
e2e refactor: close the last traps the final survey found 2026-11-17 00:22:08 +01:00
nix chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
packages refactor: close the last traps the final survey found 2026-11-17 00:22:08 +01:00
scripts chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
.dockerignore refactor: remove the Electron desktop app and its packaging 2026-11-12 20:10:13 +01:00
.editorconfig chore: add repository basics and the AGPL-3.0-or-later license 2026-11-11 01:41:48 +01:00
.env.example chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
.envrc build: add the Nix devShell and a throwaway Postgres runner for tests 2026-11-11 01:41:48 +01:00
.gitattributes chore: add repository basics and the AGPL-3.0-or-later license 2026-11-11 01:41:48 +01:00
.gitignore refactor: remove the Electron desktop app and its packaging 2026-11-12 20:10:13 +01:00
.mcp.json style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
.nvmrc chore: add repository basics and the AGPL-3.0-or-later license 2026-11-11 01:41:48 +01:00
.quartz.json style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
AGENTS.md refactor(web): share one TreeRow between the file tree and the tag tree 2026-11-17 00:45:55 +01:00
biome.json chore: biome skips .claude/settings.json 2026-11-13 02:54:12 +01:00
CHANGELOG.md docs: learnings replace per-space AGENTS.md instructions (ADR 0035) 2026-11-14 06:10:46 +01:00
CLAUDE.md docs: add AGENTS.md, the README and the Trail wiring 2026-11-11 01:41:48 +01:00
compose.prod.yaml feat(nix): services.quartz.secretKeyFile for SECRET_KEY 2026-11-12 20:10:13 +01:00
compose.yaml fix: the dev compose file publishes its ports on loopback only 2026-11-13 00:58:18 +01:00
flake.lock chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
flake.nix chore: remove the quartz CLI, the sync engine and the Home Manager module 2026-11-14 04:50:59 +01:00
lefthook.yml style: format markdown with Biome and run the hook on markdown too 2026-11-11 01:45:40 +01:00
LICENSE chore: add repository basics and the AGPL-3.0-or-later license 2026-11-11 01:41:48 +01:00
opencode.json style: format the agent tooling files with biome 2026-11-16 13:40:56 +01:00
package-lock.json refactor: share the remaining rules, drop dead API, seed e2e through the client 2026-11-17 00:21:48 +01:00
package.json fix(deps): patch the audit findings and make the CI audit step blocking 2026-11-13 10:08:34 +01:00
README.md docs: the graph view can also be flat (ADR 0040) 2026-11-15 21:27:23 +01:00
tsconfig.base.json build: set up npm workspaces, Biome, TypeScript and lefthook 2026-11-11 01:41:48 +01:00

Quartz

Note-taking, done right. Quartz is a self-hosted, multi-user notes server for people who want their notes as plain Markdown files and still want to share them. Spaces are shared with other users and edited together live, and an export gives every note back as a file. The server keeps everything in Postgres, so a backup is one pg_dump.

Status: 0.1.0, the first release (changelog, with its known limitations). Linux and NixOS only for now.

A shared note in the Styled view: headings, bold, links, tasks, a table and code rendered in place, with a collaborator's cursor

The same in the dark theme

The Styled view in the dark theme

Features

  • Plain Markdown notes; the server keeps everything in Postgres, and an export gives it back as files.
  • Spaces shared with other users as owner, editor or viewer.
  • Public links: share one note, read-only, with anyone who has the link, optionally behind a password; revoke it at any time (owners, and administrators for every link).
  • Live co-editing with cursors (Yjs); offline edits merge without conflicts.
  • Profile pictures for people and spaces, cropped in the browser; your cursor takes your picture's main color, or one you pick.
  • One editor, two views: Raw shows the Markdown as written; Styled hides the syntax and renders headings, emphasis, links, tasks, tables, math, diagrams and embeds in place, showing the Markdown again on the line you edit. Optional vim motions: yanks also go to the system clipboard, p puts vim's register and "+p the system clipboard.
  • Format note (Ctrl+Shift+F): tidy lists, tables, blank lines and whitespace without touching the text.
  • Code blocks are highlighted and ```mermaid blocks draw as diagrams.
  • Math ($x^2$, $$...$$) with KaTeX, footnotes, GitHub and Obsidian callouts (> [!NOTE]), and safe raw HTML (<details>, <kbd>, <sub>).
  • An emoji picker in the editor: type : and a couple of letters.
  • Line numbers in the editor, absolute or vim-style relative to the cursor.
  • Drag in images, video and audio; embed Excalidraw drawings and kanban boards, edited live inside the note, each card opening in a side drawer with its priority, due date, assignees and notes; every space's home lists the cards assigned to you across all spaces. The embed system is open to more kinds.
  • Self-hosted Excalidraw service that uses Quartz accounts.
  • Local accounts and single sign-on through OpenID Connect.
  • Links between notes of different spaces (/s/<spaceId>/f/<path>), in backlinks, the graph and for agents.
  • Full-text search across spaces that ranks passages, weighs rare words and follows links, so a question in plain words works, and finds folders by name and tag; backlinks with the line that links, an outline, colored tags on notes and folders, kept by Quartz rather than in the Markdown (chips beside the breadcrumbs, rename across a space, dots on files, a sidebar toggle between folders and an expandable tag tree, #tag in search) with tag pages, a 3D (or flat 2D) force-directed link graph (one space, every space you belong to, or a note's neighbourhood, to turn, tilt, pan and zoom into; a second set of edges shows which notes are related though nobody linked them; filtered by tag or folder, colored by folder or tag, with broken links and orphan notes listed) and version history with a diff against the version before and restore that names the people and agents who edited, one button away in a file's header.
  • Renaming or moving a note or folder rewrites the links that point at it, so links keep working.
  • A folder's README.md is the folder's text: edited at the top of the folder's page, and a link to it is a link to the folder.
  • A change log per space: every file created, edited, moved, trashed, restored or tagged, and every tag renamed, by a person, an agent or the assistant (with the answer that made it), on a Changes page linked above the Attachments and Trash pages at the sidebar's bottom and filtered by kind, person or file, can be previewed and reverted to how it was just before; a revert over later changes asks first. Under each assistant answer, the actions it took and one button to undo them. Agents can move files to the trash but never delete for good, and undo their own changes.
  • A web app you can install as an app (PWA).
  • Keyboard-first web app: a command palette with search (Ctrl+K), a quick switcher across spaces (Ctrl+P), a side panel (Ctrl+Shift+B), a file tree driven by the arrow keys, and vim in the editor if you want it. See docs/usage.md for every shortcut.
  • Members and roles per space, managed in the app; administrators manage accounts in Settings, Users.
  • Your data is yours: Settings, Account exports the spaces you choose as one zip of Markdown, .excalidraw drawings, .kanban boards and attachments.
  • AI agents and other OAuth clients sign in through the browser and are listed in Settings, where each can be signed out.
  • A remote MCP server so AI agents can read and write notes for you.
  • A built-in AI assistant in a side panel (Ctrl+O) with the same tools as MCP agents, including reading public web pages a note links to (a repository's README, docs): it streams its reasoning and tool calls, shows what each answer cost, and keeps answering through a page reload. Any OpenAI-compatible endpoint: the server's (for everyone or chosen users) or each user's own. Prompts can be dictated through an OpenAI-compatible speech-to-text endpoint (Whisper API), set up the same way, and answers, whole notes, or a selection in a note or the chat, are read aloud through a text-to-speech endpoint (OpenAI's /audio/speech). The prompt tags files with @, quotes a selection of the chat, and takes /new, /clear, /compact and /learn. Each chat shows how much of the model's context it fills; at 80% its older part is summarized so it can go on. Optional title and compression models take that work off the chat model.
  • Optional search by meaning: with an OpenAI-compatible embedding model set for the server (a local one, such as Ollama, keeps your notes on the machine), agents' recall and search_notes find what a question means though it shares no word with the note, and the related graph also relates notes that say similar things. Notes are embedded in the background; without a model everything works from words and links. An administrator can embed every note again from Settings, AI assistant (Reindex embeddings), with its progress shown.
  • Learnings: short notes your agents keep about you (preferences, facts, decisions, lessons), the same in every space. The assistant saves one when you correct it and starts every chat from them; MCP agents read them first (list_learnings). You read, edit, pin, archive and delete them on the Learnings page, and "Learn about me" in Settings turns them off.

Stack

  • TypeScript, npm workspaces, Node 24+
  • Server: Fastify, Drizzle over Postgres 18, Hocuspocus (Yjs), MCP SDK, openid-client
  • Web: React, Vite, Tailwind CSS, daisyUI, Radix UI, TanStack Router and Query, CodeMirror 6
  • Draw: Excalidraw
  • Biome, Vitest, Playwright, lefthook, Nix flake

Quick start

Three ways to a running Quartz at http://localhost:8080 with a first administrator. Each needs Postgres 18 or newer; the first two take it from compose.yaml. Prerequisites and versions are in docs/installation.md; running it on a real server is docs/deployment.md.

Docker compose

cp .env.example .env
docker compose --profile app up --build -d --wait
printf '%s' 'a long password' | docker compose exec -T app \
  quartz-admin create-user admin --admin --password-stdin

This builds the runtime image (apps/server/Dockerfile) and the draw container (apps/draw/Dockerfile), starts Postgres, runs the migrations once and starts the server with the built web app; the server proxies /draw to the draw container. The ports are published on 127.0.0.1 only; to reach it from another machine use a reverse proxy or an SSH tunnel (docs/deployment.md). Sign in at http://localhost:8080 as admin. Stop it with docker compose --profile app down (add -v to delete the data).

Local npm and Postgres

nix develop                     # or Node 24+ on PATH
npm ci
npm run build
cp .env.example .env
docker compose --profile db up -d --wait
sed -i 's#^DATABASE_URL=.*#DATABASE_URL=postgres://quartz:quartz@127.0.0.1:5432/quartz#' .env
npm run db:migrate -w apps/server
npm run admin -w apps/server -- create-user admin --admin   # prompts for the password
WEB_DIST_DIR=../web/dist npm start -w apps/server

The server serves the web app it was pointed at; any Postgres 18 works in place of the compose one (set DATABASE_URL). For development with live reload, see docs/development.md.

Nix and NixOS

nix build git+https://git.cumsek.com/marti/quartz#quartz-server   # bins: quartz-server, quartz-migrate, quartz-admin

On NixOS, import the flake's module and switch:

{
  inputs.quartz.url = "git+https://git.cumsek.com/marti/quartz";

  outputs = {nixpkgs, quartz, ...}: {
    nixosConfigurations.host = nixpkgs.lib.nixosSystem {
      modules = [
        quartz.nixosModules.quartz
        ({pkgs, ...}: {
          services.postgresql.package = pkgs.postgresql_18;
          services.quartz = {
            enable = true;
            # Plain http://localhost; behind HTTPS leave this on.
            cookieSecure = false;
          };
        })
      ];
    };
  };
}
sudo nixos-rebuild switch --flake .#host
printf '%s' 'a long password' | sudo quartz-admin create-user admin --admin --password-stdin

The module creates the local database, runs the migrations before the server starts and puts quartz-admin on PATH. Every option is in docs/deployment.md.

Install as an app

The web app is a Progressive Web App: open your server in a browser and install it (the address bar's install button in Chromium browsers, Add to Dock in Safari, Add to Home Screen on iOS) to get Quartz in its own window with its own icon. It needs the server and an HTTPS origin (or localhost). Details: docs/usage.md.

Development

nix develop            # or install Node 24+ and Postgres 18 yourself
npm ci
scripts/with-postgres.sh npm test

See AGENTS.md for every command, docs/development.md for running the server and the web app, docs/installation.md and docs/deployment.md for running Quartz, and docs/architecture.md for how Quartz works. Connecting Claude or another AI agent: docs/mcp.md. Using the web app: docs/usage.md. Cutting a release: docs/releasing.md.

Configuration

The server reads its configuration from the environment once at boot and exits on a bad value. .env.example lists every variable with a safe development value.

Variable Default Purpose
DATABASE_URL required Postgres 18
DATABASE_POOL_MAX 10 connections in the pool
PUBLIC_URL unset external origin; required for SSO, OAuth and MCP
HOST, PORT 0.0.0.0, 8080 where the server listens
NODE_ENV development production makes cookies Secure and needs https issuers
LOG_LEVEL info Pino log level
SESSION_TTL_DAYS 30 a browser session ends after this many days without use
COOKIE_SECURE true in production Secure cookies and HSTS
TRUST_PROXY false trust one reverse proxy hop for the client address
LOCAL_LOGIN_ENABLED true password login on or off
OIDC_PROVIDERS unset comma-separated SSO provider ids
OIDC_<ID>_ISSUER, _CLIENT_ID, _CLIENT_SECRET, _NAME required per provider the OpenID Connect client
OIDC_<ID>_ALLOWED_DOMAINS unset (anyone) email domains a first sign-in must have a verified address in
OIDC_<ID>_LINK_BY_EMAIL false join an existing account through a verified email
WEB_DIST_DIR unset built web app to serve
DRAW_URL or DRAW_DIST_DIR unset where /draw comes from
MAX_UPLOAD_BYTES 104857600 largest blob accepted
TRASH_RETENTION_DAYS 30 days deleted files stay in the trash; 0 keeps them
SECRET_KEY unset encrypts the assistant's stored API keys; 32+ characters
QUARTZ_DEV_SERVER localhost:8080 web dev server only: where it proxies the API to

Documentation

Every page, by what you want to do, is listed in docs/README.md.

License

AGPL-3.0-or-later.