Hermes Agent
Hermes Agent with Google Drive and Docs: setup and fixes
Updated 17 November 2026
Hermes Agent ships with a Google Workspace skill that lets it search and manage files in Google Drive, read and write Docs and Sheets, and reach Gmail and Calendar too. You set it up once with your own Google Cloud project. This page covers the Drive, Docs and Sheets side: what the skill can do, how to authorise it, where the token lives and what the common errors mean.
Facts come from the Google Workspace page of the Hermes Agent 0.23.1 documentation and the bundled skill’s reference page in the same documentation, both read on 17 November 2026. Gmail is covered in Hermes Agent Gmail and Calendar in Hermes Agent Google Calendar.
What the skill can do with Drive, Docs and Sheets
The skill is bundled with Hermes and installed by default, at skills/productivity/google-workspace. The table below lists the Drive, Docs and Sheets commands documented in the bundled skill reference.
| Service | Documented commands |
|---|---|
| Drive | drive search, drive get, drive upload, drive download, drive create-folder, drive share, drive delete |
| Docs | docs get, docs create, docs append |
| Sheets | sheets create, sheets get, sheets update, sheets append |
You normally just ask Hermes in chat and it runs these. The examples below show what each one does.
- Search and inspect.
drive search "quarterly report" --max 10searches by text; adding--raw-querylets you pass a Drive query such as a MIME type filter.drive get FILE_IDreturns metadata for one file, including size, parents and owners. - Upload and download.
drive uploadtakes a local path and detects the MIME type, with optional--nameand--parent.drive downloadsaves binary files as they are. Google-native files are exported: Docs to PDF, Sheets to CSV, Slides to PDF and Drawings to PNG by default, or another type with--export-mime. That is an export only; the skill lists no command for editing Slides. - Organise and share.
drive create-foldermakes a folder, optionally inside a parent.drive sharesets a role of reader or writer for one email address, for anyone with the link, or for a whole domain. - Delete.
drive deletemoves the file to the trash by default, which can be reversed.--permanentskips the trash. - Docs.
docs getreads a Document, and with--tabone tab of a tabbed Doc.docs createmakes a new Doc, optionally with starting text.docs appendadds text to the end; on a Doc with several tabs,--tabis required. - Sheets. The skill can create a spreadsheet, read a range such as
Sheet1!A1:D10, write values to a range, and append rows. The values are passed as a JSON array of rows. For what that looks like in daily use, see AI agent for Google Sheets.
Set up the Google Cloud project and OAuth client
The documentation describes the setup as agent-driven: ask Hermes to set up Google Workspace and it walks you through each step. Underneath it runs a setup script, with a shorthand defined like this:
GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"The steps the skill gives you:
- Check first. Run
$GSETUP --check. If it printsAUTHENTICATED, you are already set up. - Create or select a Google Cloud project in the Google Cloud console.
- Enable the APIs. In the API Library, the skill lists Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API and People API. For this page, Drive, Sheets and Docs are the ones that matter.
- Create the OAuth client. Under Credentials, choose Create Credentials, then OAuth 2.0 Client ID, with application type “Desktop app”. Download the JSON file.
- Add yourself as a test user if the app is still in Testing, under Audience, Test users.
- Register the client file:
$GSETUP --client-secret /path/to/client_secret.jsonOne practical note from the skill: in the Hermes CLI, a message that is only a path starting with / can be mistaken for a slash command, so put the path inside a sentence instead.
Where the token is stored, and how to revoke it
The skill documents these locations and commands:
- The token is stored at
~/.hermes/google_token.jsonand refreshes automatically. - The exact authorisation URL is also saved to
~/.hermes/google_oauth_last_url.txt. - A temporary pending session, with the verifier for the code exchange, sits in
~/.hermes/google_oauth_pending.jsonuntil the exchange completes. - To remove access, run
$GSETUP --revoke.
That token file is what lets the agent act on your Drive, so treat it like a password: keep ~/.hermes private, and choose the narrowest --services set that covers what you need. The script shorthands use HERMES_HOME when it is set; the skill documents the credential and session files at the paths listed above.
The gws CLI or the Python fallback
The skill describes two execution backends. When the Google Workspace CLI, gws, is installed, the skill uses it for broader coverage. Otherwise it falls back to the bundled Python client implementation. Either way, the commands in this page go through the same wrapper script, scripts/google_api.py, with a shorthand:
GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
$GAPI drive search "quarterly report" --max 10The wrapper keeps Hermes’s existing JSON output, so results look the same on both backends. If gws is installed, the wrapper points it at the same ~/.hermes/google_token.json file, so you do not run a separate gws auth login.
Output is JSON throughout. Drive search returns id, name, mimeType, modifiedTime and webViewLink for each file. drive get returns file metadata, while sheets get returns a two-dimensional array of cell values. The documented Drive write operations, sheets create, docs create and docs append return a status with operation-specific fields.
Limits and rules the skill sets
The skill states a short list of rules, and the first one matters most for Drive:
- Confirm before changing things. The agent should never delete Drive files, share files, or modify Docs and Sheets without confirming with you first, showing the file IDs, content or share role it intends to use. Prefer the default trash over
--permanent. Read this as an instruction to the agent, not a technical lock, so check what you approve. - Check authorisation first. Run the check before first use, and go through setup if it fails.
- Respect rate limits. Avoid rapid-fire sequential API calls, and batch reads when possible.
- Scopes can change. Drive write and delete, and Docs create and edit, need re-authorisation if you set up an older version of the skill. See the next section.
The page lists no file-size limits, quota numbers or supported-format limits, so check Google’s own documentation for those rather than assuming.
Common errors and fixes
| Problem | Fix from the skill |
|---|---|
NOT_AUTHENTICATED | Run the setup steps: client secret, authorisation URL, code exchange, check. |
REFRESH_FAILED | The token was revoked or expired. Redo the authorisation steps. |
HttpError 403: Insufficient Permission | A scope is missing. Run $GSETUP --revoke, then authorise again with the services you need. |
AUTHENTICATED (partial) or “Token missing scopes” | Drive write and delete and Docs create and edit need re-authorisation: revoke, then authorise again to grant the upgraded scopes. |
HttpError 403: Access Not Configured | The API is not enabled. Enable it in the Google Cloud console. |
ModuleNotFoundError | Run $GSETUP --install-deps, then restart Hermes and rerun the authorisation. If Hermes is not importable, use hermes setup first rather than installing packages with pip. |
| Advanced Protection blocks authorisation | Your Workspace admin must allowlist the OAuth client ID. |
Run the setup script with Python from the Hermes environment, not an unrelated system Python, as the skill advises. For the install side, see install Hermes Agent.
Google Drive and Docs on ReadyHermes
We have not tested Hermes’s bundled Google Workspace skill, with your own Google Cloud OAuth client, on a ReadyHermes assistant, and the workspace has no screen for it. Do not follow the setup above there.
What ReadyHermes offers instead is an Apps section in the workspace. It lists apps including Google Drive, Google Docs, Google Sheets and Google Slides, alongside Gmail and Google Calendar. You press Connect, sign in to your own Google account on Google’s sign-in page, approve, and come back to see the app shown as connected. You can also ask in chat, for example “Connect my Google Drive”, and the assistant replies with a sign-in link. 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 permissions you are granting.
ReadyHermes runs your own Hermes Agent on our servers, always on, reachable from the chat apps you choose, on plans from US$3.99 a month with US$1 of AI included every month. The assistant should draft and ask before it changes your files, but check what you approve. For the wider picture see managed Hermes Agent hosting.
Questions
Can Hermes Agent read and edit Google Docs?
Yes, through the bundled Google Workspace skill. It can read a Doc with docs get, create one with docs create, and add text to the end with docs append. The skill lists no other Docs editing commands, and it says to confirm with you before modifying a Doc.
What can Hermes do with Google Drive files?
The skill documents search, metadata lookup, upload, download, creating folders, sharing and deleting. Deleting goes to the trash by default, and a permanent delete needs the --permanent flag. Google-native files are exported when downloaded, for example Docs to PDF and Sheets to CSV.
Do I need a Google Cloud project to use it?
Yes for this skill. You create or select a project, enable the APIs you need such as the Drive, Docs and Sheets APIs, create a Desktop app OAuth client, and authorise it. If you only need email, the documentation points to the himalaya skill, which needs no Google Cloud project.
Where does Hermes store the Google token?
At ~/.hermes/google_token.json, and it refreshes automatically. A temporary pending session is kept at ~/.hermes/google_oauth_pending.json until the code exchange completes, and you can remove access with the setup script's --revoke option.
How do I connect Google Drive and Docs on ReadyHermes?
Open the Apps section in the workspace, press Connect on Google Drive or Google Docs, sign in on Google's page and approve. You do not create a Google Cloud project yourself. We have not tested Hermes's own Google Workspace skill on ReadyHermes.