Hermes Agent + Google Calendar for beginners: schedule and verify a follow-up

A 30-minute block is sitting in Google Calendar. The time and time zone are correct, and nobody has been added as a guest. The useful part is that Hermes did not stop after reporting completion. It read the event back from the calendar and showed what Google had actually stored.

This guide continues from setting up Hermes Agent and completing your first task. For the same verification habit in a read-only task, see checking five web pages and saving a receipt.

Who this guide is for

Imagine that an AI workshop has just ended. You want to reserve half an hour for the next decision, but you are not ready to invite anyone. Hermes can add the block, verify the result, and leave the next decision with you.

This guide assumes that Hermes is already installed. It does cover the technical work that must succeed before you ask the agent to schedule anything: installing Google Workspace CLI, authorizing Calendar through OAuth, and running a read-only terminal test. For the first write test, use a temporary secondary calendar rather than your primary calendar.

What you will do in 20–30 minutes

First, you will install Google Workspace CLI and connect it to the correct Google account. After a read-only test succeeds, you will create one calendar event with explicit fields. Hermes will then read back the calendar name, title, start, end, time zone, description, reminders, and guest count. Only after that check will you decide whether to keep, edit, or delete the event.

Before you start

Hermes must be installed on the same computer or server where gws will run. If it is not ready yet, start with setting up Hermes Agent and completing your first task.

You also need a Google account with access to Google Calendar. OAuth login is a one-time step where you choose the account and approve access yourself. Never send the OAuth file or exported credentials through an agent chat.

Part 1: install Google Workspace CLI

The Google Workspace CLI command is gws. The project recommends downloading a prebuilt binary from GitHub Releases. If you already have Node.js 18 or later, npm is the easiest route:

node --version
npm --version
npm install -g @googleworkspace/cli
gws --version

If node --version reports anything below 18, update Node.js or use the prebuilt binary for your operating system. If the terminal cannot find gws after the npm installation, open a new terminal and check that npm's global binary directory is in your PATH.

Google Workspace CLI is still pre-1.0 and is not an officially supported Google product. Check the current project README if an installation or authentication command has changed.

Part 2: authorize Calendar through OAuth

gws needs a Google Cloud project and an OAuth client. If Google Cloud CLI (gcloud) is already installed and signed in, the CLI can handle most of the setup:

gws auth setup
gws auth login -s calendar

The first command configures the project and APIs through gcloud. The second opens Google sign-in and limits the service picker to Calendar. Choose the account that owns the test calendar and approve only the Calendar access required for this workflow.

If you do not use gcloud, configure OAuth manually in Google Cloud Console:

1. Create or select a Google Cloud project.
2. Configure the OAuth consent screen. External in testing mode is sufficient for a personal test.
3. Add your Google account under Test users.
4. Create an OAuth client of type Desktop app.
5. Download the client file and save it as ~/.config/gws/client_secret.json on the computer that runs gws.
6. Run gws auth login -s calendar and complete sign-in in the browser.

If Hermes runs on a server without a browser, complete interactive login on a trusted computer, export the credentials, and transfer the file securely:

gws auth export --unmasked > credentials.json

Treat credentials.json like a password: restrict its file permissions, never commit it to Git, and do not paste it into a prompt. The environment variable must be available to the same user or service that runs Hermes.

Part 3: test the connection before Hermes can write

Run two read-only commands yourself:

gws auth status
gws calendar calendarList list --params '\{"maxResults":5\}' --format json

The first command should report a valid token. The second should return a calendar list from the correct account. Do not share the raw output publicly because it can contain email addresses and calendar IDs. If either command fails, fix the installation or OAuth connection rather than changing the agent prompt.

Check where the binary is installed as well:

command -v gws

The Hermes process must see the same path. This matters when Hermes runs as a Gateway or background service rather than in the same terminal.

Once the read test succeeds, open the working folder where you normally use Hermes and launch the terminal interface:

hermes

