Codumentor logo Codumentor

Google Workspace Plugin

Lets the assistant work in the signed-in user's Gmail, Calendar, Docs, Sheets, and Drive — search and read by default, and (after approval) send mail, manage events, and edit documents. Each user connects their own Google account; there is no shared instance credential.

It sits on top of the OAuth plugin, which stores tokens and runs the Google consent flow. Users connect from Settings → Extensions → Google Workspace; they never have to visit a separate "OAuth" screen.

Using it

Connect your Google account

The first time, Google has to be set up once for your Codumentor, see Google Cloud project below. Until then, the settings section says Google is not configured.

  1. Open Settings (gear icon) → Extensions → Google Workspace.
  2. Choose which products to grant, and at which level:

| Product | Read only | Broader grant |
|---------|-----------|----------------|
| Gmail | Search and read mail | Read & send — also send, draft, label, and trash (not permanent deletion) |
| Calendar | List calendars and read events | Manage events — also create, update, and delete events |
| Docs | Read document text | Read & edit — also create documents and edit text |
| Sheets | Read spreadsheet values | Read & edit — also create spreadsheets and edit values |
| Drive (file search) | Find Docs and Sheets by name or full text | (search only) |

  1. Click Connect. Google's consent screen opens in the browser. After you approve, Codumentor stores the grant for your user.
  2. You can later narrow or broaden those choices in the same settings section, or disconnect the account.

The assistant only receives tools that match the products and levels you granted. If you connect Gmail as read-only, it cannot send mail until you raise that level and reconnect.

The TUI has the same picker under Settings → Google Workspace.

Talk to the assistant

Once connected, ask in ordinary language, for example:

Read tools run without a prompt. Anything that sends mail, changes a calendar, or edits a Doc/Sheet asks for approval first (Allow once / Allow for this conversation / Create a rule / Deny), the same way a shell command does.

If you are not connected, or a needed product is missing, the tool returns a message pointing you back to Settings → Google Workspace — it does not call Google.

What the assistant can do

Gmail

ToolApprovalPurpose
gmail_searchnoneSearch or list messages (Gmail search syntax, e.g. from:alice is:unread)
gmail_get_messagenoneRead one message (headers, body, attachment list)
gmail_get_threadnoneRead a whole conversation
gmail_list_draftsnoneList saved drafts
gmail_list_labelsnoneList labels / folders
gmail_get_attachmentnoneDownload one attachment into the staging area so it can be copied into a repo — the bytes do not enter the chat
gmail_sendgmail.sendSend a new message, or send an existing draft
gmail_draftgmail.draftCreate or update a draft
gmail_delete_draftgmail.draftDiscard a draft
gmail_modify_messagegmail.modifyAdd/remove labels (read/unread, archive, star, move)
gmail_trash_messagegmail.trashMove a message to Trash, or restore it
gmail_manage_labelgmail.labelCreate, rename, or delete a label

Permanent Gmail deletion is not exposed.

Calendar

ToolApprovalPurpose
calendar_list_calendarsnoneList calendars the account can see
calendar_list_eventsnoneList events in a time window
calendar_get_eventnoneRead one event in full
calendar_create_eventcalendar.event.createCreate an event
calendar_update_eventcalendar.event.updateUpdate an event
calendar_delete_eventcalendar.event.deleteDelete an event

Drive, Docs, Sheets

ToolApprovalPurpose
drive_searchnoneFind Docs/Sheets (and other files) by name or full text
docs_get_documentnoneRead a Doc as compact text
docs_create_documentdocs.createCreate a Doc
docs_replace_textdocs.editReplace exact text matches
docs_insert_textdocs.editInsert text at an anchor
sheets_get_spreadsheetnoneSpreadsheet overview (tabs)
sheets_read_valuesnoneRead an A1 range
sheets_create_spreadsheetsheets.createCreate a spreadsheet
sheets_update_valuessheets.editWrite an A1 range
sheets_append_valuessheets.editAppend rows
sheets_clear_valuessheets.editClear an A1 range

drive_search is how the assistant finds a Doc or Sheet; the Docs/Sheets tools then open it by id. Drive access is read-only — the plugin does not upload, move, or share Drive files.

