Gmail Watch
Apps & Automationgmail-watchGmail Watch is an Agent Skill for apps & automation published in the Open-Curiosity/gini-agent repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Open-Curiosity/gini-agent/blob/HEAD/skills/google/gmail-watch/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gmail-watch, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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_authand 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.