Email Sweep
A Claude Code plugin for a daily, compounding Gmail inbox sweep.
/email-sweep runs an end-of-day pass over your Gmail inbox: it auto-labels the obvious threads, batches the ambiguous ones by sender for quick human rulings, and logs every decision to a training log that seeds tomorrow's auto-rules. The system is designed to compound — today's "ambiguous" set shrinks every week as yesterday's rulings become standing rules.
flowchart TB
F["FETCH: today's Gmail unreads"]
C["CLASSIFY: obvious vs ambiguous"]
R["RESOLVE: human rules by sender"]
A["APPLY: labels + archive"]
T["TRAIN: decision log (.jsonl)"]
F ==> C ==> R ==> A ==> T
T -. "tomorrow's obvious set grows" .-> C
Commands
Two slash commands. /email-sweep:sweep drives the daily loop; /email-sweep:init handles lifecycle (setup + cleanup).
| Command | What It Does | When To Run |
|---|
/email-sweep:init | First-run setup — verifies CLI on PATH, Python deps, Claude Code permissions, OAuth credentials + token, syncs the label taxonomy to Gmail, cross-checks CLI ↔ MCP auth (12 gates). Idempotent — safe to re-run. | Once after install, and any time setup drifts (new machine, revoked token, edited taxonomy) |
/email-sweep:sweep | Classify today's unread threads, confirm obvious batch, walk ambiguous by sender, apply labels, log decisions | Daily, end-of-day — ~60 seconds |
/email-sweep:sweep --all | Full inbox sweep (read + unread, any age) instead of today's unreads only | Weekly catch-up, or after skipped days |
/email-sweep:init --remove | Cleanup pass for setup. Removes the user-level shims (CLI symlink, command alias). Leaves OAuth credentials, decisions log, settings.json permissions, and synced Gmail labels untouched (with printed manual-cleanup guidance). | Before /plugin uninstall, or to undo a partial setup |
Quick Start
Before you start: this plugin uses the Claude.ai Gmail connector (the mcp__claude_ai_Gmail__* tools). You need to be signed in to Claude Code with a claude.ai account (Pro/Max/Team) and have the Gmail connector enabled — see Requirements. Raw ANTHROPIC_API_KEY auth won't have these tools.
Claude Code — Marketplace install (recommended)
/plugin marketplace add jasonjgarcia24/email-sweep
/plugin install email-sweep@jason-email-sweep
/reload-plugins
/email-sweep:init
The first two add the marketplace and install the plugin; the third reloads the current session so the new commands are callable without restarting Claude Code; the fourth runs first-run setup (CLI symlink, OAuth credentials + token, label taxonomy sync, permissions check, CLI ↔ MCP account match). /email-sweep:init is idempotent — it detects what's already in place and only fixes what's missing. See the OAuth setup section below for the one-time Google Cloud Console steps init will walk you through.
To pull a newer version later: uninstall first then reinstall (Claude Code's /plugin install skips already-installed plugins, so a vanilla rerun won't pick up upstream changes):
/plugin marketplace update jason-email-sweep
/plugin uninstall email-sweep@jason-email-sweep
/plugin install email-sweep@jason-email-sweep
/reload-plugins
/email-sweep:init
Two ways to invoke the daily sweep. /email-sweep:sweep is the plugin-namespaced form (always available after install — Claude Code namespaces plugin commands as <plugin-name>:<command-name> to avoid collisions). /email-sweep is the short form — during /email-sweep:init, a user-level symlink is installed at ~/.claude/commands/email-sweep.md → the plugin's commands/sweep.md, so both resolve to the same file with no drift. (Init itself stays namespaced — /email-sweep:init only — because Claude Code has a built-in /init command for CLAUDE.md initialization that the short form would collide with.)
SSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or switch to HTTPS for fetches only:
git config --global url."https://github.com/".insteadOf "[email protected]:"
Uninstall
Three steps. The first cleans up the user-level shims init created; the next two remove the plugin and marketplace.
/email-sweep:init --remove
/plugin uninstall email-sweep@jason-email-sweep
/plugin marketplace remove jason-email-sweep
--remove removes (only if they exist and point at email-sweep paths):
~/.local/bin/gmail-labels symlink (the CLI on PATH)~/.claude/commands/email-sweep.md symlink (the short-form /email-sweep alias)
--remove does NOT touch (manage these yourself if you want full cleanup):
jasonjgarcia24
