---
name: google-workspace
description: "Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python."
version: 1.0.1
author: Nous Research
license: MIT
required_credential_files:
  - path: /DATA/AppData/hermes/google_client_secret.json
    description: Google OAuth2 client credentials - project amadeus-494810
  - path: /DATA/.hermes/google_token.json
    description: Google OAuth2 token - ahmed.aytac@gmail.com, all scopes granted
metadata:
  hermes:
    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]
    homepage: https://github.com/NousResearch/hermes-agent
    related_skills: [himalaya]
---

# Google Workspace

Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.

## References

- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)
- `references/bulk-gmail-operations.md` — Bulk deletion: rate-limiting, retry patterns, date-range pagination

## Scripts

- `scripts/setup.py` — OAuth2 setup (run once to authorize)
- `scripts/google_api.py` — compatibility wrapper CLI. It prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.

## First-Time Setup

The setup is fully non-interactive — you drive it step by step so it works
on CLI, Telegram, Discord, or any platform.

Define a shorthand first:

```bash
GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
```

### Step 0: Check if already set up

```bash
$GSETUP --check
```

If it prints `AUTHENTICATED`, skip to Usage — setup is already done.

### Step 1: Triage — ask the user what they need

Before starting OAuth setup, ask the user TWO questions:

**Question 1: "What Google services do you need? Just email, or also
Calendar/Drive/Sheets/Docs?"**

- **Email only** → They don't need this skill at all. Use the `himalaya` skill
  instead — it works with a Gmail App Password (Settings → Security → App
  Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
  Load the himalaya skill and follow its setup instructions.

- **Anything beyond email** → Continue with this skill. Note: the setup
  script (`setup.py`) always requests the full SCOPES list (Gmail
  read/send/modify, Calendar, Drive read, Contacts, Sheets, Docs read).
  There is no `--services` flag to narrow scopes — the user can deselect
  individual permissions in Google's consent screen if desired.

**Question 2: "Does your Google account use Advanced Protection (hardware
security keys required to sign in)? If you're not sure, you probably don't
— it's something you would have explicitly enrolled in."**

- **No / Not sure** → Normal setup. Continue below.
- **Yes** → Their Workspace admin must add the OAuth client ID to the org's
  allowed apps list before Step 4 will work. Let them know upfront.

### Step 2: Create OAuth credentials (one-time, ~5 minutes)

Tell the user:

> You need a Google Cloud OAuth client. This is a one-time setup:
>
> 1. Create or select a project:
>    https://console.cloud.google.com/projectselector2/home/dashboard
> 2. Enable the required APIs from the API Library:
>    https://console.cloud.google.com/apis/library
>    Enable: Gmail API, Google Calendar API, Google Drive API,
>    Google Sheets API, Google Docs API, People API
> 3. Create the OAuth client here:
>    https://console.cloud.google.com/apis/credentials
>    Credentials → Create Credentials → OAuth 2.0 Client ID
> 4. Application type: "Desktop app" → Create
> 5. If the app is still in Testing, add the user's Google account as a test user here:
>    https://console.cloud.google.com/auth/audience
>    Audience → Test users → Add users
> 6. Download the JSON file and tell me the file path
>
> Important Hermes CLI note: if the file path starts with `/`, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:
> `The JSON file path is: /home/user/Downloads/client_secret_....json`

Once they provide the path:

```bash
$GSETUP --client-secret /path/to/client_secret.json
```

If they paste the raw client ID / client secret values instead of a file path,
write a valid Desktop OAuth JSON file for them yourself, save it somewhere
explicit (for example `~/Downloads/hermes-google-client-secret.json`), then run
`--client-secret` against that file.

### Step 3: Get authorization URL

```bash
$GSETUP --auth-url
```

The script prints the full OAuth URL to stdout. The agent must extract it and
send it to the user as a clickable link.

Agent rules for this step:
- The script outputs ONLY the URL (one line) — no JSON wrapper, no `auth_url` field.
- Send that exact URL to the user as a single line. It needs to be a clickable link.
- Tell the user that the browser will likely fail on `http://localhost:1` after approval, and that this is expected.
- Tell them to copy the ENTIRE redirected URL from the browser address bar.
- If the user gets `Error 403: access_denied`, send them directly to `https://console.cloud.google.com/auth/audience` to add themselves as a test user.