Who gets which half

Two gates, not one. target_agents (default main) decides whether the family is offered at all; write_target_agents (default main) then decides who gets the tools in the "Approval" column above.

The family default stays closed because these tools act on a real mailbox and calendar, and nobody reads a subagent's tool calls before they land. The second gate is what makes opening it a decision about reading: with target_agents: all, a research subagent can search mail and list events, and still cannot send, edit, trash, or delete anything. Set write_target_agents: all only if subagents should write too.

Configuration

Personal (community) install: both plugins are already switched on. There is nothing to add here; go straight to Google Cloud project.

For a custom configuration, load both plugins. This plugin's priority must be lower than OAuth's (3 vs 4) so Google is available when OAuth starts serving connect flows.

plugins:
  - module: codumentor.plugins.oauth
    class: OAuthPlugin
    priority: 4
    args:
      enabled: true

  - module: codumentor.plugins.google_workspace
    class: GoogleWorkspacePlugin
    priority: 3
    args:
      enabled: true

Connecting an account requires the oauth:manage permission, which the built-in power_user and admin roles have. Grant it to other roles if ordinary users should connect Google themselves.

The configuration loader automatically creates and persists auth.jwt_secret for token encryption; no manual secret setup is needed for a personal install (see OAuth). Localhost works without a public URL or api.external_url. For a remotely accessible deployment, set api.external_url to the externally reachable base URL.

Google Cloud project

Before anyone can click Connect, Google has to know about your Codumentor. You do that once, by registering it as an "app" in your own Google Cloud account. It costs nothing for this use and takes about ten minutes. You end up with two values, a client ID and a client secret, which you give to Codumentor.

The steps below assume the usual personal setup: Codumentor runs on your own computer and you open it at http://127.0.0.1:2638/app. If it runs on a server that others reach over the network, read Running Codumentor on a server first, because one address changes.

1. Create a project

  1. Open Google Cloud Console and sign in with the Google account you want the assistant to use.
  2. Click the project picker at the top of the page → New project. Any name works, for example Codumentor. Click Create and make sure the new project is selected.

2. Turn on the Google APIs

Open APIs & Services → Library, search for each of these, open it and click Enable:

You only need the ones for the products you plan to connect, but enabling all five does no harm.

3. Set up the consent screen

This is the page Google shows when you click Connect. Open APIs & Services → OAuth consent screen (newer consoles call it Google Auth Platform) and fill it in:

You can skip the optional fields (logo, domains, scopes). Codumentor asks for the scopes itself when you connect.

4. Create the client ID

  1. Open APIs & Services → Credentials (or Clients) → Create credentials → OAuth client ID.
  2. Application type: Web application. Name: anything.
  3. Under Authorized redirect URIs, click Add URI and paste exactly:

``
http://127.0.0.1:2638/oauth/callback/google
``

Copy it character for character: http, not https; 127.0.0.1, not localhost; port 2638; no slash at the end. Google compares this address literally, so http://localhost:2638/... counts as a different address and fails. (If you changed Codumentor's port, use your port instead of 2638.)

  1. Click Create. Google shows the Client ID (ends in .apps.googleusercontent.com) and the Client secret (usually starts with GOCSPX-). Keep this window open, or download the JSON, for the next step.

5. Give the two values to Codumentor

The simplest way is your personal settings file, config.yaml in your Codumentor settings folder (~/.codumentor/config.yaml; on Windows C:\Users\<you>\.codumentor\config.yaml). Open it in a text editor and add these lines at the end, with your own values:

plugins_overrides:
  - module: codumentor.plugins.google_workspace
    class: GoogleWorkspacePlugin
    args:
      client_id: "123456789012-abc123.apps.googleusercontent.com"
      client_secret: "GOCSPX-your-secret"

Keep the indentation exactly as shown (spaces, not tabs). If the file already has a plugins_overrides: line, add the - module: … entry under it instead of writing a second one. Use plugins_overrides:, not plugins:: a plugins: list in this file replaces the whole built-in list and switches off every other extension.

