Natural-language Gmail filters, running on your Mac.

Replace Gmail's rigid filter language with rules you can actually write — "archive Substack unless a friend wrote it", "file Stripe receipts under Finance and skip the inbox". Evaluated locally by Claude Code. Your email never leaves your machine.

Install in one shell command
curl -fsSL https://gmailaimanager.supar.work/install.sh | bash
Also reachable at https://supar-work.github.io/gmail-ai-manager/install.sh if the custom domain ever has issues.
macOS · Apple Silicon MIT builds from source your data stays local

What happens when you run the installer

  1. Checks your machine. macOS Apple Silicon, Xcode CLI tools, git, Node ≥ 20, pnpm, a Rust toolchain, and the Claude Code CLI. Missing pieces print exact install commands instead of failing silently.
  2. Clones to ~/src/gmail-ai-manager. Full source — audit it, diff it, patch it. Re-run scripts/update.sh anytime to pull changes and rebuild.
  3. Walks you through Google OAuth. Creates your own Google Cloud project with a Desktop-app credential. Nothing is shared between users; your Client ID / Secret live only in ~/Library/Application Support/gmail-ai-manager/api/.env. See the five-minute walkthrough below.
  4. Builds the Tauri bundle. pnpm build for the Node sidecar + React UI, then cargo build --release for the Rust menu-bar shell. Takes ~3–6 minutes the first time; subsequent updates reuse caches.
  5. Installs to ~/Applications. SQLite data lives under Application Support so macOS doesn't prompt for Documents / iCloud access. Logs at ~/Library/Logs/gmail-ai-manager/server.log.

Bring-your-own Google OAuth (5 min)

Gmail's filter/label APIs are "restricted" scopes — shared OAuth clients need to pass Google's CASA security assessment. For a self-hosted local app, the friendlier path is for each user to spin up their own Google Cloud project in "testing mode". The installer opens the right URLs and asks you to paste two strings.

  1. Create a project. console.cloud.google.com/projectcreate → name it gmail-ai-manager, no org, click Create.
  2. Enable the Gmail API. Enable Gmail API in the new project.
  3. Configure the OAuth consent screen. Branding page: App name = "Gmail AI Manager (Local)", audience = External. Add your Gmail address under Audience → Test users.
  4. Create a Desktop-app OAuth client. Credentials page → + Create Client → Application type = "Desktop app". Copy the Client ID + Client secret that appear.
  5. Paste into the installer prompt. The terminal wizard writes the values to ~/Library/Application Support/gmail-ai-manager/api/.env with chmod 600.
  6. First sign-in shows an "unverified app" warning. Expected — testing-mode clients don't carry a verified badge. Click Advanced → Go to Gmail AI Manager (unsafe). You are the app's publisher, so the warning is about yourself.

What it actually does

Natural-language rules

Write rules in English. Each rule compiles to a JSON action list (label, archive, reply, snooze…) via Claude. Trash is never emitted — archive is the strongest action the app allows.

Imports your existing Gmail filters

A per-filter wizard suggests a canonical label, shows sample matched emails, and rewrites your rule text when you change the label. Translate one, a selection, or all at once.

Suggested labels with migration

Claude analyses 8 recent emails per filter and suggests a two-level canonical label (e.g. Family/Basis). Accepting creates the label and moves existing messages via Gmail's batchModify.

Local-first scheduler

SQLite on disk, in-process poller, no cloud. Pause / resume / stop any run from the tray. Every rule-change invalidates only the cache keys it affects.

FAQ / troubleshooting

Why do I need my own Google Cloud project?

Because Gmail's filter and label scopes are restricted. A published app with those scopes must pass Google's CASA security audit (~$500–$10k + a few months). A testing-mode client skips that entirely — you're the only authorized user and Google trusts that you trust yourself. Takes 5 minutes.

Does the app send my email anywhere?

Only to Claude via the claude CLI on your machine. Messages are fetched from Gmail, classified locally, and the result is stored in SQLite at ~/Library/Application Support/gmail-ai-manager/data.db. There's no upstream server you're talking to.

What happens on uninstall?

Quit the menu-bar app, then rm -rf "~/Applications/Gmail AI Manager.app" "~/Library/Application Support/gmail-ai-manager" "~/Library/Logs/gmail-ai-manager". Optionally delete the source checkout at ~/src/gmail-ai-manager and the Google Cloud project.

The installer says "Gatekeeper blocked Gmail AI Manager".

The bundle isn't codesigned (no Apple Developer ID). The installer strips the quarantine bit automatically, but if macOS still complains: xattr -dr com.apple.quarantine "/Users/you/Applications/Gmail AI Manager.app", then right-click the app and choose Open.

claude_exited_1: 401 authentication_error

The sidecar spawned claude -p with stale auth. Run claude login in a fresh Terminal, then quit + relaunch Gmail AI Manager from the tray.

Does it auto-start?

Yes. The installer registers a LaunchAgent at ~/Library/LaunchAgents/work.supar.gam.plist with RunAtLoad=true, so the tray app comes up automatically on every login — no need to touch the Finder icon. If it crashes, launchd restarts it; if you quit it from the tray, it stays quit until next login (or launchctl kickstart gui/$(id -u)/work.supar.gam). Uninstall with scripts/uninstall-launch-agent.sh.

How do I update?

~/src/gmail-ai-manager/scripts/update.sh — pulls main, rebuilds, redeploys, restarts. Preserves your database and .env.

How do I back up my rules / filters?

Run ~/src/gmail-ai-manager/scripts/backup.sh. It writes a timestamped directory under ~/Library/Application Support/gmail-ai-manager/backups/ containing: a full SQLite snapshot (data.db), JSON exports of rules.json + gmail-filters.json, and a human-readable summary. The installer and updater automatically run a backup before making changes. Restore with scripts/restore.sh --full <dir> (replace everything) or --merge <dir> (upsert Rule + GmailFilter rows only).

Intel Mac / Linux / Windows?

Not yet. The first release targets Apple Silicon only to keep the build surface small. Track progress or 👍 the issue tracker.