### Step 4: Exchange the code

The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
or just the code string. Either works. The `--auth-url` step stores a temporary
pending OAuth session locally so `--auth-code` can complete the PKCE exchange
later, even on headless systems:

```bash
$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED"
```

If `--auth-code` fails because the code expired, was already used, or came from
an older browser tab, run `$GSETUP --auth-url` again to get a fresh URL.

### Step 5: Verify

```bash
$GSETUP --check
```

Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.

### Notes

- Token is stored at `~/.hermes/google_token.json` and auto-refreshes.
- Pending OAuth session state/verifier are stored temporarily at `~/.hermes/google_oauth_pending.json` until exchange completes.
- If `gws` is installed, `google_api.py` points it at the same `~/.hermes/google_token.json` credentials file. Users do not need to run a separate `gws auth login` flow.
- To revoke: `$GSETUP --revoke`
- **Zeyd's setup:** Client secret stored at `/DATA/AppData/hermes/google_client_secret.json` (project: `amadeus-494810`, client ID `760929667815-...`). Token at `/DATA/.hermes/google_token.json` (profile-scoped). Gmail address: `ahmed.aytac@gmail.com`. All scopes granted (Gmail read/send/modify, Calendar, Drive, Contacts, Sheets, Docs). Do NOT re-ask for client secret path if these files exist.

## Usage

All commands go through the API script. Set `GAPI` as a shorthand:

```bash
GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
```

### Gmail

```bash
# Search (returns JSON array with id, from, subject, date, snippet)
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"

# Read full message (returns JSON with body text)
$GAPI gmail get MESSAGE_ID

# Send
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"

# Reply (automatically threads and sets In-Reply-To)
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"

# Labels
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
```

### Calendar

```bash
# List events (defaults to next 7 days)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z

# Create event (ISO 8601 with timezone required)
$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"

# Delete event
$GAPI calendar delete EVENT_ID
```

### Drive

```bash
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
```

### Contacts

```bash
$GAPI contacts list --max 20
```

### Sheets

```bash
# Read
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"

# Write
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'

# Append rows
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
```

### Docs

```bash
$GAPI docs get DOC_ID
```

## Output Format

All commands return JSON. Parse with `jq` or read directly. Key fields:

- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
- **Gmail send/reply**: `{status: "sent", id, threadId}`
- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
- **Calendar create**: `{status: "created", id, summary, htmlLink}`
- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
- **Sheets get**: `[[cell, cell, ...], ...]`

## Rules

1. **Never send email or create/delete events without confirming with the user first.** Show the draft content and ask for approval.
2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
5. **Respect rate limits** — avoid rapid-fire sequential API calls. Batch reads when possible.

## Pitfalls

