| name | connect-gws |
| description | Install the Google Workspace CLI (gws) and sign the user in, so the brain can pull Google Drive, Gmail, and Calendar into raw/ as local copies. Use when connecting any Google source as a saved local copy rather than a live connector. |
Connect: Google Workspace (the gws CLI)
You're wiring the user's Google Drive, Gmail, and Calendar so the brain keeps a
local copy in raw/. The user is not technical. Do the typing yourself, explain
each step in one line, and stop if something fails instead of pushing on.
This is the local-copy path (data saved to disk, the way our own brain pulls
Google). If they only want an agent to read Gmail or Calendar live and never
need a saved copy, a connector is simpler — see /connect-gmail. Use gws when
they want the data sitting in raw/, searchable and ingestible offline.
1. Install gws
Offer to run the one that fits their machine, then confirm with gws --version:
2. Sign in — their own Google account, no shared key
gws auth setup — one-time. It walks them through creating their own
Google Cloud project and logs them in. It uses the gcloud CLI under the hood.- If they don't have
gcloud, do the manual setup instead: Google Cloud Console
→ OAuth consent screen → add themselves as a Test user → create a Desktop
app OAuth client → download the JSON → save it to
~/.config/gws/client_secret.json. (Full steps:
https://github.com/googleworkspace/cli#authentication)
gws auth login -s drive,gmail,calendar — sign in and scope it to what they
need. Scope to services, not the big "recommended" preset: an unverified
app is capped at ~25 scopes and the preset will fail.- If the browser warns "Google hasn't verified this app", that's expected for
their own testing-mode app — have them click Continue.
Credentials are encrypted at rest in the OS keyring. Never have them paste a
key or token into the chat.
If the Google Cloud / gcloud setup gets hairy and they really just want their
email or calendar readable (not saved to disk), stop here and use the
connector instead — /connect-gmail, a browser sign-in with no project to
create. Only push through the gws setup when they genuinely need a local copy
in raw/.
3. Confirm it works
gws drive files list --params '{"pageSize": 5}' should print a few file names.
For Gmail or Calendar, run gws gmail --help / gws calendar --help to see the
exact resource, or gws schema drive.files.list to introspect any method.
4. Turn it into a puller (so it refreshes on its own)
Copy scripts/pull-example.sh to scripts/pull-drive.sh (or ask Claude to write
it): have it call gws and write under raw/drive. Same shape for pull-gmail.sh
and pull-calendar.sh. Run each once and confirm files land in raw/. Once they
exist, the morning/evening routines pick them up automatically.
5. Close
Mark the Drive / Email / Calendar rows in sources.md with today's date. Tell
them in two lines what's live and what's next. They can re-run /connect any time.
