GitHub - think41/extrasuite: Provide LLM agents a temporary service account to access whitelisted files in google drive

AI agents that safely read and edit your Google Workspace files — with a full audit trail.

ExtraSuite is terraform for google drive files. You can pull a google drive file (sheets/docs/forms/app scripts/slide), edit the files locally and push it back. Extrasuite will figure out what you changed, then create the right API calls to update the google drive file.

ExtraSuite gives agents its own identity that is distinct from the users. For each user, we create a 1:1 service account. The service acount has a unique "email like" identity. Users explicitly share the file or folder with this service account. This has two unique advantages:

• the agent can only read/comment/edit the files you explicitly share with it
• any changes made by the agent show up in version history as "Edited by Alice's agent" instead of "Edited by Alice"

ExtraSuite is built for small and mid-sized teams who rely on Google Workspace and want AI to help — without handing an agent the keys to your entire Drive. Individual users can also use it, but primary workflow is designed for teams.

The Pull → Edit → Push Workflow

This is the core of ExtraSuite. It works like Git for Google Workspace files.

uvx extrasuite sheet pull https://docs.google.com/spreadsheets/d/...
# Edit the local files
uvx extrasuite sheet push ./spreadsheet_id/

Why Declarative Beats Imperative

Most AI-driven automation is imperative: "call the Sheets API to set cell A1 to X, then call it again to set B2 to Y". This is fragile, hard to review, and impossible to sandbox meaningfully.

ExtraSuite is declarative: the agent edits local files to express the desired state, and push figures out what changed and translates it into the correct API calls.

What pull Produces

Each file type is converted into a folder of human- and LLM-readable files:

• Sheets → data.tsv, formula.json, format.json (factored CSS-like styles)
• Slides → content.sml per slide (SML: an HTML-inspired markup language)
• Docs → document.xml (semantic HTML-like XML), comments.xml
• Forms → a single form.json with all questions and settings
• Scripts → .js and .html files, one per script file

A .pristine/ directory captures the original state. diff compares current files against pristine and shows the pending batchUpdate request — no API calls needed. push applies it.

The Problem with "Give the AI Access to Google Drive"

Most AI tools request broad OAuth permissions. The agent can read any file, write any file, send email on your behalf — all at once, for as long as the token lives. You have no visibility into what changed, and if something goes wrong, you're left hunting through version history manually.

This is the lethal trifecta: an agent that can read sensitive data, take consequential actions, and communicate externally — all in a single compromised session. ExtraSuite eliminates this by design.

How ExtraSuite Works

A Dedicated Identity Per Employee

Every employee's agent gets its own Google service account (e.g. alice-agent@your-project.iam.gserviceaccount.com). The agent can only access files that have been explicitly shared with that service account — nothing else in your Drive is visible. All edits made by the agent appear in Google Drive version history attributed to "Alice's agent", not anonymously, not as Alice herself.

Typed Commands, Minimal Scope

The client sends a typed command to the ExtraSuite server along with the agent's stated reason for the operation. The server uses the command type to determine the minimum required credentials:

• Pull/push operations (Sheets, Docs, Slides, Forms, Drive) → a short-lived service account token, valid for 1 hour
• User-impersonating operations (Gmail, Calendar, Apps Script, Contacts) → a short-lived delegated access token scoped to exactly the required OAuth scope(s), valid for 1 hour

The client stores a session token locally (valid 30 days) to authenticate these requests without re-opening a browser. The session token never touches the Google API — it only authenticates against the ExtraSuite server. Short-lived Google access tokens are fetched on demand and never stored.

The command type, context fields, and the agent's reason are all logged server-side before any token is issued. The server can reject operations that fall outside the configured scope allowlist.

Local-Only Editing — No Arbitrary Code Execution

The agent's job is simple: edit files on disk and call pull/push. It does not execute arbitrary code against the Google API. This means you can configure your agent sandbox to:

• Whitelist only extrasuite pull and extrasuite push as allowed commands
• Allow outbound connections only to Google API endpoints and the ExtraSuite server

That eliminates the external communication leg of the lethal trifecta entirely.

What You Can Actually Do

Document Collaboration, Not Just Creation

Creating a document is easy. The hard part is everything after: multiple stakeholders, rounds of edits, comments that need responses, priorities that shift between drafts.

ExtraSuite lets agents participate in that ongoing collaboration:

• Read comments left by colleagues in a Doc and draft replies
• Incorporate reviewer feedback by editing the local document.xml and pushing
• Track which version introduced which change (it's in Drive's version history)
• Pull the latest state before each editing session so the agent always works from current content

Mini-Applications with Apps Script

Google Sheets + Forms + Apps Script is the de facto low-code platform for many business teams — expense approvals, onboarding checklists, inventory tracking. ExtraSuite lets agents build and maintain these:

• Pull a script project, add or modify trigger functions, push it back
• Wire a Form submission to an Apps Script that sends a confirmation email
• Update a Sheet with data from an external system and trigger a workflow
• Build the whole thing with an agent, or have an agent maintain an existing one

Bring in Context from Your Other Systems

Documents and spreadsheets don't exist in a vacuum. Your CRM, your ticketing system, your product database — that's where the real data lives. ExtraSuite handles the Google Workspace side so your agent can:

• Pull a sales pipeline sheet, update it with data from your CRM, push the changes
• Draft a status report doc using data from your project tracker
• Create a Form for collecting information and link it to a Sheet via Apps Script

Gmail Drafts and Calendar

For Gmail, the agent composes a draft (you review and send). For Calendar, the agent can view availability, create events, and RSVP — useful for scheduling workflows.

CLI Reference

The CLI is self-documenting. Every command has a --help flag that serves as the live reference. Run extrasuite <module> --help for workflow overview, and extrasuite <module> <command> --help for flags.

Modules

Each module has a --help page with workflow overview, directory structure, and key rules. The source for all help text lives in client/src/extrasuite/client/help/.

Core Commands (sheet / doc / slide / form / script)

Each of these commands exists on all five modules. The links below go to the sheet reference; the other modules follow the same structure.

Gmail Commands

Calendar Commands

Drive Commands

Getting Started

Prerequisites

1. Google Workspace that allows collaboration with external users
2. A Google Cloud project with editor access (does not need to be your organization's project)
3. ExtraSuite server deployed (see below)

Install the Client

Or install persistently:

uv tool install extrasuite

Deploy the Server

The ExtraSuite server manages service account creation and token issuance. Deploy it once for your whole team:

gcloud run deploy extrasuite-server \
  --image=ghcr.io/think41/extrasuite-server:latest \
  --service-account=extrasuite-server@$PROJECT_ID.iam.gserviceaccount.com \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="ENVIRONMENT=production,GOOGLE_CLOUD_PROJECT=$PROJECT_ID" \
  --set-secrets="GOOGLE_CLIENT_ID=extrasuite-client-id:latest,GOOGLE_CLIENT_SECRET=extrasuite-client-secret:latest,SECRET_KEY=extrasuite-secret-key:latest"

See the deployment documentation for full setup instructions.

Employee Onboarding

1. Employee logs into the ExtraSuite server and notes their agent's service account email
2. Runs extrasuite auth install-skill to give the agent its instructions
3. Shares specific Google files with the service account (editor or viewer, as needed)
4. Agent runs extrasuite <module> pull <url> and the workflow begins

Security Summary

Development

# Server
cd server && uv sync
uv run uvicorn extrasuite.server.main:app --reload --port 8001

# Client
cd client && uv sync
uv run pytest tests/ -v

# Tests and linting
cd server && uv run pytest tests/ -v && uv run ruff check .

License

MIT License — see LICENSE for details.