Vault
The Lab · Vault · Blueprint · 45 to 90 minutes the first time

Your agent reads your inbox.

Gmail and Calendar from the terminal through gws, Google's own command-line tool. One Google account, signed in through your browser, read access only. Plan on 45 to 90 minutes the first time; most of it is Google's one-time sign-in setup.

In plain English

This is the one where your agent gets to see your email and calendar, and only see. You install Google's own command-line tool, sign in through your browser, and approve read-only access to Gmail and Calendar. Then two small tests prove it: it can list your recent unread messages, and it can list tomorrow's events. From there it pulls a small slice when you ask, headers, snippets, one-line summaries, never whole emails, and writes today's brief to work/morning-brief/ in your workbench. Nothing is sent, deleted or changed.

What you get

gws installed, one Google account signed in read-only for Gmail and Calendar, two smoke tests that prove it, and a morning brief prompt that writes today's brief to work/morning-brief/ and never stores raw email bodies.

Why it matters

The two things that decide your day live in Gmail and Calendar. A read-only pipe is enough to brief you, and it keeps sending out of reach until you choose to build that, with a person in the loop.

How it works

One npm install, a one-time Google sign-in setup, one gws auth login with read-only scopes that opens your browser, two list commands. Google's own tool, not a wrapper.

Your seat

You run the two sign-in commands in your own terminal window, click the screens in your browser, and say which slice of your inbox and calendar the agent may summarise. The agent runs the list commands. You read the summaries.

Bring one Google account. Yours.

Your own Gmail or Google Workspace account, one, the one you actually live in. The sign-in is Google's normal approval screen, in your browser, and the blueprint asks for read-only access to Gmail and Calendar and nothing else. A work account is fine only if your admin allows third-party command-line tools; if that screen refuses, use your own account instead.

In the commands the account is me and the calendar is primary. That is on purpose: no email address or calendar ID ever needs to be typed into anything you save or share.

Never
Never paste a token or a credentials file into the chat.

The sign-in happens in your browser and the token lives where gws keeps it, on your machine. If an agent ever offers to enter a real credential for you, the answer is no. And do not request send, delete or modify scopes for this; a drafting or reply workflow is a separate build with its own approval gate.

What happens the first time?

Five steps. The sign-in is the long one, and you do it yourself. Here is what goes by so none of it is a stranger.

  • It checks for Node. Version 18 or newer. If you ran the AIBL installer, it is there.
  • It installs the tool. One npm package, @googleworkspace/cli. That is where the gws command comes from. Homebrew works too; use one path, not both.
  • You sign in, in your own terminal window. You run gws auth setup, then gws auth login with read-only scopes for Gmail and Calendar, and tell your agent when you are done. A browser tab opens; you approve; you come back. Your agent waits while you do it.
  • It checks the pipe. gws auth status, then a Gmail list of recent unread or starred messages, then a Calendar list of upcoming events. If those come back, the connection is real.
  • Then the useful part. A small pull, headers and snippets only, in the compact shape the example contract shows. The morning brief prompt turns it into today's brief at work/morning-brief/YYYY-MM-DD.md.

The first sign-in is the long part. gws auth setup needs Google's gcloud tool. Without it, you make a small private app in the Google Cloud console instead, with your own account as its only tester. Your agent walks you through each screen; you click. Six screens:

  • 1. A project. Create or choose a Google Cloud project.
  • 2. The two APIs. Turn on the Gmail API and the Google Calendar API in that project.
  • 3. The consent screen. Set up the OAuth consent screen as External.
  • 4. You, as tester. Add your own Google account as a test user.
  • 5. The client. Create an OAuth client of type Desktop app.
  • 6. The file. Download the client JSON and save it as client_secret.json in the .config/gws folder in your home folder. Then run gws auth login.
Note
Two things Google does that look odd.

Google will warn that it hasn't verified this app. It is your own app, so that is expected: click Continue. And expect to sign in again, likely about once a week: a 30-second browser click.