- **`$GAPI gmail get` returns empty body for complex multipart emails**: The `_extract_message_body` helper in `google_api.py` only handles simple MIME structures. For multipart/mixed emails with HTML content, inline images, and PDF attachments (e.g. Gotogate booking confirmations), the body field is often empty. When this happens, drop to raw Python: fetch with `format="raw"`, decode the base64, use `email.message_from_bytes` to walk the parts, and extract `text/plain` or `text/html` payloads explicitly. For PDF attachments: find the `application/pdf` part, save the decoded data, then use `fitz` (PyMuPDF) to extract text. See `references/gmail-raw-extraction.md` for the full pattern.
- **Testing-mode token expiry (7 days)**: If the Google Cloud project is in "Testing" status (not published to Production), OAuth refresh tokens live only **7 days**. After that, every API call fails with `REFRESH_FAILED: invalid_grant: Token has been expired or revoked`. **Preferred fix: set up a daily cronjob** that runs `setup.py --check` to keep the token alive automatically — see `references/oauth-cronjob-refresh.md` for the complete setup. Manual fix: go through the re-auth flow (`--revoke` then `--auth-url`). Permanent fix: publish the app to Production in Google Cloud Console → OAuth consent screen. When re-authenticating manually, always `--revoke` first to clean up the dead token file — the old invalid token on disk can confuse the setup script even after a fresh auth.
- **Stale cronjob alerts after manual refresh**: If you manually re-authenticate after a token expiry, the cronjob may still fire a failure notification for its *previous* failed run. The notification is stale — ignore it if you've already refreshed the token and verified with `--check`. The cronjob's next scheduled run will succeed.
- **False REFRESH_FAILED from cronjob (token actually valid)**: The cronjob script may report `REFRESH_FAILED: invalid_grant: Token has been expired or revoked` even when the token is still valid and `--check` returns `AUTHENTICATED`. This is a transient error — the cronjob's `--check` call can fail due to network timing, rate-limiting, or a stale in-memory state in the script process. **Always verify with a manual `--check` before assuming the token is dead.** If manual check passes, the cronjob's next run will likely succeed. Only re-authenticate if manual `--check` also fails.
- **Image-extracted addresses**: When the recipient email comes from an image (screenshot, WhatsApp share, photo), OCR/vision can misread characters — e.g. `sanktmarien.at` read as `sanktmariaen.at`. Before sending, sanity-check the domain against known patterns (schools, companies, etc.) and confirm with the user if anything looks off. A wrong domain means the email goes into a black hole with no bounce.

## Re-Authentication When Token Expires or Goes Missing

The 7-day testing-mode expiry is documented under Pitfalls. Here's the exact recovery flow depending on what state you're in:

**Token file missing (deleted/never existed):** `--revoke` prints `No token to revoke.` — that's fine. Run `--client-secret /path/to/file.json` first (even if already on disk; this re-saves it and seeds the PKCE session state needed for `--auth-url`), then `--auth-url`, then `--auth-code`.

**Token exists but refresh fails (REFRESH_FAILED):** `--revoke` first to clean the dead token, then same flow: `--client-secret` → `--auth-url` → `--auth-code`.

## Calendar Multi-Calendar Support

`google_api.py` now supports querying ALL user calendars, not just `primary`.

**List all available calendars:**
```bash
$GAPI calendar calendars
# Returns: [{"id": "...", "summary": "Arbeit"}, {"id": "...", "summary": "Uni"}, ...]
```

**Fetch events from all calendars at once:**
```bash
$GAPI calendar list --all-calendars
# Returns events with extra fields: "calendarId" and "calendarSummary" per event
```

Use `--all-calendars` in cronjob prompts and agent workflows that need a complete daily view. The default `--calendar primary` still works for targeted queries.

Internal implementation: `_get_all_calendars()` fetches via `calendarList.list` API, then `_list_calendar_events()` iterates each calendar. Events are merged and sorted by start time.

## Flight Booking Workflow

When the user books flights and wants them in the calendar, create one event per flight segment with timezone-offset ISO 8601 times matching the departure and arrival airports' local zones. Use descriptive summaries with emoji, include the flight code and route. Always put the booking reference number in the description. For multi-city round-trips (e.g. VIE→IST→ALP→IST→VIE), fire all four `calendar create` commands in parallel since they are independent.

Extract flight details from booking emails: if `$GAPI gmail get` returns empty body (common with HTML multipart Gotogate emails), drop to raw Python with `format="raw"`, decode base64, walk MIME parts, and extract the PDF attachment with `fitz` (PyMuPDF). See references/gmail-raw-extraction.md for the full pattern.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `NOT_AUTHENTICATED` | Run setup Steps 2-5 above |
| `REFRESH_FAILED` | Token revoked or expired — see Re-Authentication section above |
| Token file missing, `--revoke` says "No token to revoke" | Normal — just run `--client-secret`, then `--auth-url`, then `--auth-code` |
| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3-5 |
| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
| Terminal tool blocks `&` in subject/body as backgrounding | False positive from the terminal sandbox — just re-run; it usually succeeds on the retry. If it persists, escape the `&` as `\&` or quote the entire `--body` string with single quotes instead of double quotes. |

## Revoking Access

```bash
$GSETUP --revoke
```