gws CLI Connect.
The student-safe Google Workspace CLI path for email and calendar. Install gws, authenticate your one Google account, prove read-only Gmail and Calendar commands work, and hand compact source summaries to your Morning Brief without committing raw Google data.
- One Google account connected through gws OAuth, using the default student config instead of staff-style profile switching.
- Two source smoke tests Gmail metadata and Calendar events, pulled with read-only commands you can inspect before the brief uses them.
- A Morning Brief handoff the paste-ready prompt that turns those pulls into compact source summaries for /build-morning-brief.
Connect it with Claude.
Paste this into Claude Code. Claude reads the local blueprint, walks you through install and auth, then runs the Gmail and Calendar smoke tests before touching the Morning Brief.
How this fits in the OS.
Node.js, your own Google account, a browser for OAuth, and the blueprints/gws-cli-connect/ files in your local workshop repo.
The Google Workspace CLI, gws, to read Gmail metadata and Google Calendar events from one account. This is a CLI path, not an MCP path. Claude Desktop calls MCPs connectors, but this build uses a terminal tool.
Your Morning Brief can start with real email and calendar context, pulled by a repeatable command-line shape the agent can inspect and rerun.
What changes for you.
The artifact is small: a CLI install, an OAuth login, two smoke tests. The shift is that your agent can now read the two systems that usually define your morning.
- You stop treating email and calendar as separate chores. The brief can look at both before it writes a single sentence.
- You get a source path you can debug. A gws command either returns JSON or fails with an error. That is easier to reason about than a mystery connector state.
- You keep the privacy boundary visible. Raw pulls stay local and gitignored. The brief gets compact summaries, not a repo full of inbox exports.
This is the Connect Your Data checkpoint in its most inspectable form: a terminal command that reads your account only after you approve the connection.
Before you start.
Four things specific to this build
- One Google account you are allowed to connect. Use your own account, not someone else's inbox or calendar.
- Node.js 18 or newer. The recommended student install uses npm.
- A browser you can use for Google's OAuth approval flow.
- Infisical/1Password ready for any credential value you must store yourself. You will never paste real credentials into Claude chat.
The workshop path uses the default gws config and one account. Do not copy multi-profile examples from staff machines or old notes. If you see GOOGLE_WORKSPACE_CLI_CONFIG_DIR, that is an advanced isolation pattern, not the student default.
The build.
Seven checkpoints. Stop after each one long enough to see what happened. The agent can run the commands, but you approve the account connection and type any real credential values yourself.
Install gws
5 minThe simplest student path is npm. From your terminal:
npm install -g @googleworkspace/cli
gws --version
If you already use Homebrew, the blueprint also gives a brew install option. Use one path, not both.
npm is missing? Finish the workshop setup path first. Do not work around a missing Node install by pasting random install scripts from the web.
Set up OAuth
7 minRun the setup command:
gws auth setup
This prepares the Google Cloud and OAuth pieces that gws needs. If it asks you to log in, choose the one Google account you want your Morning Brief to read.
You will never paste downloaded OAuth JSON, client secrets, tokens, or browser callback codes into Claude chat. If Claude offers to enter the real value for you, say no. This rule has no exceptions.
gws auth setup says gcloud is missing? Use the manual OAuth setup from the gws README. Claude can walk you through the clicks, but you save the credential file yourself and never paste it into chat.
Log in with read-only scopes
3 minThe Morning Brief only needs to read. Ask for Gmail and Calendar, not every Workspace service:
gws auth login --readonly -s gmail,calendar
gws auth status
If Google shows scope checkboxes, approve only the read scopes this checkpoint needs. Drafting and sending email are different builds with their own safety gates.
Smoke test Gmail
3 minPull a small slice of recent unread or starred messages. Start with IDs, then inspect metadata for at most a few messages:
gws gmail users messages list \
--params '{"userId":"me","q":"newer_than:1d (is:unread OR is:starred)","maxResults":10}'
gws gmail users messages get \
--params '{"userId":"me","id":"MESSAGE_ID","format":"metadata","metadataHeaders":["From","Subject","Date"]}'
The list command returns IDs and thread IDs by design. The get command pulls the metadata the brief can summarize.
gws auth status and confirm login.
Smoke test Calendar
3 minUse your actual date window. This example shows one Central-time day:
gws calendar events list \
--params '{"calendarId":"primary","timeMin":"2026-05-31T00:00:00-05:00","timeMax":"2026-06-01T00:00:00-05:00","singleEvents":true,"orderBy":"startTime","maxResults":10}'
Use primary first. You can list your calendars later, but the checkpoint should not stall on calendar IDs.
singleEvents:true and orderBy:"startTime" are both in the params. That expands recurring meetings into the actual instances your brief needs.
Hand sources to the Morning Brief
7 minUse the prompt that ships with the blueprint. It asks Claude to turn small gws pulls into compact source summaries, then run the Morning Brief with Gmail and Calendar enabled.
Open blueprints/gws-cli-connect/MORNING-BRIEF-PROMPT.md, read it, and walk me through it checkpoint by checkpoint. Use gws as the source path for /build-morning-brief gmail,calendar. Keep raw Google pulls local and gitignored.
The agent does this for you. You approve each checkpoint. Claude runs the source pulls, creates the compact summary shape from brief-source-contract.example.json, and hands that summary to /build-morning-brief.
Check the privacy boundary
2 minBefore any commit or push, run:
git status --short
No raw Gmail JSON, Calendar JSON, OAuth token, credential file, or local output folder should be staged. The blueprint's gitignore covers the default local output path.
When it works.
You know this connection is real when five things happen in order:
gws --versionworks. The CLI is installed and on your PATH.gws auth statusshows one authenticated account. No profile switching needed.- Gmail returns message IDs or an empty result without an auth error. Empty data is fine. Broken auth is not.
- Calendar returns events or an empty result without an auth error. The command can read your primary calendar.
- The Morning Brief uses compact summaries. Raw pulls stay local, and the brief sees only the small source contract it needs.
If you get stuck.
Common failure modes, ranked by how often they waste time:
- Wrong account approved. Log out with
gws auth logout, then run the scoped login again and choose the right Google account. - Too many scopes requested. Use
gws auth login --readonly -s gmail,calendar. Do not select every Workspace API for this checkpoint. - Access blocked during OAuth. Add your own account as a test user in the OAuth consent screen, then retry.
- Message list looks too thin. That is normal. Gmail list returns IDs. Use
messages.getwithformat:"metadata"for headers and snippets. - Timezone drift. Calendar commands need RFC3339 timestamps with a timezone offset. Ask Claude to compute today's start and end in your local timezone before it runs the command.
- Raw exports appear in git. Stop. Move them under
apps/morning-brief/out/gws/or another gitignored path, then re-rungit status --short.
Where to go next.
Once gws is connected, these are the natural next moves.