If you would rather keep the secret out of files, set two environment variables before starting Codumentor instead:

# Linux / macOS: add to ~/.bashrc or ~/.zshrc, then open a new terminal
export GOOGLE_OAUTH_CLIENT_ID="123456789012-abc123.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="GOCSPX-your-secret"
:: Windows: run once in a Command Prompt, then open a new one
setx GOOGLE_OAUTH_CLIENT_ID "123456789012-abc123.apps.googleusercontent.com"
setx GOOGLE_OAUTH_CLIENT_SECRET "GOCSPX-your-secret"

6. Restart Codumentor and connect

Codumentor reads the client ID and secret only when it starts. Stop it (Ctrl+C in its window, or close the window), start it again, then open Settings → Extensions → Google Workspace and click Connect.

If connecting does not work

What you seeWhat to do
Settings or a tool says Google is not configuredCodumentor did not find the client ID and secret. Check the spelling and indentation in config.yaml (or that the environment variables are set in the window you start Codumentor from), then restart.
Google shows Error 400: redirect_uri_mismatchThe redirect URI in step 4 does not match. Compare it character by character with http://127.0.0.1:2638/oauth/callback/google; the error page's details show the address Codumentor actually sent. Saving a change in Google can take a few minutes to apply.
Google shows Access blocked or "has not completed the Google verification process"Add your Google address under Test users (step 3).
Google warns "Google hasn't verified this app"Expected for an app you made yourself. Click Continue (or Advanced → Go to Codumentor).
You have to reconnect about once a weekGoogle expires the sign-in after 7 days while the consent screen's publishing status is Testing. Either reconnect when asked, or set the status to In production under OAuth consent screen → Audience. For an app only you use, Google then shows the "not verified" warning once at sign-in, and you click through it as above.
A Google API error says the API has not been used or is disabledEnable that API in step 2, wait a minute, and try again.

Running Codumentor on a server

Everything above holds, except the redirect URI. When people open Codumentor at another address, for example https://codumentor.example.com, set that address as api.external_url in the configuration and register <api.external_url>/oauth/callback/google in step 4:

api:
  external_url: "https://codumentor.example.com"

The redirect URI to register is then https://codumentor.example.com/oauth/callback/google. Without api.external_url, Codumentor always sends http://<api.host>:<api.port>/oauth/callback/google, by default http://127.0.0.1:2638/oauth/callback/google, which only works in a browser on the same machine. In a shared installation, each user still connects their own Google account; nobody shares a token.

If the client ID and secret are missing, the plugin still loads but does not offer Google: the tools tell the user Google is not configured, and Codumentor keeps running.

Parameters

ParameterTypeDefaultDescription
enabledbooltrueMaster on/off.
client_idstring$GOOGLE_OAUTH_CLIENT_IDOAuth client id.
client_secretstring$GOOGLE_OAUTH_CLIENT_SECRETOAuth client secret.
default_scopeslistGmail/Calendar/Docs/Sheets read-write + Drive read + openid/emailScopes requested when the user clicks Connect without changing the picker. The picker still offers every product/level.
filter_tools_by_scopebooltrueOnly offer tools whose scopes the connected account actually grants.
revoke_on_narrowbooltrueWhen the user drops a product or level, revoke the Google grant and re-consent so the removed access is gone upstream, not only locally.
target_agentsstringmainWho gets the tools: main, subagent, all, or a subagent role name. Default keeps this family off subagents entirely.
write_target_agentsstringmainSame values, applied to the editing tools only — so widening target_agents grants reads without also granting gmail_send.
authorize_url / token_url / userinfo_url / revocation_urlstringGoogle's public endpointsOverride only to point at a private Google-compatible IdP.

Read-only default grant

To have Connect request read access unless the user raises a product in the picker:

      default_scopes:
        - openid
        - email
        - https://www.googleapis.com/auth/gmail.readonly
        - https://www.googleapis.com/auth/calendar.readonly
        - https://www.googleapis.com/auth/documents.readonly
        - https://www.googleapis.com/auth/spreadsheets.readonly
        - https://www.googleapis.com/auth/drive.readonly

Notes

See also