You'll see
These are the real commands, in the order they run.
npm install -g @googleworkspace/cli
gws auth setup
gws auth login --readonly -s gmail,calendar
gws auth status
gws gmail users messages list --params '{"userId":"me","q":"newer_than:1d (is:unread OR is:starred)","maxResults":10}'
gws calendar events list --params '{"calendarId":"primary","timeMin":"YYYY-MM-DDT00:00:00-05:00","timeMax":"YYYY-MM-DDT23:59:59-05:00","singleEvents":true,"orderBy":"startTime","maxResults":10}'

You type the two gws auth lines yourself, in your own terminal window. Your agent runs the rest. In the calendar command, your agent puts in today's date and this computer's time zone (-05:00 is only an example).

Note
Codex works the same way.

The commands are identical. The install and the smoke tests cross the network, so in Codex's sandbox those steps ask before they run. Say yes. The sign-in you run in your own terminal window, in either app.

What you can ask your agent, from now on

Five asks that work on day one. Copy, paste, read what comes back. Every one of them is read-only.

This morning

Using gws, list my unread or starred messages from the last day: sender, subject and a one-line summary each. No bodies.

Tomorrow

Using gws, what is on my primary calendar tomorrow, in order, and for each one the single thing I should prepare.

Today's brief

Follow lab/blueprints/gws-cli-connect/MORNING-BRIEF-PROMPT.md: pull today's Gmail and Calendar slice with gws and write my brief to work/morning-brief/ with today's date. Headers, snippets and one-line summaries only.

What did I grant?

Run gws auth status and tell me which account is signed in and exactly which scopes were granted.

What am I forgetting?

Using gws, which messages from this week look like they are waiting on an answer from me? Sender and subject only, newest first.

Words you now own

  • OAuth. The approval screen in your browser. You say yes once; Google gives the tool a token that stands in for you, limited to what you approved.
  • Scope. One thing the token may do. This blueprint asks for read-only Gmail and read-only Calendar, and nothing that sends, deletes or changes.
  • gws. Google's own command-line tool for Workspace. gws gmail, gws calendar, and so on.
  • Snippet. The first line or so of an email, the part Gmail shows in the list. Enough to summarise; not the body.
  • Source pull. One small fetch of exactly what a brief needs, in a fixed shape, kept on your machine.
  • Morning brief. One short page for today, built from your Gmail and Calendar slice and saved at work/morning-brief/YYYY-MM-DD.md. MORNING-BRIEF-PROMPT.md writes it; to have it ready every morning, use the Lab skill Heartbeats and Scheduled Jobs.

Before you pull anything

Three habits the blueprint asks for, because your inbox is other people's words too.

  • Read-only, and stay there. No send, delete or modify scopes. When you want a reply workflow, that is its own build with a person saying yes to each send.
  • Headers and snippets, not bodies. Nothing in the compact shape is a whole email. Full bodies never go into a file in your workbench or into a database. Headers and snippets pass through your AI app, like anything else you ask it to read.
  • No exports in git. Raw email or calendar pulls stay on your machine and out of anything committed. Before the first brief, your agent checks that work/morning-brief/ is ignored by Git, and adds the one line to .gitignore on your yes.
Never
Never commit a token, a credentials file, or a raw email or calendar export.

Your workbench is private, and this is still the rule. The token lives where gws keeps it; the brief and its compact summary live in work/morning-brief/, never inside lab/.

Fair questions

FAQ
Can it send email?

Not with this, on purpose. The scopes are read-only. A drafting or reply workflow is a separate build, and it keeps a person between the draft and the send.

FAQ
My work Google account is locked down. Now what?

Then the approval screen will refuse, and that is your admin's call. Use your own account; the blueprint only ever needs one.

FAQ
Is there a live session for this one?

No. Not scheduled, and it does not need one: the files are complete on their own. If a Tuesday ever walks it live, that session links from this page.