| name | gmail-watch |
| description | Detection engine for Gmail email watches: iterates the watch list, polls gws for new matching mail per watch, dedups, drops automated/self, and hands matches (labeled by sender) to the shared drafting turn. Provisioned and run automatically by the shared email-watch backing job. |
| license | MIT |
| compatibility | macOS and Linux. Requires the `gws` CLI authenticated against a Google account with Gmail scopes. |
| metadata | {"gini":{"version":"1.0.0","author":"Gini","platforms":["macos","linux"],"prerequisites":{"commands":["gws"]}}} |
Gmail Watch
This skill ships the detection engine behind your email watches. It is not
something you run by hand — when you create an email watch (email_watch tool,
gini email add, or the settings UI), Gini adds it to ONE shared background job
whose pre-run hook runs this skill's detect script on a schedule. All of your
watches share that one job and one "Email watch" chat thread; the script decides
which watches have new mail to draft a reply to.
What it does
Each time the shared watch job fires, detect runs headless (no model turn,
no approval) and, for EACH of your watches:
- Checks the Google sign-in (once for the session). If signed out, every watch
reports
needs_auth and nothing is drafted — the watches stay active and
recover the moment you re-authenticate.
- Lists new mail matching that watch's query via
gws, bounded by a per-watch
watermark so steady-state polling lists almost nothing.
- Drops automated senders (no-reply, mailer-daemon, notifications, …) and your
own address — only real, human, new mail survives.
- Hands each surviving match (its sender / Subject / Date / snippet only — never
the body), labeled by sender, to the drafting turn as quoted, untrusted data.
Each watch is independent: one sender's transient error marks only that watch and
the others keep working. When nothing new matches across all your watches, the
run ends with no model turn at all — the watches are silent until there is
something to act on.
How a match becomes a reply
The detection floor reads only metadata. One drafting turn then handles all the
matches for that tick in the shared thread: it reads each full message and
composes a reply per email — each labeled by sender — through the google-gmail
skill, posts the proposed replies for you to review, and sends only when you
explicitly ask (which runs gws gmail +reply through the normal approval gate).
Stateful but pure
detect is a pure function of your watch list and the small per-watch cursors it
is handed each run; it never writes to disk itself. Gini stores those cursors on
the shared watch job and advances each only after a drafting turn is dispatched,
so a match is never silently lost if delivery fails — it re-surfaces on the next
run.
First run baselines
The first time each watch runs it records where your inbox currently is and
drafts nothing for pre-existing mail — only mail that arrives after the watch
was created triggers a reply. A newly added watch baselines on its own first tick,
independently of your existing watches.
