gws-events-subscribe Skill: Stream Google Workspace Events as JSON Lines

Streams Google Workspace events, such as new Chat messages, into your terminal as lines of JSON.

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

gws-events-subscribe has your agent run gws events +subscribe, which listens for Workspace events on a target such as a Chat space and prints each one as a line of JSON (NDJSON). Unless you pass an existing subscription, it sets up Google Cloud Pub/Sub resources to receive them. SKILL.md marks it as a write command and says to confirm with you before it runs. You need the gws program installed, signed in, and a Google Cloud project for the Pub/Sub resources.

Good for

Developers who want Chat messages or other Workspace events piped into an agent
Teams building bots or automations on Workspace events
Claude Code or Codex users who already run the gws program

Install gws-events-subscribe

Claude Code

Copy this prompt.

Install the gws-events-subscribe skill in Claude Code. Run this command:

npx skills add https://github.com/googleworkspace/cli --skill gws-events-subscribe --skill gws-events --skill gws-shared -a claude-code

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, gws installed and signed in.

Do the "First" and "Then" methods once before the skills command: they install gws and sign you in. The skills command adds 3 skills (gws-events-subscribe, gws-events, gws-shared) because gws-events-subscribe reads gws-shared first and points to the others in the set. Without gcloud, use the manual OAuth setup in the README.

From the vendor's docs. Source.

What's in the skill

When it loads

Google Workspace Events: Subscribe to Workspace events and stream them as NDJSON.

Sections in SKILL.md

Usage
Flags
Examples
Tips
See Also

Key facts

Author: googleworkspace organization (repo owner)
Status: Not an officially supported Google product, per the README
License: Apache-2.0
Installs on skills.sh: 31,081 (Nov 2, 2026)
GitHub stars: 32,038 (Nov 2, 2026) (whole repo)
Last commit: Oct 30, 2026
What installs: 1 file, SKILL.md; it bundles no scripts
Needs: the gws program signed in to Google, a Google Cloud project, plus gws-shared and gws-events
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn
Documented setups: skills CLI, OpenClaw, Gemini CLI extension

What it includes

Subscribes to Workspace events and streams them as NDJSON
The one command this skill covers. SKILL.md marks it as a write command.
Write · gws events +subscribe
Pick the resource and the events to follow
--target is a Workspace resource URI such as a Chat space. --event-types is a comma-separated list of CloudEvents types.
--target and --event-types
Name the Pub/Sub project or reuse a subscription
--project is the Google Cloud project for the Pub/Sub resources. --subscription skips setup and uses an existing Pub/Sub subscription.
Network · --project and --subscription
Pulls once and exits
Without it the command keeps pulling, and the skill says to press Ctrl-C to stop.
--once
Set batch size and wait time
Defaults are 10 messages per pull and 5 seconds between pulls.
--max-messages and --poll-interval
Deletes the Pub/Sub resources on exit
SKILL.md says that without it the resources stay in place so you can reconnect.
Delete · --cleanup
Leaves messages unacknowledged
Stops the command from acknowledging messages automatically.
--no-ack
Writes each event to its own JSON file
Saves one file per event in the folder you name.
Write · --output-dir

From the official docs

Permissions

Medium risk

It creates Google Cloud Pub/Sub resources and keeps pulling events until you stop it. Sign in with only the services you need and read each command before you approve it.

What it can do

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

Watch out for

It creates Google Cloud resources
The skill calls this a write command. Without --cleanup the Pub/Sub resources stay in your project, so remove them yourself when you are done. github.com
It keeps running until you stop it
The command pulls events in a loop. Ask for --once if you want a single check, or press Ctrl-C to stop. github.com
Events are printed into your session
The agent reads each event the command prints. Subscribe only to spaces and resources you are happy to share with your AI provider. github.com
--output-dir writes one file per event
Point it at a folder you expect to fill up, not at a project directory. github.com
The project is in active development
The README says to expect breaking changes before v1.0. Re-read the install steps after you update gws. github.com

Technical details

Turning on read-only	No read-only switch in the skill. The gws-shared skill says to prefer --dry-run for destructive operations and to confirm write commands with you.
Talks to	Google Workspace Events API and Google Cloud Pub/Sub through gws
Sign-in and keys	gws sign-in. The README says credentials are encrypted at rest (AES-256-GCM) with the key kept in your OS keyring.
Scopes	Google Workspace Events and Pub/Sub access in the Google Cloud project you name

Questions

What does gws-events-subscribe do?

Streams Google Workspace events, such as new Chat messages, into your terminal as lines of JSON.

How do I install gws-events-subscribe in Claude Code?

Use the install box above. It adds gws-events-subscribe together with gws-events, gws-shared in one step. You also need the gws program installed and signed in to Google first, and the box lists both steps.

Does gws-events-subscribe work in the Claude app or Codex?

The install box has a Codex tab that uses the skills CLI's Codex target, but the repo README does not list Codex as a supported setup. The README documents no Claude app route, and every command runs the gws program in a terminal, so use Claude Code or another terminal agent.

Does gws-events-subscribe need an API key?

No API key. It uses your Google sign-in through gws, and the README says you need a Google Cloud project for the sign-in credentials. gws auth setup can create one if you have the gcloud CLI.

Is gws-events-subscribe safe?

It creates Google Cloud Pub/Sub resources and keeps pulling events until you stop it. SKILL.md calls it a write command and says to confirm with you first. Use --cleanup to remove what it created, and point it at spaces you are happy to share with your AI provider.

Do I have to use Google Cloud Pub/Sub?

The command uses Pub/Sub to receive events. It creates the resources for you in the project you name, or reuses an existing subscription if you pass one.

How do I stop it?

Press Ctrl-C and it stops gracefully. Add --once to pull a single batch and exit. Add --cleanup if you want the Pub/Sub resources it created to be removed on exit.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-events-subscribe

googleworkspace/cli skills.sh

Sources

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

Show all 4

googleworkspace/cli README · github.com
skills CLI commands · github.com
gws-events-subscribe SKILL.md · github.com
gws-shared SKILL.md · github.com