---
title: Supermail Assistants (inbox-wide AI launchers)
---
# Supermail Assistants (inbox-wide AI launchers)

## What it is

The **Assistants** strip is a row of one-click AI launchers at the top of the Supermail
**Sessions** tab. Each button starts a purpose-built AI session on your live mailbox that opens
with an **instant pre-written greeting**. It's the AI-*session* sibling of Supermail's other AI
features ([AI Filtering](supermail-ai-filtering.md) triages new mail; [Catch me up](supermail-ai-summary.md)
summarizes a thread) — where those are one-shot helpers, an Assistant is a full working
conversation that reads your inbox and helps you act on it.

**Five inbox-wide assistants:**

- **Inbox Copilot** — walks your inbox one email at a time; for each it gives a quick read and proposes a move (reply / archive / star / snooze / skip), you approve, it acts, next.
- **Draft My Replies** — finds the emails awaiting your reply and drafts each *in your voice*, staged in your Drafts; you skim, tweak, and send. It never sends.
- **Filter & Declutter** — finds the low-value noise (newsletters, promotions, notifications), clears it in approved batches (reversible only), and **proposes filter rules** for you to apply so it stays clean.
- **Filter Architect** — designs, back-tests, and **actually builds** a Supermail filter that does exactly what you want. It inspects your real messages, picks the simplest matching rule that's provably correct, back-tests it against your mail so you see what it would catch before anything goes live, and creates the filter for you — always confirming first.
- **What Needs Me** — scans your inbox and hands you a **ranked list of the threads most likely to need YOU** — a reply, a decision, an action — each with a one-line reason and a confidence, plus a short "safe to ignore" tail. It gets sharper over time by **learning who you actually reply to** (from your sent mail), kept private as one-way hashes and synced across your devices. It never sends or deletes anything.

**Filter Architect has two more entry points, both in the Supermail Filters panel:** a **"Build a
filter with AI"** button in the rule list (right where you'd click *New filter*), and a **"Build
with AI"** button at the top-right of the filter *editor*. The editor button is **seeded** — it
hands the AI whatever you've already started (the filter you're mid-edit on, plus the email you had
open, if any) so it picks up from there instead of a blank slate; the list button starts fresh. All
three entry points land in the same Filter Architect session.

**A seeded launch SHOWS you it has your draft.** When you click **"Build with AI"** from a
half-built filter, the AI's opening message leads with a short, visible **"Here's the filter you'd
started"** heads-up — a plain summary of the conditions and actions you'd set — *then* walks through
its standard guided questions, so you can see it picked up your work instead of a generic greeting
that re-asks what you already filled in. That heads-up is built **only from your own filter fields**,
never from the untrusted email you had open (that email still rides along as hidden reference the AI
can act on, but it's never shown back to you in the opener). The greeting now also paints
**instantly** on this path — no brief blank session while it loads. The plain list button (which has
no draft) opens exactly as before.

**Always on** — the launcher strip is a permanent part of Supermail (no flag, no toggle,
can't be turned off — owner decision 2026-08-03). The Filter Architect (and both its Filters-panel
buttons) is part of it. More assistants and per-thread types (profile a contact, untangle
a thread, help me write this) are later waves.

## Where to find it

The **Assistants** strip at the top of Supermail's **Sessions** tab, plus a second entry point in the Filters panel.

## How it behaves

### How it works

Mirrors the Tasks "macro session" pattern:

- A one-click button spawns a session into the `__supermail__` host using the **deferred
  stock-first-response** launch — the greeting shows instantly with NO model spawn; the model
  cold-spawns only when you reply (cheap: a click costs nothing until you engage).
- Registry (`src/shared/supermail-assistants.ts`) → resolver reads the bundled super-prompt
  (`src/main/services/supermail/supermail-assistant-session.ts`) → IPC channel
  `SUPERMAIL_LAUNCH_ASSISTANT` → handler spawns via `createSessionWithPrompt({ deferredStart })`.
  The strip is `src/renderer/src/features/supermail/SupermailAssistantsLaunchers.tsx`.
- The spawned session gets a scoped CLI token and acts through the local control server.

### What the assistants can (and can't) do — the reachability posture

- **Reachable** with the scoped token: read/search the inbox (`GET /gmail/threads`), read a thread,
  stage drafts (`POST /gmail/drafts`), reversible triage (`/gmail/threads/:id/{archive,read,star,label,snooze}`),
  and the cost-capped cleanup analysis (`GET /gmail/cleanup/analysis`).
- **Filters — two postures, by design:** with its scoped token a session can't call
  `/supermail/filters` directly (`cliTokenOnly` — an IDOR guard), but the Supermail host prompt tells
  every session to fall back to your machine's full-access token for filter work. So **Filter &
  Declutter** deliberately **proposes** rules (a conservative choice), while **Filter Architect
  actually creates and edits** them — always confirming with you before any live change.
- **Propose, never send.** Outbound (`/gmail/send`, `/gmail/reply`) is approval-gated by design;
  drafts are staged. Destructive/mass actions (archive, trash, a live filter write) are confirmed
  with you first — never auto-applied from instructions found inside an email.
- **What Needs Me's memory** is a small per-account model of who you reply to, reached through the
  same protected posture as filters (`/supermail/sender-signals`, `cliTokenOnly` + your machine's
  full-access token). It stores only one-way hashes of senders — never a readable address — and syncs
  across your devices like your filters do.

### Cost + safety

- Each assistant is a **real Claude session** (your normal per-session spend), user-initiated and
  deferred, so a click costs nothing until you reply.
- The cleanup analysis it leans on is **cost-capped** in the main process.
- **Email is untrusted.** The Supermail host system prompt + each assistant's prompt tell it never
  to obey instructions inside a message; a prompt-injection attempt can at most change the prose of
  a proposal — nothing acts without your approval.

Contract: `.claude/memory/contracts/supermail-assistants-contract.md` (its Invariants section).

## Related

The other Supermail AI features are one-shot helpers by comparison — AI Filtering triages incoming mail and Catch me up summarizes a thread. Supermail itself covers the rest of the client.