gws-gmail-watch Skill for Claude: What It Does and How to Install It

Lets Claude run the gws CLI to watch your Gmail inbox and stream each new email as it arrives.

Installs: 37.6K; on skills.sh
Stars: 32K; on GitHub
Updated: Oct 2026; last repo commit

gws-gmail-watch teaches Claude one command, gws gmail +watch. It listens for new mail through Google Cloud Pub/Sub and prints each message as one line of JSON (NDJSON), with options to filter by label, pull once and exit, or write each message to a file.

It needs the gws command-line tool, a signed-in Google account and a Google Cloud project for Pub/Sub. The SKILL.md tells Claude to read the gws-shared skill first for sign-in, flags and security rules.

Good for

Developers who want Claude to react to new Gmail messages
Anyone building an email pipeline on top of the gws CLI
Google Cloud users who already have a project for Pub/Sub

Install gws-gmail-watch

Claude Code

Copy this prompt.

Install the gws-gmail-watch skill in Claude Code. Run this command:

npm install -g @googleworkspace/cli

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 18+.

This skill only wraps the gws command, so gws must be installed and signed in first (step 1 is the README's npm route; it also offers release binaries, Homebrew and cargo). It tells Claude to read the gws-shared skill first, so step 3 adds both. The README says gws auth setup creates a Cloud project, enables the APIs and logs you in, and that gws auth login handles later sign-ins. If you have no gcloud CLI, use the manual OAuth setup in the README instead. The Claude app ZIP upload is not offered because the commands must run on your own machine.

From the project README. Source.

What's in the skill

When it loads

Gmail: Watch for new emails and stream them as NDJSON.

Sections in SKILL.md

Usage
Flags
Examples
Tips
See Also

Key facts

Author: Google Workspace (googleworkspace org)
Repository: googleworkspace/cli (the gws CLI repo)
Installs on skills.sh: 37,582 as of 2026-11-02
GitHub stars: 32,038 for the whole googleworkspace/cli repo, 2026-11-02
License: Apache-2.0
Last commit to the repo: 2026-10-30
What is inside: 1 file: SKILL.md (it tells Claude to read the separate gws-shared skill first)
Version: 0.22.5 (SKILL.md frontmatter)
Needs: The gws command on your PATH and a signed-in Google account
Official status: The README says: "This is not an officially supported Google product."
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn

What it includes

Watch for new emails and stream them as NDJSON
Starts the watch and prints new messages until you press Ctrl-C. The SKILL.md says the Gmail watch expires after 7 days, so run it again to renew.
Try: “Use gws to watch my inbox for unread mail in the project my-gcp-project.”
Runs code · gws gmail +watch
Choose or create the Pub/Sub resources
Pass a GCP project ID to set up Pub/Sub resources, or point at an existing topic or subscription to skip setup.
Write · --project, --topic, --subscription
Only watch labels such as INBOX,UNREAD
Comma-separated Gmail label IDs to filter on.
Read · --label-ids
full, metadata, minimal or raw
Sets how much of each message is returned. The default is full.
Read · --msg-format
Pull one batch and exit
Useful for a single check instead of a long-running watch.
Network · --once
Delete the Pub/Sub resources it created on exit
Without this flag the SKILL.md says the Pub/Sub resources persist so you can reconnect.
Delete · --cleanup
Write each message to its own JSON file
Saves one JSON file per message into the folder you name.
Write · --output-dir

From the official docs

Permissions

Medium risk

This skill reads your Gmail through the gws CLI and can create Google Cloud Pub/Sub resources in your project. Try it on a test account or a narrow label filter before pointing it at your main inbox.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Email contents flow into your conversation
New messages print to the terminal and Claude reads them. Filter by label and use a test account first. github.com
It can create and delete Pub/Sub resources
It sets up Pub/Sub resources in your project, and the cleanup flag deletes the ones it made. Name an existing topic or subscription if you want to control what is created. github.com
The Gmail watch runs until you stop it
Press Ctrl-C to stop. The SKILL.md says the watch expires after 7 days. github.com
Not an official Google product
The README says the gws CLI is not officially supported by Google. Read its auth and scope notes before you sign in. github.com

Technical details

Turning on read-only	No read-only switch is documented in SKILL.md.
Talks to	Gmail API and Google Cloud Pub/Sub via the gws CLI
Sign-in and keys	Sign-in is handled by gws. The README says credentials are encrypted at rest (AES-256-GCM) with the key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is chosen.
Scopes	Gmail access through your gws sign-in Pub/Sub topic and subscription in the GCP project you name

Questions

What does gws-gmail-watch do?

It tells Claude how to run gws gmail +watch, which streams new Gmail messages as NDJSON using Google Cloud Pub/Sub. It adds one command and no other behavior.

How do I install gws-gmail-watch?

Use the install box at the top of this page. It covers the gws CLI, the sign-in step and both skills, because the skill needs the gws command and the shared gws skill.

Does it need a Google Cloud project?

The SKILL.md's --project flag takes a GCP project ID for the Pub/Sub resources, and you can instead name an existing topic or subscription. The README also lists a Google Cloud project as required for the gws OAuth sign-in.

Is gws-gmail-watch safe to use?

It gives Claude access to your mailbox through your own Google sign-in, and message contents flow into the conversation. It also creates Pub/Sub resources in your project unless you point it at existing ones. Use a test account or a narrow label filter first.

Why did the watch stop after a week?

The SKILL.md says a Gmail watch expires after 7 days. Run the command again to renew it.

Is the gws CLI an official Google product?

The README says it is not an officially supported Google product, although it lives in the googleworkspace GitHub organization.

gws-gmail-watch vs gws-gmail-reply?

Watch streams incoming mail. The separate gws-gmail-reply skill sends replies. They share the same gws CLI and sign-in.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-gmail-watch

googleworkspace/cli skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4