- TypeScript 97.1%
- CSS 1.3%
- Nix 1%
- JavaScript 0.4%
- Shell 0.1%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| .agents/skills/quartz | ||
| .claude | ||
| .codex | ||
| .forgejo/workflows | ||
| .opencode/plugins | ||
| .trail | ||
| apps | ||
| docs | ||
| e2e | ||
| nix | ||
| packages | ||
| scripts | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .envrc | ||
| .gitattributes | ||
| .gitignore | ||
| .mcp.json | ||
| .nvmrc | ||
| .quartz.json | ||
| AGENTS.md | ||
| biome.json | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| compose.prod.yaml | ||
| compose.yaml | ||
| flake.lock | ||
| flake.nix | ||
| lefthook.yml | ||
| LICENSE | ||
| opencode.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.base.json | ||
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.
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,
pputs vim's register and"+pthe 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,
#tagin 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.mdis 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,
.excalidrawdrawings,.kanbanboards 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,/compactand/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'
recallandsearch_notesfind 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.

