Flagged

Open-source important-email highlighter. Keep using Gmail and surface emails that are too important to miss with frontier or open-source models.

---

"I was paying for Superhuman mostly because it highlighted the important emails I could not afford to miss. Flagged is the open-source version of that one job." — @msanchezworld

---

What It Does

Flagged monitors your Gmail accounts every few minutes, classifies unread email using a frontier or open-source model you choose, and highlights the messages that are actually worth your attention.

• Important Email Highlighter - immediate alerts for real people, customers, friends, partners, paid work, school/family logistics, and direct asks worth deciding on
• Money/Admin - digest by default for bills, receipts, refunds, affiliate payouts, and account notices
• Learning/Events - digest by default for newsletters, webinars, launches, and event blasts
• Sales Pitches / Muted - suppressed by default

You keep your current inbox. You respond in Gmail. Flagged just makes sure the important stuff does not get buried.

🔴 URGENT — Important Email (Main Inbox)

💬 CUSTOMER
From: Jane Founder <jane@example.com>
Subject: Question about working with Mass Ideation
Score: 9/10 — Direct customer inquiry with a specific ask

"Hey Miguel, I saw your AI workflow work and wanted to ask..."

---

Why Flagged?

Most AI email products want to become your whole inbox. Flagged is intentionally narrower: it replaces the one Superhuman-style job many people actually need, highlighting the emails they cannot afford to miss.

Feature	Flagged	Email rules/Zapier	SaaS AI inboxes
Frontier or open-source model choice	✅	Limited	Limited
No subscription fee	✅	❌	❌
Tunable importance rules	✅	Limited	Limited
Works across multiple inboxes	✅	Paid tier	Paid tier
Highlights, not a new email client	✅	Partial	❌
No vendor lock-in	✅	Limited	❌

---

Privacy Model

Flagged is model-flexible by design:

• Local/open-source by default. LM Studio lets Qwen, Phi, Llama, Gemma, and similar models run entirely on your hardware.
• Frontier-capable when you choose it. Point Flagged at an OpenAI-compatible endpoint or proxy if you want a hosted frontier model.
• Minimal payload. Flagged sends only sender name, subject line, attachment flag, and a 400-character preview snippet to the configured model provider. It never sends the full email body.
• Gmail OAuth is read-only. Flagged cannot send, delete, or modify emails. It can only read.
• You control the tradeoff. Use local models for maximum privacy, or frontier models when accuracy matters more than keeping classification fully local.

---

Requirements

• Mac, Linux, or Windows with Python 3.9+
• A model endpoint — LM Studio for local open-source models, or any OpenAI-compatible endpoint/proxy for frontier models
• Gmail account(s) — up to as many as you want
• Telegram bot for v1 alerts — takes 2 minutes to create via @BotFather
• Google Cloud project (free) for Gmail API access

---

Install

Mac / Linux — one line:

curl -fsSL https://raw.githubusercontent.com/Massideation/flagged/main/install.sh | bash

Windows — one line (PowerShell):

irm https://raw.githubusercontent.com/Massideation/flagged/main/install.ps1 | iex

The installer clones the repo, installs dependencies, and launches an interactive setup wizard that walks you through every step — Telegram bot, Gmail API, model selection, and background service — no manual config editing required.

Manual install:

git clone https://github.com/Massideation/flagged
cd flagged
pip install -r requirements.txt
python setup_wizard.py

Full walkthrough → SETUP.md

---

OpenClaw

Flagged can run beside a local OpenClaw setup today: Gmail is read through the Gmail API, classification happens through your configured model provider, and v1 alerts go to Telegram where OpenClaw can help with follow-up actions you explicitly ask for.

Telegram is the first delivery channel, not the product boundary. Slack, Discord, webhooks, and other alert targets are natural next integrations.

It is not yet packaged as an OpenClaw plugin. See docs/OPENCLAW.md for the current integration path and plugin roadmap.

For the product direction and next engineering steps, see docs/OPPORTUNITY_RADAR.md.

---

Model Options

Flagged works with OpenAI-compatible chat-completions endpoints. You can use local open-source models through LM Studio, or a frontier model through a compatible provider/proxy.

For email classification, smaller local models are often enough — you want fast and accurate, not large and slow.

Model	RAM	Speed	Notes
Qwen2.5 3B Instruct ⭐	~2GB	⚡⚡⚡	Default — best-in-class for classification at this size
Qwen3 4B Instruct	~3GB	⚡⚡⚡	Slightly more capable, still very fast
Phi-3.5 Mini	~2.5GB	⚡⚡⚡	Excellent reasoning, great JSON output
Llama 3.2 3B Instruct	~2GB	⚡⚡⚡	Reliable fallback, strong instruction following
SmolLM3 3B	~2GB	⚡⚡⚡	Newest option, outperforms Llama 3.2 3B on benchmarks
GLM-4.7 / LFM	~5-8GB	⚡	Works, but overkill — wastes RAM you need for other work

