Report whether stored credentials are valid and loaded.

Returns dict with keys: valid (bool), expired (bool), scopes (list of granted OAuth scope URLs), and — only on failure — error (string describing the auth or config problem).

List unread forwarded emails in Hermes's inbox, newest first.

Returns a list of dicts, each with keys: id, thread_id, sender, subject, date, snippet.

Search emails in Hermes's Gmail using Gmail search syntax.

Supports the same operators as the Gmail search bar (e.g., from:alice, subject:invoice, after:2026/04/01).

Returns a list of dicts, each with keys: id, thread_id, sender, subject, date, snippet.

Fetch a single email by ID. Unwraps forwarded messages to extract the original.

Returns dict with keys: id, thread_id, original_sender, original_subject, original_body (plain text), in_reply_to (Message-ID header for threading), attachment_paths (list of local file paths in ~/.cache/hermes-google/).

Send a draft email from Hermes's account to the user's own inbox.

The destination is restricted to the configured user email; any other to value is rejected by the server. To reply to a thread, pass the in_reply_to value from mail_get.

Returns dict with key: id (sent message ID).

Mark a message as read in Hermes's inbox (removes the UNREAD label).

Returns dict with key: id (the message ID that was marked).

Archive a message in Hermes's inbox (removes the INBOX label).

Never call without user confirmation. Returns dict with key: id (the message ID that was archived).

List all calendars visible to Hermes (own calendar + any shared with Hermes).

Returns a list of dicts, each with keys: id (calendar ID), summary (display name), access_role (e.g., 'owner', 'writer', 'reader').

List events in a calendar within a time range, sorted chronologically.

calendar accepts 'user' (your personal calendar), 'hermes' (Hermes's primary calendar), or a full Google Calendar ID.

start and end must be RFC 3339 datetimes with timezone offset (e.g., '2026-04-24T00:00:00+08:00'). Bare dates are rejected by the API.

Returns a list of dicts, each with keys: id, title, start, end, attendees (list of email strings).

Create a calendar event. Requires user confirmation before calling.

calendar accepts 'user', 'hermes', or a full Google Calendar ID. start and end must be RFC 3339 datetimes with timezone offset.

Returns dict with key: id (created event ID).

Patch specific fields of a calendar event. Requires user confirmation before calling.

calendar accepts 'user', 'hermes', or a full Google Calendar ID. fields is a dict of Google Calendar event fields to update (e.g., {"summary": "New title", "location": "Room 3"}).

Returns dict with key: id (updated event ID).

Delete a calendar event. Requires user confirmation before calling.

calendar accepts 'user', 'hermes', or a full Google Calendar ID.

Returns dict with key: id (deleted event ID).

Search Drive files visible to Hermes by filename.

Optionally filter by MIME type (e.g., 'application/pdf', 'application/vnd.google-apps.spreadsheet').

Returns a list of dicts, each with keys: id, name, mime_type.

List children of a Drive folder by folder ID.

Returns a list of dicts, each with keys: id, name, mime_type.

Download a Drive file to the local cache directory.

The file is saved to ~/.cache/hermes-google/drive/<file_id>/. Use Claude Code's Read tool on the returned path to view the contents.

Returns dict with key: path (absolute local file path).

Upload a local file to Drive. Requires user confirmation before calling.

If folder_id is omitted, uploads to the configured default parent folder.

Returns dict with key: id (created Drive file ID).

Replace a Drive file's contents with a local file. Requires user confirmation before calling.

Returns dict with key: id (updated Drive file ID).

Move a Drive file into a different parent folder. Requires user confirmation before calling.

Returns dict with key: id (moved Drive file ID).

Delete a Drive file. Requires user to have used an explicit 'delete' verb.

Returns dict with key: id (deleted Drive file ID).