Quark

Currently password login only. OIDC (via MAS) and SSO are planned. Other in-progress items — theme filesystem hot-reload, key backup (SSSS), emoji/sticker pack management UI, and mobile (iOS/Android) builds — are tracked in DESIGN.md.

Architecture

┌─────────────────────────────────────┐
│        Web Frontend (TypeScript)    │
│   Monospace / terminal-styled UI    │
│   Renders HTML, images, emoji       │
├─────────────────────────────────────┤
│          Tauri v2 IPC Bridge        │
├─────────────────────────────────────┤
│         Rust Backend (Core)         │
│   matrix-sdk  ·  Vodozemac E2EE     │
│   Matrix /sync  ·  Media cache      │
└─────────────────────────────────────┘

• Frontend — vanilla TypeScript with direct DOM manipulation (no React/Vue) to keep the terminal feel without framework overhead. Built with Vite, tested with Vitest.
• Backend — Rust with matrix-sdk 0.9 (the same SDK behind Element X), handling protocol, sync, E2EE, and media. Bundled by Tauri v2 — roughly 10× smaller binary and far less RAM than Electron.

See DESIGN.md for the authoritative spec and CLAUDE.md for the contributor-oriented architecture overview.

Getting started

Prerequisites

• A Rust toolchain (stable, ≥ 1.78)
• Node.js + pnpm (packageManager: [email protected])
• Tauri v2 system dependencies for your OS (WebKitGTK, etc. on Linux)

A Nix flake is provided — direnv allow (or nix develop) drops you into a shell with everything installed.

Install with Nix

The flake also builds Quark as a package (Linux and macOS):

nix run github:mcplummet/quark    # try it without installing
nix profile install github:mcplummet/quark

Or consume it declaratively from a NixOS, nix-darwin or home-manager flake:

{
  inputs.quark = {
    url = "github:mcplummet/quark";
    inputs.nixpkgs.follows = "nixpkgs"; # optional, builds against your nixpkgs
  };

  # then either add the package directly…
  environment.systemPackages = [ inputs.quark.packages.${pkgs.system}.default ];

  # …or use the overlay and refer to pkgs.quark
  nixpkgs.overlays = [ inputs.quark.overlays.default ];
}

On macOS the build produces a Quark.app; nix-darwin copies it into /Applications/Nix Apps, and $out/bin/quark launches the same binary from a shell. Both are read-only, so the in-app updater turns itself off — upgrade with nix flake update instead.

Run it

pnpm install

pnpm tauri dev    # full app: Rust backend + frontend, hot-reload
pnpm dev          # frontend only, mock IPC, no Rust process (port 1450)

pnpm build        # tsc + vite build → dist/
pnpm test         # Vitest (single run)
pnpm test:watch   # Vitest (watch mode)
pnpm tauri build  # release bundle (.deb / .AppImage / .rpm / .msi / .dmg / …)

Backend-only work, from src-tauri/:

cargo build
cargo test

Configuration

Config lives in ~/.config/quark/:

config.toml:

[general]
theme = "phosphor"
notifications = true
confirm_redact = true

[sync]
timeline_limit = 50

[media]
auto_load_images = true
cache_size_mb = 500

[gif]
provider = "klipy"   # klipy | giphy
api_key = ""         # bring your own
rating = "pg"        # g | pg | pg-13 | r

quarkrc (keybindings use vimrc syntax; sourced on startup and on :source):

" remap navigation, vim-style
nmap gg  jump-top
nmap G   jump-bottom
nmap dd  redact

" leader bindings (leader defaults to space)
let mapleader = " "
nmap <leader>e  emoji-picker
nmap <leader>g  gif-search

set scrolloff=5
set gif_provider=klipy

Full keybinding command list, scoped maps (tmap/rmap/pmap), autocmd, and the complete theme schema are documented in DESIGN.md.

Keybindings (defaults)

All bindings are rebindable in quarkrc.

Common commands: :join, :leave, :invite, :verify, :theme, :gif, :directory, :roomsettings, :debug, :version.

Themes

Eleven built-in themes ship in themes/:

phosphor (green CRT) · amber (amber CRT) · dracula · nord · solarized-dark · solarized-light · catppuccin-mocha · catppuccin-latte · gruvbox-dark · high-contrast · pesterchum

Switch with :theme <name> or via Settings. (Filesystem hot-reload on save is not yet wired up — switching applies immediately, but editing a theme file currently needs a :theme re-select.)

Project structure

quark/
├── src/                  # TypeScript frontend
│   ├── main.ts           # bootstrap, login, sync startup
│   ├── app/              # actions (IPC dispatch), state, keyboard, sync
│   ├── ipc/              # Tauri invoke wrappers, shared types, mock layer
│   ├── ui/               # DOM components (Timeline, Input, RoomList, pickers…)
│   ├── vim/              # mode state machine, keymaps, : command parser
│   ├── theme/            # CSS custom-property loader
│   └── style/            # monospace terminal base CSS
├── src-tauri/            # Rust backend
│   └── src/
│       ├── lib.rs        # Tauri builder, managed state, plugins
│       ├── commands.rs   # #[tauri::command] IPC handlers
│       ├── matrix/       # client, timeline, rooms, crypto, emoji, media…
│       ├── gif/          # Giphy / Klipy clients
│       ├── config/       # TOML theme + quarkrc parsers
│       ├── media_cache.rs
│       └── notifications.rs
├── themes/               # built-in theme TOMLs
├── flatpak/              # flatpak manifest + desktop/metainfo
├── DESIGN.md             # authoritative spec
└── CLAUDE.md             # architecture notes for contributors

Building & releases

Multi-platform bundles are produced by GitHub Actions on tagged (v*) releases: Linux (.deb / .AppImage / .rpm), Flatpak, Windows (.exe / .msi), macOS (.dmg), and Android (.apk). A Flatpak manifest lives under flatpak/ (app ID tel.quark.app).

Mobile (iOS and Android, via Tauri v2) is experimental and in progress — see the mobile sections of DESIGN.md.

Contributing

• When shipping a feature or fix, bump the version in every file that carries it, together: package.json, src-tauri/Cargo.toml, src-tauri/tauri.conf.json, the version badge in this README, the quark entry in Cargo.lock, the iOS Info.plist, and src-tauri/gen/apple/project.yml (.claude/skills/version-bump/bump.sh does all seven in lockstep). Features bump minor; fixes bump patch.
• Keep DESIGN.md up to date — it's the authoritative spec.
• Run pnpm test and cargo test (from src-tauri/) before opening a pull request.

License

Copyright (C) 2026 mcplummet.

Quark is licensed under the GNU Affero General Public License v3.0. See LICENSE.