- TypeScript 78.7%
- Kotlin 16%
- CSS 4.1%
- JavaScript 0.5%
- Nix 0.4%
- Other 0.2%
Mail scored between SPAM_REVIEW and SPAM_CERTAIN was hidden from Mail's inbox while it stayed unread in the server's, where nothing filed it and the provider's filter learnt nothing. The engine now makes a "Likely spam" folder (role likely-spam) and moves such mail there; Spam files it in Spam, Not spam moves it back. What the score was already holding moves in once, when the folder is made. Android learns the new role. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| .impeccable | ||
| android | ||
| docs | ||
| packages | ||
| scripts | ||
| .dockerignore | ||
| .envrc | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| package-lock.json | ||
| package.json | ||
| process.md | ||
| README.md | ||
| shell.nix | ||
| tsconfig.base.json | ||
A mail client for Linux, the web and Android, built in the visual language of the notes app — three panes, date-grouped list, serif reading body, mono metadata, tabs for open threads, a vim status bar, and a lot of themes.
One mail server holds the mail and every client is a window onto it: the accounts and their IMAP connections, the store, the settings, label colours, filter rules, PGP keys and themes. The server runs in a container and serves the web app itself; the desktop pairs with it.
That reverses how this started. Until 2026-11 it was not a service — no
container, no server, no port; an application that owned its own process
and its own IMAP connections. That was right for one computer and wrong for
a phone: two engines would dial the same account, an account added on one
device would not exist on the other, and the things IMAP cannot carry
(label colours, filter rules, the spam model, scheduled mail) would differ
between them. docs/SERVER-PLAN.md is the plan and the reasons; the
desktop still runs on its own when it is not paired, until that is removed.
Running the server
docker compose up -d --build
docs/DEPLOY.md has the rest: the settings it keeps on its volume, claiming
it, pairing clients and moving a desktop's mail in. From a checkout, npm run build and then npm run serve (docs/RUNNING.md). Either way it serves the
web app at its address.
Running the desktop
npm install
npm run build
npm start
On NixOS, run nix-shell first: Electron's downloaded binary cannot start
without a global /usr/lib, and shell.nix points it at the nixpkgs build
instead. docs/RUNNING.md has the detail.
For UI work, the window runs in a browser against Vite, which is faster than rebuilding Electron for a CSS change:
npm run dev # then open http://localhost:5273
Settings → Devices connects it to a server, with a pairing code from the
web app's own Settings → Devices. Unpaired, add an account in Settings →
Accounts. Gmail and Outlook need a browser sign-in rather than a password,
and docs/ACCOUNTS.md has the one-time client setup that requires.
Everything renders with the design's own fixture mail until an account is
configured, so there is something real to look at from the first run. In a
Vite tab with no server behind it there is no IPC bridge and no API, so the
window uses the fixtures — which is what makes it possible to work on the
shell without a mailbox. docs/RUNNING.md has the variant with a server
behind it.
Where things are
packages/shared |
Types, the theme system and its 57 palettes, settings, the mail domain |
packages/core |
The engine: accounts, IMAP/SMTP, the local store, sync, search (docs/ENGINE.md) |
packages/client |
The window — the shell, reader, composer and settings panes |
packages/desktop |
The Electron shell: window, menu, keyring, XDG paths, pairing |
packages/server |
The mail server: the engine over HTTP, sign-in and devices, the web app |
android/ |
Kotlin and Compose, a client of the server (docs/ANDROID.md) |
docs/RUNNING.md has the rest of the launch detail — the dev-server
workflow, where the application writes, and what to check when something
looks wrong. docs/DESIGN.md is the record of what the design specifies and
what was decided on top of it. docs/ARCHITECTURE.md is how the pieces fit,
docs/ENGINE.md covers the mail engine and docs/ACCOUNTS.md covers signing
in — including the one-time OAuth setup Gmail and Outlook need.
docs/PLUGINS.md is the scope agreed for plugins. docs/DEPLOY.md is the
container.
Configuration
On the server, everything is on its data volume — settings.json,
themes/, plugins/, mail.db and the encrypted vaults
(docs/RUNNING.md lists it). An unpaired desktop keeps the same things
under XDG, as files you can edit:
~/.config/mail/settings.json every setting in the Appearance pane
~/.config/mail/themes/*.toml drop a theme in; it appears in the picker
~/.local/share/mail/ accounts, keyring references, the message store
~/.local/share/mail/mail.db mail, unsent drafts and the pending queue
A theme is three colours and a name; everything else is derived from them, so a whole theme fits on a postcard:
name = "Harbour"
[palette]
bg = "#0f1419"
fg = "#e6e1cf"
acc = "#39bae6"
Appearance → Import theme takes one of those or a base16 .yaml and
copies it in; Edit current opens the file for whichever theme is showing,
writing one out first if it is a built-in. Both are read again whenever the
pane is opened, so editing a file and coming back is enough — there is
nothing to restart.
Tests
npm test
1,148 tests across the five packages (2026-11-10), no browser and no network.
The colour maths and theme derivation, the keymap, the stylesheet's
invariants, the whole engine — threading, MIME mapping, the search language,
the sync planner, composing and the outbox — and the server's sign-in,
devices, routes and import all run under node --test.
The two files that open a socket (ImapFlowConnection,
NodemailerTransport) are thin adapters with no decisions in them, and the
sync is tested against a fake server. docs/ENGINE.md says why that boundary
is where it is.