Google Drive
Google documents, spreadsheets and presentations as context: reading, questions in comments, the report as a document, scope, sign-in options.
For a team, Google Drive is written context that is in neither the task nor the code: a specification in a document, a plan in a spreadsheet, decisions in a presentation. The integration lets the model read all of this when an answer needs it, takes questions right in the comments on a document, spreadsheet or presentation, and can leave the result as a document, not only as a comment.
Tools
| Tool | What it does |
|---|---|
search_files | searches documents, spreadsheets, presentations and folders by words — in the name and in the text: Drive itself does the search, across file contents |
get_file | reads a whole file: a document — as markdown, a spreadsheet — all sheets as tables, a presentation — as text, a folder — as a list of its contents; a text file — as is; together with its discussion |
list_folder | lists a folder’s contents — nested folders and files with their kind |
get_sheet | one sheet or a range of a spreadsheet (Budget, A1:D20) — when the spreadsheet is large and only part of it is needed |
get_comments | the file’s discussions: comment threads with replies, who wrote and when |
add_comment | a comment on a file or a reply in a thread |
create_document | a Google document from markdown — in a folder within the connection’s scope |
The first five only read and are available wherever the model is given connector tools — in “Ask” and in deep research. The two writing ones are not given to the model at any stage: the connector itself uses them when, at the platform’s command, it returns an answer as a comment or a research report as a new document — and only within the scope.
A document arrives as markdown, a spreadsheet as tables. A Google document is exported in one call to markdown — headings, lists, tables, code, links; the integration adds nothing and truncates nothing. A spreadsheet is read through the Sheets API sheet by sheet, each as a markdown table with the header from the first row; a thousand-row sheet stays a thousand-row sheet. A presentation arrives as the text of its slides. A binary file (an archive, a video) is named by the integration by its kind and size, rather than pretending to have read it.
Requests in comments
Everything described in “Tracker integrations” works
here too: @buff <question>, @buff research …, @buff task … or /ask, /research,
/task in a comment on a document, spreadsheet or presentation is a question, a research or
a task draft. The answer arrives in the same thread — as a reply to the comment; a question in a new
comment starts a new conversation.
The bot is addressed by mentioning its address — in Google Docs that is +address or @address,
and the suggestion fills in the name — by the account’s name or by the alias from the settings
(buff), written as a word in the text. Case does not matter.
A document has no code branch, so the answer is computed at the level of the development project — or space — the connection is bound to.
Research — as a document
The answer to /research does not go into a comment: in the folder of the document where the question was asked,
a new Google document with the report appears — the text itself, not a picture of text — and next to it
a PDF file. A reply with a link to the report and to the research in Buff arrives in the discussion thread.
The document is created only within the scope.
Scope
The connection lists roots — links or identifiers of folders and files. The bot works in them and in everything nested: a file counts as “in scope” if one of its parents is a root (folder → folder → document). Writing is limited the same way: you cannot reply, create a document or a comment outside the scope. Shared drives are always in view — a document on a shared drive is just as much yours as one in “My Drive”.
An empty list of roots means “everything open to the account on Drive”. For a service account these are the folders and files shared with it; for your own account — its whole Drive and everything shared with it. This differs from trackers, where an empty list means “nowhere” — the semantics are decided for each source separately.
The account’s permissions in Google are the outer boundary, the list of roots is the inner one; it is sensible to have both: share a folder with the service account, not your whole Drive.
Two ways to sign in
The integration accepts two kinds of credentials — the choice is in the connection form, and in both cases the connector issues the access tokens itself: Google issues them for an hour, and refreshing them is the connector’s job, not yours. The plugin sees neither the key nor the token.
A service account — for the team
A separate robot account in your Google Cloud project. You share folders with its address — as with a colleague — and the bot works under its own name: its comments are signed by it, not by one of the people. The connector signs a JWT with the account’s key and exchanges it for an access token.
- In the Google Cloud console create a project (or take an existing one) and enable the Google Drive API and the Google Sheets API in it.
- IAM & Admin → Service Accounts → create an account; it needs no roles in the project.
- On the account open Keys → Add key → JSON — a key file downloads. Its whole contents are the credentials for the connector.
- On Drive share the folders and files you need with the account’s address
(
name@project.iam.gserviceaccount.com) with the “Commenter” role for reading and replies, or “Editor” if you need report documents.
A document the service account creates in someone else’s “My Drive” folder belongs to it, not to the folder’s owner. On a shared drive this does not happen — files there belong to the drive. If reports should stay with the team, select a folder on a shared drive.
Your own account — for yourself
A personal Drive is connected under your own name: the bot reads everything you see and replies as you. You need your own OAuth client — Google does not provide a shared one, and it is created once.
- In the Google Cloud console enable the Google Drive API and the Google Sheets API.
- APIs & Services → OAuth consent screen: type “External”, add yourself to the test users. While the app is in testing mode, Google shows the “Google hasn’t verified this app” screen — for your own client this is normal, click “Continue”.
- APIs & Services → Credentials → Create credentials → OAuth client ID, type “Desktop app”. Copy the client ID and client secret — or download the client’s JSON file; the connector accepts it whole.
- In the connector choose the “sign in with your own account” method, paste them and save the connection.
- Click “Sign in”: Google opens, you give consent — on the consent screen tick access to Drive, the box is unticked by default — and Google returns the browser to the connector’s local page. Done — you are signed in, and the page shows whose name the connection works under. If you missed the box, the connectivity check says “insufficient authentication scopes”: click “Sign in again”.
The connector is on a server and the browser is on your laptop? Google still returns the browser to
the connector’s 127.0.0.1 address — the page will not open. Copy the address from the address bar of
this blank page (it contains the code) and paste it into the “address of the page the
source returned to” field on the connector’s page. The same sign-in, just by hand. Through an SSH tunnel to
the local page the return arrives by itself.
The refresh token is stored in the credentials file on your machine; while it is valid, you do not need to sign in again. You can revoke access in the Google account settings — the connection then reports it in Google’s words at the connectivity check.
Events — polling
Drive has no comment feed across all files, and Google’s push notifications require
a verified HTTPS domain, which the connector does not have. So requests are found by polling:
the integration goes round the documents in scope, a few per pass, and asks each for
comments changed since reading began. By default every 5 seconds: the interval is
a connection setting. The Drive API limit is 12,000 requests per minute per user, so
even a large scope fits with room to spare; the integration waits out 429 and 403 rateLimitExceeded
answers as Google asks.
Setup
| Field | Value |
|---|---|
| Drive API, Sheets API address | prefilled — no need to change it |
| Sign-in and token issuance addresses | prefilled — no need to change them |
Sign-in method for api | service account (JSON key) or sign in with your own account (OAuth) |
api credentials | the whole contents of the JSON key — or the client ID and client secret of your own OAuth client |
| Folders and files | links or identifiers of the roots, comma-separated; empty — everything open to the account |
| Other ways to address the bot | a short name, for example buff |
| Polling interval | seconds; empty — as the integration suggests, 5 |
The connectivity check says not “ok” but whose name the connection works under — a service account or a user account, with the address — how many roots are in scope and how many of them are actually available.
From the command line: connector install google-drive, then
connector instance set --plugin google-drive --version 1.0.0 --set roots=<link>,<link> --poll 5
and connector instance secret <connection> --secret api --kind service_account (the key comes
from standard input). For your own account — --kind oauth2 with JSON of the form
{"client_id":"…","client_secret":"…"}, then connector instance signin <connection> --secret api:
the command prints the sign-in address and accepts the return address.
What the integration does not do
- It does not edit existing documents, spreadsheets and presentations — it only reads them, writes comments and creates new documents within the scope.
- It does not copy or index Drive content to us: what a particular answer needed is read and goes into that answer’s context.
- It does not receive push notifications — requests are found by polling.
- It does not work with Gmail, Calendar or Forms — only with Drive, Docs, Sheets and Slides.
Notion
Notion pages and databases as context for answers: reading, questions in comments, the research report as a page, scope, webhook and polling.
Files on disk
Server folders and SMB network folders as context: Word, Excel, PowerPoint (2007+ and 97–2003), PDF and text — the glob, grep and read tools; read-only.