A read-only Gmail reader that sorts your mail with a small model on your own machine. No mail leaves the machine for triage.
LocalMail is a fork of JevMail by fazlerocks. JevMail sends each message to a hosted model; LocalMail replaces that with a local one.
- Sorts mail into Needs reply, Updates, Promos, Sales and Spam, with reply urgency and a personal-mail flag.
- An urgent strip for mail that needs action today. Only senders you have written to can mark mail urgent.
- Read-only: the only Gmail scope is
gmail.readonly. Nothing is sent, archived, labelled or marked read. Done marks and corrections stay in a local SQLite file. - Runs on CPU with ONNX Runtime. No GPU, no model server, no hosted fallback.
- Optional, also local: summaries and questions with a small language model, and search by meaning with an embedding model.
Sorting uses wildroot-mail-v1: two bge-small-en-v1.5 models (33M parameters each) fine-tuned for mail triage and exported to float32 ONNX. One answers lane, reply urgency and personal; the other scores whether a message needs action today. Rules the model cannot override sit on top: for example, a sender you have never written to cannot raise urgency above 3. The Wildroot browser uses the same model.
| Measure | LocalMail | Jev 1.14 (hosted) |
|---|---|---|
| Lane accuracy, 5 lanes | 90.2% | 92.4% |
| Needs reply precision | 87.8% | 84.8% |
| Needs reply recall | 90.8% | 98.3% |
| Reply urgency, exact | 84.4% | 83.9% |
| Personal mail | 96.7% | 95.2% |
| Needs action today, AUC | 0.965 | 0.993 |
546 held-out public emails, enriched for mail that needs a reply or action, so these are not figures for a typical inbox. Jev is the hosted model JevMail uses. Method and limits: docs/BENCHMARK.md.
Each model takes about 40 ms per email on 4 CPU threads. Both together use about 460 MiB of memory and 266 MB of disk.
Requires Node.js 22, pnpm 10 and Python 3.12.
git clone https://github.com/wildroot-io/localmail
cd localmail
pnpm install --frozen-lockfile
python3 -m venv .venv
.venv/bin/pip install -r requirements-student.txt
for f in student.onnx action.onnx tokenizer.json vocab.txt; do
curl -L -o "models/student-v1/$f" "https://huggingface.co/bpmatt/wildroot-mail-v1/resolve/main/$f"
done
cp .env.example .env.local # then set the Google values below
pnpm build
PYTHON=.venv/bin/python bin/start-local.shOpen http://localhost:3000. bin/start-local.sh starts the mail service and the app on loopback; Ctrl-C
stops both. The service checks each model file against the hash in models/student-v1/config.json.
- In Google Cloud Console, create a project and enable the Gmail API.
- Configure the OAuth consent screen as External, in Testing, and add your Gmail address as a test user.
- Create an OAuth client of type Web application with the redirect URI
http://localhost:3000/api/auth/callback/google. - In
.env.local, setAUTH_GOOGLE_ID,AUTH_GOOGLE_SECRET,MAILBOX_OWNER_EMAIL(the one account this installation serves) andAUTH_SECRET(for exampleopenssl rand -base64 32).
In Testing mode Google expires refresh tokens after 7 days, so expect to sign in again weekly.
.env.example lists the app's settings. THREADS, MAIL_PORT, WORKSPACE and PYTHON are shell
variables read by bin/start-local.sh; THREADS defaults to half the logical CPUs.
| Variable | Default | |
|---|---|---|
SYNC_LIMIT |
20 | Newest messages fetched on first sync, and the cap per later sync |
FETCH_MORE_LIMIT |
100 | Older messages per Fetch more |
GMAIL_RATE_PER_MIN |
100 | Gmail fetch pace |
MAX_BODY_CHARS |
2000 | Characters of each body the model reads |
AUTO_SORT |
1 | 0 waits for the Start sorting button |
New mail is fetched every five minutes while the page is open. Each new sender costs one read-only Gmail search, to check whether you have written to them.
A correction applies to that message at once and is kept locally. It does not retrain the model.
- Gmail sign-in and sync have not yet been run end to end against a real mailbox. All tests use a fake Gmail client.
- Training and test mail is mostly from 2000 to 2002. Modern newsletters, receipts and automated alerts are lightly covered. English only; text past 256 tokens is ignored.
- About 1 in 11 messages that needed a reply was missed in testing. Lanes are suggestions: check All.
pnpm dev # app only; /preview runs a simulator with no credentials
pnpm test && pnpm lint && pnpm exec tsc --noEmit
pnpm build --webpack # production build; the default pnpm build uses Turbopack
python3 -m unittest discover -s decision_engine -t . -p 'test_*.py'
python3 -m unittest assistant_runtime.test_serverpnpm sort:reset clears sorting and corrections and keeps messages. pnpm db:reset deletes the local
database. Keep data/ out of any repository: it holds your mail.
MIT. See LICENSE, which keeps the copyright notice of the original JevMail project. The sorting model is MIT. The search model, EmbeddingGemma 2, is Apache-2.0. The assistant model is your choice; its licence is on its model card.
- JevMail by Fazle Rahman, the app this fork is built on.
- BAAI/bge-small-en-v1.5, the base model.
- The Enron, SpamAssassin and phishing_pot email corpora, and public mailing-list archives.