fast-classifier

Deterministic, rule-first email classifier for Fastmail: sweep newsletters, file everything, flag what needs action — dry-run first, never deletes.

Quickstart GitHub

Built for— independent open-source project, not affiliated with Fastmail

6,551emails scanned

3,849newsletters swept

5,573filed into 14 labels

87%rule coverage

fast-classifier — the canonical loop

$ fast-classifier analyze
recon: 6,551 emails · 214 senders · report written
$ fast-classifier plan
# DRY RUN — no changes will be made
plan: sweep 3,849 newsletters · file 5,573 into 14 labels
$ fast-classifier sweep --execute
OK  swept 3,849 newsletters — 0 deleted (never deletes)
$ fast-classifier file --execute
$ fast-classifier needs-action
$ fast-classifier verify

The 20-second demo

Born from a real inbox

fast-classifier was born from a live session that organized a real 6,551-email inbox: 3,849 newsletters swept in one run, 5,573 emails filed into 14 labels, and 87% rule coverage reached by iterating recon reports instead of training anything. The one-off scripts from that session are preserved read-only in reference/; this project is those scripts hardened into a typed, tested library with a CLI and an MCP server. Every core concept shipped from that session.

CLI

The canonical loop: analyze → plan → iterate rules → sweep --execute → file --execute → needs-action → verify. Every mutating command is dry-run until you pass --execute. CLI reference →

Library

A typed, tested TypeScript library: pure rule engine, pipelines, and pluggable JMAP/MCP transports behind one MailProvider interface — with an in-memory provider for tests. API reference →

MCP server

fast-classifier-mcp exposes 10 tools over stdio for agents, with writes gated behind --allow-execute and forced dry-runs marked forcedDryRun: true. MCP server guide →