Hermes Agent
Hermes Agent and Google Calendar: setup step by step
Updated 17 November 2026
Hermes Agent ships with a Google Workspace skill that can read your calendar and create or delete events, using Google’s own sign-in. You make a small Google Cloud project, authorise it once, and the token then refreshes by itself. This page covers Google Calendar setup and the documented service sets, how to check it, and the errors you are most likely to meet.
Facts come from the Hermes Agent 0.23.1 documentation: the Google Workspace skill guide and the skill’s own reference page, plus the scheduled jobs page, all read on 17 November 2026.
What the skill does with a calendar
The skill is bundled with Hermes and installed by default. It covers Gmail, Calendar, Drive, Contacts, Sheets and Docs; this page uses only the calendar part. For calendars, the documentation lists three operations:
- List events. With no dates it returns the next 7 days, and you can give a start and an end. Each event comes back with
id,summary,start,end,location,descriptionandhtmlLink. - Create an event. It takes a summary, a start and an end, and optionally a location and attendees.
- Delete an event by its event ID.
The documentation shows these as commands run through a wrapper script, which the agent runs for you when you ask in chat. You do not normally type them yourself, although it helps to know what they look like:
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00
$GAPI calendar delete EVENT_ID$GAPI is a shorthand the skill defines for its API script in skills/productivity/google-workspace/scripts/google_api.py. The documentation does not list editing an existing event, so treat that as something to check rather than assume.
Before you start
The skill’s setup begins with two questions, and the answers change what you do:
- Which Google services do you need? If you only want email, the skill points you to the
himalayaskill instead, which uses a Gmail App Password and needs no Cloud project. For calendar, this skill is the one to use. - Does your Google account use Advanced Protection (hardware security keys required to sign in)? If so, your Workspace admin must add the OAuth client ID to the organisation’s allowed apps list before authorisation will work.
You also need Hermes installed, and a way to talk to it, whether the terminal or a chat app such as Telegram. If you have not installed it yet, start with how to install Hermes Agent. The documentation describes the setup as fully non-interactive and driven step by step by the agent, so it works from the CLI, Telegram, Discord or any other platform.
Create the Google Cloud project and OAuth client
This is a one-time job, which the skill estimates at about five minutes. You can ask Hermes to set up Google Workspace and it will walk you through it, or follow these steps from the skill’s instructions:
- Create or select a project in the Google Cloud console.
- Open the API Library and enable the Google Calendar API. The skill’s full list also names the Gmail, Drive, Sheets, Docs and People APIs; enable only the ones for services you will authorise.
- Open Credentials, choose Create Credentials, then OAuth 2.0 Client ID, and set the application type to Desktop app.
- If the app is still in Testing, add your own Google account as a test user under Audience, then Test users.
- Download the client secret JSON file and tell Hermes where it is.
One detail from the documentation matters in the CLI: if the file path starts with /, do not send it alone as a message, because it can be mistaken for a slash command. Put it in a sentence, such as “The JSON file path is: ~/Downloads/client_secret_....json”. Hermes then registers the file with the setup script:
$GSETUP --client-secret /path/to/client_secret.json$GSETUP is the skill’s shorthand for scripts/setup.py in the same folder. If you paste the raw client ID and secret instead of a file, the skill says the agent writes a valid Desktop OAuth JSON file for you and runs the same command on it.
Where the token is kept, and how to check it
The token is stored at ~/.hermes/google_token.json and refreshes automatically. While an exchange is unfinished, a temporary pending session is kept at ~/.hermes/google_oauth_pending.json. Anyone who can read the token file can act as that Google authorisation, so keep your Hermes home folder private, and do not copy it into a shared place.
To check that setup worked:
$GSETUP --checkIt should print AUTHENTICATED. The skill also runs this check before first use, and if it already reports AUTHENTICATED, setup is done. A partial result, AUTHENTICATED (partial), or a message that the token is missing scopes means the permissions you granted are not enough for what was asked.
For a real test, ask in chat what is on your calendar for the next week. A list of events with titles and times shows the whole path works. To remove access later:
$GSETUP --revokeSet a rule for yourself on writes. The skill’s instructions say the agent must never create or delete calendar events without confirming with you first, showing what will be done, and asking for approval. Calendar times must also carry a timezone offset such as -07:00, or use Z for UTC; a bare time like 2026-03-01T10:00:00 is ambiguous and is treated as UTC.
A daily agenda from a scheduled job
The skill includes a reference file, references/daily-brief.md, for a morning brief that combines schedule, conflicts, meeting preparation and urgent mail. Hermes loads it when you ask for a morning brief, meeting preparation, or what is on your calendar and what email needs attention. To get an agenda every morning without asking, create a scheduled job. The format is a schedule followed by a prompt. This uses a schedule form the scheduled jobs page shows:
hermes cron create "every 1d at 09:00" "Check my calendar for today and list my meetings, flagging any clashes"The Hermes gateway must be running for the job to execute. Jobs created from the command line save their output to local files unless you give a delivery target, so set one if you want the agenda in a chat. Because a scheduled run has nobody to answer a question, keep this one to reading the calendar; a job that creates or deletes events would hit the skill’s own rule about asking first. The full set of options, and how to list, pause and remove jobs, is on Hermes Agent cron jobs.
Common errors
The documentation’s troubleshooting table covers these cases. The same setup also serves Gmail and Drive; see Hermes Agent and Gmail and Hermes Agent and Google Drive for those.
| Problem | Fix |
|---|---|
NOT_AUTHENTICATED | Run the setup again: the client, the authorisation URL and the code exchange. |
REFRESH_FAILED | The token was revoked or expired. Redo the authorisation steps. |
HttpError 403: Insufficient Permission | A permission is missing. Run $GSETUP --revoke, then authorise again with the right services. |
HttpError 403: Access Not Configured | The API is not enabled. Enable the Google Calendar API in the Cloud console. |
ModuleNotFoundError | Run $GSETUP --install-deps, which syncs the Google extra, then restart Hermes and repeat the authorisation. |
Error 403: access_denied at sign-in | Add your account as a test user under Audience in the Cloud console. |
| Advanced Protection blocks sign-in | A Workspace admin must allowlist the OAuth client ID. |
If a plain-looking time gives an event at the wrong hour, check the timezone offset first, since a bare time is read as UTC.
Google Calendar on ReadyHermes
We have not tested Hermes’ bundled Google Workspace skill, with your own Google Cloud OAuth client, on a ReadyHermes assistant, and the workspace has no screen for it. ReadyHermes does it differently: the workspace has an Apps section that lists Google Calendar. You press Connect, sign in to your own Google account on Google’s own sign-in page, approve and come back, and the app shows as connected. You do not create a Google Cloud project or OAuth client yourself, and you can disconnect from the same section at any time. Read the consent screen to see what is being granted. You can also ask in chat, for example “Connect my Google Calendar”, and the assistant replies with a sign-in link.
The assistant runs on our servers and stays on, so a scheduled job fires while your own computer is off. You set one up by asking in plain words, for example “every weekday at 08:00 send me today’s agenda”, and the result arrives in the workspace chat or the chat app you connected. The workspace has no separate screen for schedules, so you ask the assistant to list, pause or remove them. Scheduled runs use AI like any other message. The assistant drafts and asks before acting, so check anything it proposes to add to your calendar. Plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. For the business-owner view of an assistant on your calendar, see AI calendar assistant.
Questions
What can Hermes Agent do with Google Calendar?
Through the bundled Google Workspace skill it can list events (the next 7 days by default, or a range you give), create events with a summary, start, end, and optionally a location and attendees, and delete an event by its ID. The documentation does not list editing an existing event.
How do I connect Hermes Agent to Google Calendar?
Create a Google Cloud project, enable the Google Calendar API, create an OAuth client of type Desktop app and download its JSON file. Hermes then registers it, gives you an authorisation URL, and exchanges the redirected URL or code you paste back. You can ask Hermes to set up Google Workspace and it walks you through each step.
Can I give Hermes access to calendar only?
The Hermes docs do not show a calendar-only option. The --services examples are email,calendar; calendar,drive,sheets,docs; and all. Pick the smallest documented set that includes calendar and read Google's consent screen before approving.
Where does Hermes store the Google token?
At ~/.hermes/google_token.json, where it refreshes automatically. A temporary pending session is kept at ~/.hermes/google_oauth_pending.json until the code exchange completes. Run the setup script with --revoke to remove access.
Can I use Google Calendar on ReadyHermes?
Yes, through a different route. The workspace's Apps section lists Google Calendar; you press Connect and sign in with your own Google account, with no Cloud project of your own. We have not tested the bundled Google Workspace skill on ReadyHermes.