Running Google Workspace from Claude Code / Cursor with gog CLI — Implementation Guide

2. Five operating rules

1. Never commit the OAuth client JSON. Reference it through .env or the OS credential manager.
2. Keep refresh tokens in gog's local directory only. Never paste them into Slack, Notion or GitHub issues.
3. Remember scope inheritance: when the agent reads shared Drives, it sees them with your own permissions.
4. Wrap destructive actions (sending mail, deleting events, moving files) with dry-runs or previews.
5. If you need other users' credentials, coordinate with the Workspace admin and use the official Test Users flow.

3. Tool layout

gogcli — direct Workspace operations

Gmail / Calendar / Drive / Sheets / Docs reads and writes through one command surface. OAuth lives here too.

google-workspace-ops — high-level skills

Composite tasks (e.g. "find missed replies and prepare 3 drafts") packaged as Claude Code / Cursor skills, calling gogcli underneath.

gas-clasp-ops — Apps Script bridge

Drives GAS projects (push / deploy / run) through clasp so an agent can edit Apps Script directly and wire up Sheets triggers.

4. A typical day

1. Morning email triage (missed replies → drafts)
2. Scheduling (free-slot search → event creation)
3. Drive cleanup (list → rename / move)
4. Sheets / Excel aggregation (read → transform → export)
5. Meeting notes draft in Docs
6. GAS triggers to automate the next day's routines

5. GCP setup

1. Create a new project in Cloud Console and link a billing account (required even when the practical usage stays near the free tier).
2. APIs & Services → Library: enable Gmail, Calendar, Drive, Sheets and Docs APIs.
3. Google Auth Platform → Branding: fill in app name, contact and logo. Keep the app in test mode.
4. Audience tab → Test users: add your own Google account.
5. Credentials → Create credentials → OAuth client ID. Choose user type "External" and application type "Desktop app".
6. Download the JSON. Keep it out of the repo (e.g. credentials/my-google-workspace-oauth.json under a local-only directory).

6. gog authentication

# 1. Confirm installation
gog --version

# 2. Register OAuth client
gog auth credentials set credentials/my-google-workspace-oauth.json

# 3. Add account (opens a browser)
gog auth add your-email@example.com

# 4. Check connection
gog auth list

The browser will show the "This app isn't verified" warning. That's the expected state for an app still in test mode — open Details and continue to the app you created. Approve the Calendar / Gmail / Drive scopes you need. Claude Code / Cursor users can run the slash command /module-4-gcp-quick and have the agent walk through the four steps above.

7. Authentication test

# Latest 5 inbox messages
gog gmail search --query "is:inbox" --max 5

# Calendar events for the next 7 days
gog calendar events --days 7

Three common failure modes:

• Your address is missing from the OAuth Test Users list.
• The OAuth client is not of type Desktop app.
• You enabled Gmail but forgot Calendar (or any other API).

8. Calendar

# Find a 60-minute slot in the next 7 working days
gog calendar free-slots --duration 60 --days 7 --working-hours 10-18

# Create an event
gog calendar create-event \
  --title "1on1 @ koheinakamura" \
  --start "2026-05-20T15:00:00+09:00" \
  --duration 30 \
  --attendees "partner@example.com"

Ask "book a 1on1 for any free slot next week" inside Claude Code or Cursor and the agent chains free-slots → create-event automatically. The module covers six scenarios (internal / customer / interview / conference / focus block / deadline reminder).

9. Morning email triage

1. Use gog gmail search to find threads where you sent the last message but never received a reply.
2. Feed each thread to an agent and ask Gemini to score priority and decide whether a reply is needed.
3. For those that need one, generate a pre-send draft with gog gmail draft create.

10. Drive

# List 20 latest files under a folder
gog drive list --parent <folder-id> --max 20

# Download to local
gog drive download <file-id> --output ./downloads/

# Export Sheets as CSV
gog drive export <sheet-id> --format csv --output ./out.csv

11. Sheets / Excel

# List sheets
gog sheets list <spreadsheet-id>

# Export a range to CSV
gog sheets export <spreadsheet-id> \
  --range "Sheet1!A1:F100" \
  --format csv \
  --output ./out.csv

# Preview first 20 rows
gog sheets preview <spreadsheet-id> --max 20

12. GAS automation

To keep things running while no one is typing, combine GAS triggers with the gas-clasp-ops skill. The agent can push and deploy Apps Script directly, then wire it to Sheets triggers for nightly or weekly runs.

13. Skills you walk away with

• Gmail triage and draft generation
• Calendar free-slot search and event creation
• Drive listing, naming, sharing
• Sheets export and integration with other tools
• Docs draft generation for meeting notes
• Scheduled execution via GAS triggers
• One-shot operations from Claude Code / Cursor slash commands