google-workspace

Name: google-workspace
Author: adityahimaone

72stars5forks

How to install google-workspace?

adityahimaone/hermes-agent-rtk-caveman/google-workspace

$npx -y skills add adityahimaone/hermes-agent-rtk-caveman --skill google-workspace

Installs into the current project.

Summary

Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via Python. Uses OAuth2 with automatic token refresh. No external binaries needed — runs entirely with Google's Python client libraries in the Hermes venv.

Files · 1

View on GitHub

SKILL.md

1	# Google Workspace
2
3	Gmail, Calendar, Drive, Contacts, Sheets, and Docs — all through Python scripts in this skill. No external binaries to install.
4
5	## References
6
7	- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)
8
9	## Scripts
10
11	- `scripts/setup.py` — OAuth2 setup (run once to authorize)
12	- `scripts/google_api.py` — API wrapper CLI (agent uses this for all operations)
13
14	## First-Time Setup
15
16	The setup is fully non-interactive — you drive it step by step so it works
17	on CLI, Telegram, Discord, or any platform.
18
19	Define a shorthand first:
20
21	```bash
22	HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
23	GWORKSPACE_SKILL_DIR="$HERMES_HOME/skills/productivity/google-workspace"
24	PYTHON_BIN="${HERMES_PYTHON:-python3}"
25	if [ -x "$HERMES_HOME/hermes-agent/venv/bin/python" ]; then
26	PYTHON_BIN="$HERMES_HOME/hermes-agent/venv/bin/python"
27	fi
28	GSETUP="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/setup.py"
29	```
30
31	### Step 0: Check if already set up
32
33	```bash
34	$GSETUP --check
35	```
36
37	If it prints `AUTHENTICATED`, skip to Usage — setup is already done.
38
39	### Step 1: Triage — ask the user what they need
40
41	Before starting OAuth setup, ask the user TWO questions:
42
43	**Question 1: "What Google services do you need? Just email, or also
44	Calendar/Drive/Sheets/Docs?"**
45
46	- Email only → They don't need this skill at all. Use the `himalaya` skill
47	instead — it works with a Gmail App Password (Settings → Security → App
48	Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
49	Load the himalaya skill and follow its setup instructions.
50
51	- Calendar, Drive, Sheets, Docs (or email + these) → Continue with this
52	skill's OAuth setup below.
53
54	**Question 2: "Does your Google account use Advanced Protection (hardware
55	security keys required to sign in)? If you're not sure, you probably don't
56	— it's something you would have explicitly enrolled in."**
57
58	- No / Not sure → Normal setup. Continue below.
59	- Yes → Their Workspace admin must add the OAuth client ID to the org's
60	allowed apps list before Step 4 will work. Let them know upfront.
61
62	### Step 2: Create OAuth credentials (one-time, ~5 minutes)
63
64	Tell the user:
65
66	> You need a Google Cloud OAuth client. This is a one-time setup:
67	>
68	> 1. Go to https://console.cloud.google.com/apis/credentials
69	> 2. Create a project (or use an existing one)
70	> 3. Click "Enable APIs" and enable: Gmail API, Google Calendar API,
71	> Google Drive API, Google Sheets API, Google Docs API, People API
72	> 4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
73	> 5. Application type: "Desktop app" → Create
74	> 6. Click "Download JSON" and tell me the file path
75
76	Once they provide the path:
77
78	```bash
79	$GSETUP --client-secret /path/to/client_secret.json
80	```
81
82	### Step 3: Get authorization URL
83
84	```bash
85	$GSETUP --auth-url
86	```
87
88	This prints a URL. Send the URL to the user and tell them:
89
90	> Open this link in your browser, sign in with your Google account, and
91	> authorize access. After authorizing, you'll be redirected to a page that
92	> may show an error — that's expected. Copy the ENTIRE URL from your
93	> browser's address bar and paste it back to me.
94
95	### Step 4: Exchange the code
96
97	The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
98	or just the code string. Either works. The `--auth-url` step stores a temporary
99	pending OAuth session locally so `--auth-code` can complete the PKCE exchange
100	later, even on headless systems:
101
102	```bash
103	$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED"
104	```
105
106	### Step 5: Verify
107
108	```bash
109	$GSETUP --check
110	```
111
112	Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.
113
114	### Notes
115
116	- Token is stored at `google_token.json` under the active profile's `HERMES_HOME` and auto-refreshes.
117	- Pending OAuth session state/verifier are stored temporarily at `google_oauth_pending.json` under the active profile's `HERMES_HOME` until exchange completes.
118	- Hermes now refuses to overwrite a full Google Workspace token with a narrower re-auth token missing Gmail scopes, so one profile's partial consent cannot silently break email actions later.
119	- To revoke: `$GSETUP --revoke`
120
121	## Usage
122
123	All commands go through the API script. Set `GAPI` as a shorthand:
124
125	```bash
126	HERMES_HOME="

People who liked this also viewed

6 picks

Type

google-workspace

72stars5forks

View on GitHub

How to install google-workspace?

adityahimaone/hermes-agent-rtk-caveman/google-workspace

$npx -y skills add adityahimaone/hermes-agent-rtk-caveman --skill google-workspace

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Google Workspace
2
3	Gmail, Calendar, Drive, Contacts, Sheets, and Docs — all through Python scripts in this skill. No external binaries to install.
4
5	## References
6
7	- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)
8
9	## Scripts
10
11	- `scripts/setup.py` — OAuth2 setup (run once to authorize)
12	- `scripts/google_api.py` — API wrapper CLI (agent uses this for all operations)
13
14	## First-Time Setup
15
16	The setup is fully non-interactive — you drive it step by step so it works
17	on CLI, Telegram, Discord, or any platform.
18
19	Define a shorthand first:
20
21	```bash
22	HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
23	GWORKSPACE_SKILL_DIR="$HERMES_HOME/skills/productivity/google-workspace"
24	PYTHON_BIN="${HERMES_PYTHON:-python3}"
25	if [ -x "$HERMES_HOME/hermes-agent/venv/bin/python" ]; then
26	PYTHON_BIN="$HERMES_HOME/hermes-agent/venv/bin/python"
27	fi
28	GSETUP="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/setup.py"
29	```
30
31	### Step 0: Check if already set up
32
33	```bash
34	$GSETUP --check
35	```
36
37	If it prints `AUTHENTICATED`, skip to Usage — setup is already done.
38
39	### Step 1: Triage — ask the user what they need
40
41	Before starting OAuth setup, ask the user TWO questions:
42
43	**Question 1: "What Google services do you need? Just email, or also
44	Calendar/Drive/Sheets/Docs?"**
45
46	- Email only → They don't need this skill at all. Use the `himalaya` skill
47	instead — it works with a Gmail App Password (Settings → Security → App
48	Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
49	Load the himalaya skill and follow its setup instructions.
50
51	- Calendar, Drive, Sheets, Docs (or email + these) → Continue with this
52	skill's OAuth setup below.
53
54	**Question 2: "Does your Google account use Advanced Protection (hardware
55	security keys required to sign in)? If you're not sure, you probably don't
56	— it's something you would have explicitly enrolled in."**
57
58	- No / Not sure → Normal setup. Continue below.
59	- Yes → Their Workspace admin must add the OAuth client ID to the org's
60	allowed apps list before Step 4 will work. Let them know upfront.
61
62	### Step 2: Create OAuth credentials (one-time, ~5 minutes)
63
64	Tell the user:
65
66	> You need a Google Cloud OAuth client. This is a one-time setup:
67	>
68	> 1. Go to https://console.cloud.google.com/apis/credentials
69	> 2. Create a project (or use an existing one)
70	> 3. Click "Enable APIs" and enable: Gmail API, Google Calendar API,
71	> Google Drive API, Google Sheets API, Google Docs API, People API
72	> 4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
73	> 5. Application type: "Desktop app" → Create
74	> 6. Click "Download JSON" and tell me the file path
75
76	Once they provide the path:
77
78	```bash
79	$GSETUP --client-secret /path/to/client_secret.json
80	```
81
82	### Step 3: Get authorization URL
83
84	```bash
85	$GSETUP --auth-url
86	```
87
88	This prints a URL. Send the URL to the user and tell them:
89
90	> Open this link in your browser, sign in with your Google account, and
91	> authorize access. After authorizing, you'll be redirected to a page that
92	> may show an error — that's expected. Copy the ENTIRE URL from your
93	> browser's address bar and paste it back to me.
94
95	### Step 4: Exchange the code
96
97	The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
98	or just the code string. Either works. The `--auth-url` step stores a temporary
99	pending OAuth session locally so `--auth-code` can complete the PKCE exchange
100	later, even on headless systems:
101
102	```bash
103	$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED"
104	```
105
106	### Step 5: Verify
107
108	```bash
109	$GSETUP --check
110	```
111
112	Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.
113
114	### Notes
115
116	- Token is stored at `google_token.json` under the active profile's `HERMES_HOME` and auto-refreshes.
117	- Pending OAuth session state/verifier are stored temporarily at `google_oauth_pending.json` under the active profile's `HERMES_HOME` until exchange completes.
118	- Hermes now refuses to overwrite a full Google Workspace token with a narrower re-auth token missing Gmail scopes, so one profile's partial consent cannot silently break email actions later.
119	- To revoke: `$GSETUP --revoke`
120
121	## Usage
122
123	All commands go through the API script. Set `GAPI` as a shorthand:
124
125	```bash
126	HERMES_HOME="

People who liked this also viewed

6 picks

Type