gws-chat Skill: Manage Google Chat Spaces and Messages

Lets your coding assistant manage Google Chat spaces, messages and custom emojis by running the gws command line tool.

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

gws-chat teaches your assistant to use gws chat, the Google Chat part of the gws tool. It covers spaces, messages, members, media uploads and downloads, and custom emojis. It also points to a +send helper for posting a message to a space.

You need the gws command line tool and a Google sign-in. The skill covers write and delete actions, and deleting a space also deletes its messages and memberships, so approve those yourself.

Good for

Google Workspace teams that want an assistant to post updates to Chat spaces
Admins who list, search or set up Chat spaces and their members
Developers who want to explore the Chat API from the terminal

Install gws-chat

Claude Code

Copy this prompt.

Install the gws-chat 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+.

Do steps 1 to 3 in order. The skill only gives your assistant instructions. The gws tool does the work, and it needs a Google sign-in. The command also adds gws-chat-send, the +send helper the SKILL.md links to. gws auth setup needs the gcloud CLI to create a Google Cloud project for you; without gcloud, use the manual setup in the README. The README also lists a GitHub Releases download, Homebrew and cargo as other ways to get gws.

From the project README. Source.

What's in the skill

When it loads

Google Chat: Manage Chat spaces and messages.

Sections in SKILL.md

Helper Commands
API Resources
customEmojis
media
spaces
users
Discovering Commands

Key facts

Author: googleworkspace org (the README says it is not an officially supported Google product)
Repo: googleworkspace/cli
Installs on skills.sh: 33,492 as of 2026-11-02
GitHub stars: 32,038 for the whole googleworkspace/cli repo, 2026-11-02
License: Apache-2.0 (README)
Last commit to the repo: 2026-10-30
What is inside: 1 file (SKILL.md). It points to the separate gws-shared and gws-chat-send skills.
Needs: The gws command line tool (Node.js 18+ for the npm route), a Google account and a Google Cloud project for sign-in
Also installs: gws-shared, plus gws-chat-send, the helper the index lists for sending a message
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn (2026-11-02)

What it includes

Sends a message to a Chat space
The helper skill gws-chat-send runs gws chat +send --space <NAME> --text <TEXT>. Its SKILL.md marks it as a write command and says to confirm with the user before running it.
Try: “Send "Build is green" to spaces/AAAAxxxx.”
Runs code · +send
Creates, lists, searches, updates and deletes spaces
Includes create, setup (a space with initial members), get, list, patch, findDirectMessage, search (an administrator's search) and completeImport. Delete always cascades: the space's messages and memberships go with it.
Try: “List the Chat spaces I am a member of.”
Delete · spaces
Works with people, messages and events inside a space
The resource names are listed in the SKILL.md. Use gws schema chat.<resource>.<method> to see each method's parameters.
Write · spaces.members, spaces.messages, spaces.spaceEvents
Creates, lists, gets and deletes custom emojis
Custom emojis are only available for Google Workspace accounts, and an administrator must turn them on for the organization.
Delete · customEmojis
Uploads and downloads Chat attachments
upload adds an attachment, and download fetches media by name.
Write · media
Works with your own Chat sections and spaces
Listed as resources in the SKILL.md.
Write · users.sections and users.spaces
Browses methods and shows their parameters
The skill tells the assistant to inspect a method before it calls it, then build the --params and --json flags from the schema.
Read · gws chat --help and gws schema

From the official docs

Permissions

High risk

This skill can post Chat messages as you and delete whole spaces with their messages. Approve every write and delete yourself.

What it can do

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

Watch out for

Deleting a space deletes its messages
The spaces delete method always cascades to the space's messages and memberships. Approve any delete yourself and check the space name. github.com
It posts messages as you
gws chat +send is marked as a write command that needs the user's confirmation. Read the space name and text before you approve. github.com
Chat content goes to your AI provider
Messages and member lists the assistant reads become part of your chat with it. Avoid it on spaces with sensitive content. github.com
Setup installs a global npm package
The npm route downloads the gws binary from GitHub Releases. The README also says to expect breaking changes before v1.0, so pin what you rely on. github.com
You need a Google Cloud project to sign in
gws uses OAuth credentials from your own Google Cloud project. If the consent screen is unverified, Google caps the scopes you can pick, so choose individual services with gws auth login -s. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. Choose --dry-run to preview a call, and sign in with only the services you need.
Talks to	Google Workspace APIs, called by the gws tool. Anything the assistant reads from your account goes to your AI provider as part of the chat
Sign-in and keys	gws encrypts saved credentials (AES-256-GCM) with a key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is chosen.
Scopes	Whatever Google permissions you approve when you run gws auth login

Questions

What does gws-chat do?

It makes your assistant manage Google Chat through gws chat. That covers spaces, messages, members, attachments and custom emojis, plus a helper for sending a message to a space.

How do I install gws-chat?

Use the install box at the top of this page and run all three steps. The command adds gws-shared and gws-chat-send together with gws-chat. You also need the gws tool and a Google sign-in.

Does it need a Google Cloud project or an API key?

It needs a Google Cloud project, because gws signs in with OAuth credentials from one, according to the README. gws auth setup can create it if you have the gcloud CLI. Without gcloud, follow the README's manual setup.

Can it delete Chat spaces or messages?

Yes. The spaces delete method always performs a cascading delete, which removes the space's messages and memberships too. Custom emojis can also be deleted. Approve any delete yourself.

Is gws-chat safe to use?

It can post messages and delete spaces as you, so review each command before approving it. The shared rules tell the assistant to confirm write and delete commands first and to prefer --dry-run for destructive ones.

Can I use it in the Claude app or Claude.ai?

The README does not document that. The skill tells the assistant to run gws shell commands, so it fits an assistant that can run commands on a machine where gws is installed and signed in, such as Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-chat

googleworkspace/cli skills.sh

Sources

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

Show all 5

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