Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot official · Google

gws-gmail-watch — Claude Code skill: Gmail and setup

Watches Gmail for new emails and streams events as NDJSON. Use it when an agent needs incoming mail as a live input.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add googleworkspace/cli --skill gws-gmail-watch -a claude-code
Open on GitHub

What gws-gmail-watch does

gws-gmail-watch runs gws gmail +watch and watches for new Gmail messages. Events are streamed as NDJSON, with filtering by Gmail label IDs such as INBOX or UNREAD. Each message can use the full, metadata, minimal, or raw format.

The skill can create Pub/Sub resources from a GCP project or use an existing subscription and topic. --once pulls one batch and exits, while --output-dir writes each message to its own JSON file. The default batch limit is 10 messages, and the default pull interval is 5 seconds.

You need gws, authentication, and the rules from gws-shared. Gmail watch expires after 7 days, so run it again to renew the watch. Install this skill when an agent needs a stream of new email; use gws-gmail commands for one-off mailbox operations.

What it helps with

  • watch for new Gmail messages
  • filter incoming mail by Gmail label IDs
  • stream email events as NDJSON
  • write each message to a separate JSON file
  • pull one batch and exit

Example prompts for the agent

  • Run `gws gmail +watch --project my-gcp-project` and pass new email events to the agent as NDJSON.
  • Watch only inbox messages with `gws gmail +watch --project my-project --label-ids INBOX --once`.
  • Run `gws gmail +watch --project my-project --cleanup --output-dir ./emails` and save messages in `./emails`.

How to install gws-gmail-watch

1Skills CLI (Vercel)

npx skills add googleworkspace/cli --skill gws-gmail-watch -a claude-code

2Manually: put the files in place

~/.claude/skills/gws-gmail-watch/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gws-gmail-watch/

From the same set95

The whole set →
gws-gmail official googleworkspace This skill hands your agent Gmail: send mail, read the inbox, reply in a thread. Useful when email work already runs through the gws CLI. Claude Code CX Codex Cursor +1 81,900installs gws-gmail-send official googleworkspace A skill that teaches your agent to send Gmail from the terminal: recipients, subject, body, attachments and drafts. Claude Code CX Codex Cursor +1 74,700installs gws-drive official googleworkspace This skill hands your agent Google Drive through the gws CLI: files, folders, shared drives, comments and access requests. Useful when docs move through code. Claude Code CX Codex Cursor +1 74,500installs gws-shared official googleworkspace This skill gives agents shared rules for gws CLI authentication, flags, and output formats. Use it when working with gws commands. Claude Code CX Codex Cursor +1 66,000installs gws-calendar official googleworkspace Manage Google Calendar events, access rules, and schedules through the gws CLI tool. Claude Code CX Codex Cursor +1 61,100installs gws-sheets official googleworkspace This skill lets an agent read and edit Google Sheets through the CLI. Use it when a coding workflow needs spreadsheet data or table updates. Claude Code CX Codex Cursor +1 58,800installs gws-docs official googleworkspace This skill lets an agent read and update Google Docs through gws. Use it when document changes should happen from an agent chat. Claude Code CX Codex Cursor +1 58,300installs gws-sheets-read official googleworkspace Reads cell values and sheets from Google Spreadsheets via CLI. Useful when an agent needs spreadsheet data without risk of altering it. Claude Code CX Codex Cursor +1 50,600installs

Similar

observability-and-instrumentation addyosmani Instruments code with structured logs, RED and USE metrics, and distributed tracing. Use it when shipping features to production so issues are diagnosable. Claude Code CX Codex Cursor +1 54,200installs mcp-builder official anthropics This skill walks through building an MCP server in TypeScript or Python, from reading the protocol spec to writing tests and evaluation questions. Claude Code Claude.ai 130,949installs google-agents-cli-adk-code official Google A reference skill for building ADK agents with tools, callbacks, state, and workflows. Use it when an agent project needs concrete API patterns or code examples. Claude Code CX Codex Cursor +1 511,400installs lark-im larksuite This skill lets an agent work with Lark IM messages, chats, files, and interactive cards. Use it when coding tasks need access to team conversations. Claude Code CX Codex Cursor +1 472,300installs lark-event larksuite Listens to Lark/Feishu events and streams them as NDJSON. Use it for bots, message processing, and long-running subscribers. Claude Code CX Codex Cursor +1 466,200installs caveman-discover JuliusBrussee Finds and labels every LLM workflow in your repository so Caveman Cloud breaks down spend by actual job rather than grouping everything into one bucket. Claude Code CX Codex Cursor +1 103,500installs migration JuliusBrussee Enforces reversible, compatibility-safe transitions for schema, data, and API updates. Useful whenever data loss or rollout downtime is unacceptable. Claude Code CX Codex Cursor +1 102,900installs

Questions about gws-gmail-watch

How do I install gws-gmail-watch in Claude Code?

Run npx skills add googleworkspace/cli --skill gws-gmail-watch -a claude-code. The skill file is placed at ~/.claude/skills/gws-gmail-watch/SKILL.md.

What does gws-gmail-watch do?

It watches Gmail for new messages and streams them as NDJSON. It also supports label filtering, one-time pulls, and writing messages to JSON files.

What does gws-gmail-watch need to run?

You need gws, authentication, and the rules from gws-shared. Resource setup uses a GCP project, Pub/Sub subscription, or topic; existing resources can be passed with the matching flags.

Source text

SKILL.md · Apache-2.0 
---
name: gws-gmail-watch
description: "Gmail: Watch for new emails and stream them as NDJSON."
metadata:
  version: 0.22.5
  openclaw:
    category: "productivity"
    requires:
      bins:
        - gws
    cliHelp: "gws gmail +watch --help"
---

# gmail +watch

> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.

Watch for new emails and stream them as NDJSON

## Usage

```bash
gws gmail +watch
```

## Flags

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--project` | — | — | GCP project ID for Pub/Sub resources |
| `--subscription` | — | — | Existing Pub/Sub subscription name (skip setup) |
| `--topic` | — | — | Existing Pub/Sub topic with Gmail push permission already granted |
| `--label-ids` | — | — | Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD) |
| `--max-messages` | — | 10 | Max messages per pull batch |
| `--poll-interval` | — | 5 | Seconds between pulls |
| `--msg-format` | — | full | Gmail message format: full, metadata, minimal, raw |
| `--once` | — | — | Pull once and exit |
| `--cleanup` | — | — | Delete created Pub/Sub resources on exit |
| `--output-dir` | — | — | Write each message to a separate JSON file in this directory |

## Examples

```bash
gws gmail +watch --project my-gcp-project
gws gmail +watch --project my-project --label-ids INBOX --once
gws gmail +watch --subscription projects/p/subscriptions/my-sub
gws gmail +watch --project my-project --cleanup --output-dir ./emails
```

## Tips

- Gmail watch expires after 7 days — re-run to renew.
- Without --cleanup, Pub/Sub resources persist for reconnection.
- Press Ctrl-C to stop gracefully.

## See Also

- [gws-shared](../gws-shared/SKILL.md) — Global flags and auth
- [gws-gmail](../gws-gmail/SKILL.md) — All send, read, and manage email commands

© googleworkspace · Apache-2.0 · googleworkspace/cli

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor