morning-brief

Rule-based daily Gmail inbox triage. Zero LLM, read-only, Windows-friendly.

Classifies recent mail into HIGH / MEDIUM / LOW / SPAM from a YAML rules file, writes a markdown digest, and pops a desktop toast. Scan your inbox in thirty seconds instead of thirty minutes.

Why not an LLM-based tool

Paid-LLM triage tools like mailtrim and gmail-digest work, but cost money per run and fail silently when the API is down. For a personal inbox, most of the signal lives in sender domain plus a handful of subject keywords. Rules handle that case reliably and for free.

Install

pip install morning-brief

Windows users also want the toast helper:

pip install "morning-brief[windows]"

One-time setup

1. Create a Google Cloud project, enable the Gmail API, create an OAuth 2.0 Client ID of type Desktop app, and download the JSON as credentials.json.
2. Run morning-brief init to scaffold ~/.morning-brief/.
3. Drop credentials.json into ~/.morning-brief/.
4. Edit ~/.morning-brief/rules.yaml to match your senders.
5. Run morning-brief run. First run opens your browser for read-only consent and writes token.json locally.

Sub-day windows

morning-brief run --hours 4    # last four hours instead of last day
morning-brief run --hours 1    # quick post-lunch sweep

--hours overrides the default --days 1. Maps directly to Gmail's newer_than:Nh query.

Thread collapse

Conversations that fan out across many messages collapse to one digest entry annotated with (N msgs). On by default; pass --no-collapse-threads to keep the v0.2.0 one-line-per-message behaviour.

Debug your rules

morning-brief preview --sender "hr@canonical.com" --subject "Interview Tuesday"
# Bucket: HIGH
# Reason: high_sender:@canonical.com

morning-brief why <message-id>
# From:    notifications@github.com
# Subject: Review requested on PR #42
# Stored:  HIGH
# Now:     HIGH
# Reason:  high_keyword:review requested

preview answers "what would happen if I added this rule?" without calling Gmail. why looks up a stored message and shows whether your current rules.yaml would still classify it the same way.

Daily run

Windows Task Scheduler, WSL cron, or macOS launchd can each fire the command once a day at 8am.

Windows Task Scheduler: create a basic task triggered daily at 08:00 running morning-brief run.

WSL cron:

0 8 * * * /home/you/.local/bin/morning-brief run >> /tmp/morning-brief.log 2>&1

For toast notifications from WSL cron, install wsl-notify-send; morning-brief will pick it up automatically.

Rules

rules.yaml uses case-insensitive substring matching. The starter generated by morning-brief init covers GitHub notifications, common spam patterns, and a placeholder high-priority sender list.

Classification precedence: spam wins first, then high, then github-low, then medium (default).

Scope

• Read-only Gmail access. The tool never marks, labels, moves, or deletes mail.
• Writes digests to ~/.morning-brief/digests/YYYY-MM-DD.md.
• Tracks processed message IDs locally for 7 days so reruns are idempotent.

Status

Alpha. Classifier is covered by unit tests; integration tests for the Gmail client come next.

License

MIT.