You can also use a private channel such as Telegram that is already connected to Hermes. Choose a named calendar that the agent is allowed to use. A temporary secondary calendar is useful for the first test because you can remove it without touching your primary calendar.

Write down these details before asking Hermes to act:

• The exact calendar name.
• The date and start/end time.
• The time zone, such as Europe/Stockholm.
• A short title and description.
• Whether reminders should be used.
• That the first run must have zero guests.

The Hermes Quickstart covers the basic interaction: give the agent a normal task, let it use the appropriate tools, and inspect the result.

Step 1: give Hermes a complete event card

Avoid a vague request such as adding something next Tuesday. The calendar name, date, and time zone should not be left for the agent to guess.

Copy this template and replace the brackets:

First check that gws --version and gws auth status succeed. If either fails, stop and explain the error without changing the calendar. Otherwise, create exactly one follow-up block in [calendar name]. Title: [title]. Date: [date]. Time: [start–end]. Time zone: Europe/Stockholm. Description: [goal and agenda]. Do not add guests, a meeting link, attachments, or reminders. After creating the event, read it back from Google Calendar and give me a receipt with calendar, title, start, end, duration, time zone, description, reminders, and guest count. Do not change anything else without asking.

Our test used the title Follow up on AI workshop, the time 10:00–10:30, and the description Goal: confirm the next step. Agenda: decision, owner, date. You do not need customer information or a real attendee.

If a field is still ambiguous, Hermes should ask before creating the event. A short follow-up question is better than a block in the wrong calendar.

Step 2: create the event once

Ask Hermes to perform one bounded calendar action and keep the resource identifiers private during the run. If the tool returns an unclear response, the agent should check whether the event already exists before trying again. A blind retry can create a duplicate.

Google Calendar requires a start and end when creating an event. The title, description, time zone, guests, and reminders are separate fields that need deliberate handling. This guide leaves guests out entirely, so the test does not start an invitation chain.

Source: Google Calendar API – Events: insert.

Step 3: read back what Google Calendar stored

A successful event creation shows that Google accepted a request. It is not the final check. Ask Hermes to fetch the stored event separately and compare the result with your event card.

A compact receipt can look like this:

• Calendar: the correct named test calendar.
• Title: Follow up on AI workshop.
• Start and end: 10:00–10:30.
• Duration: 30 minutes.
• Time zone: Europe/Stockholm.
• Description: exact match.
• Reminders: disabled, with no overrides.
• Guests: 0.
• Meeting link and attachments: absent.

Google treats creating an event and fetching it as separate operations. The second read provides the evidence for the receipt.

Source: Google Calendar API – Events resource.

The practical test behind this guide used Hermes Agent 0.20.5 and Google Workspace CLI 0.22.5. The CLI returns structured JSON that Hermes can inspect, but the project is pre-1.0 and describes itself as not officially supported by Google. Let the agent inspect current help rather than building the workflow around old commands.

Source: Google Workspace CLI on GitHub.

Step 4: decide what happens after the check

When every field matches, choose the next action. You can keep the block, correct one field and read it back again, or delete the event. Add guests, a meeting link, or other meeting details only as a separate explicit action after the review.

The division of responsibility stays simple: Hermes performs and verifies the bounded task. You decide whether the calendar entry should become an actual meeting invitation.

Common mistakes

• A relative date is used without an exact date or time zone.
• The calendar is chosen implicitly even though the account has several calendars.
• A chat message saying the task is complete is accepted without a separate fetch.
• The organizer is mistakenly counted as a guest.
• Default reminders are assumed to be off without checking the field.
• The same request is retried after an unclear response before checking the calendar.

Next step

Once a guest-free follow-up block works reliably, you can reuse the pattern for other clearly bounded calendar tasks. Add invitations only when you have a review and approval point for recipients, time, and content.

Want to connect an agent to Google Workspace with clear permissions, approval points, and run receipts? Hammer can help you build the first bounded integration through Tool Forge.