On a 16GB machine: use Qwen2.5 3B locally. It uses ~2GB RAM, classifies emails in under a second, and leaves your machine free for everything else.

For frontier models: configure model_provider.url, model_provider.model, and optionally model_provider.api_key_env in config.json. Remember that sender, subject, attachment flag, and the preview snippet will be sent to that provider.

---

Tuning Flagged to Your World

The PRIORITIES.md file is Flagged's brain. It tells the AI model who you are, what counts as important in your world, and what should wake you up vs. what should stay quiet.

The alert_channels section in config.json controls what happens after classification:

{
  "alert_channels": {
    "opportunities": { "mode": "immediate", "min_score": 7 },
    "money_admin": { "mode": "digest", "min_score": 9 },
    "learning_events": { "mode": "digest", "min_score": 8 },
    "sales_pitches": { "mode": "mute", "min_score": 10 }
  }
}

Supported modes:

• immediate sends an alert now (Telegram in v1)
• digest records/logs the item for later batching
• mute suppresses the item

You can inspect or change this from the terminal:

python flagged.py scope show
python flagged.py scope set money_admin --mode digest --min-score 9
python flagged.py scope set learning_events --mode mute

Edit it to match your life:

## Raise to 9-10 (Drop everything)
- Event invites with RSVP deadlines
- Direct outreach from [your key contacts/orgs]
- Speaking or podcast requests
- Term sheets or partnership proposals

## Keep at 1-4 (Do not alert)
- Marketing newsletters
- Automated platform notifications
- Bills, receipts, refunds, Uber/travel receipts
- Cold sales outreach and generic event blasts

Changes apply on the next poll — no restart needed.

---

Running as a Background Service

macOS (always-on, survives reboots):

cp com.flagged.emailmonitor.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.flagged.emailmonitor.plist

Linux (systemd):

# See SETUP.md for systemd service setup

Windows (Task Scheduler):

# See SETUP.md for Windows setup

---

Multiple Inboxes

Flagged supports unlimited Gmail accounts. Add as many as you want in config.json:

"accounts": [
  { "label": "Personal", "credentials_path": "credentials.json", "token_path": "token_personal.pkl" },
  { "label": "Work",     "credentials_path": "credentials.json", "token_path": "token_work.pkl" },
  { "label": "Projects", "credentials_path": "credentials.json", "token_path": "token_projects.pkl" }
]

One credentials.json works for all accounts. Each account gets its own token file after a one-time browser authorization.

---

V1 Telegram Alert Format

🔴 URGENT — Important Email (Personal)

🤝 PARTNERSHIP
From: founder@coolproject.xyz
Subject: Collab idea — would love to chat
Gist: A founder appears to be asking for a specific collaboration conversation. This may be an opportunity because it is direct personal outreach with a concrete next step.
Score: 8/10 — Direct personal outreach, specific ask, no template language
Sender: person / prospect
Ask: needs_reply
Why flagged: Founder appears to be reaching out directly with a collaboration ask.
Noise check: Not a newsletter, bill, receipt, or sales pitch; no list/unsubscribe language.

"Hey, I've been following your work and wanted to..."

[Good] [Bad]
[Mute type] [Digest only]

After you tap a feedback button, Flagged asks for an optional short reason. Those examples are saved locally and included in future classification prompts so the system learns what you consider a real opportunity, a bad alert, or digest-only noise.

Emoji legend:

• 🔴 9-10 Urgent
• 🟠 7-8 Priority
• 🟡 5-6 Worth reviewing (if you lower your threshold)

---

Contributing

Pull requests welcome. See CONTRIBUTING.md.

Ideas for contributions:

• Outlook / Microsoft 365 support — big one
• Slack / Discord / webhook notification support (alongside Telegram v1)
• Web dashboard for viewing scored email history
• Better importance presets for founders, families, freelancers, and small teams
• Webhook support for custom integrations
• Linux systemd service template
• Docker container
• Support for more email providers (Fastmail, ProtonMail bridge)

---

Built By

Flagged was built by Miguel Sanchez — building at the intersection of AI, crypto, and media.

• 🐦 Twitter: @msanchezworld
• 💻 GitHub: MSanchezWorld
• 📺 YouTube: MiguelSanchezWorld

---

License

MIT — use it, fork it, build on it. See LICENSE.