Google Drive

Cosmo's Google Drive integration uses the drive.file OAuth scope, which grants access only to individual files you explicitly select via a built-in picker. Your entire Drive is never readable by Cosmo — you stay in control of exactly which documents are shared.

What Cosmo can do

Cosmo cannot list your whole Drive, browse folders, create, edit, or delete files. Folder selection is intentionally disabled in the Picker — drive.file scope only grants access to individually-picked files, not folder contents.

Connecting Google Drive

1. Open Integrations from the sidebar.
2. Find Google Drive and click Connect.
3. A Google sign-in window opens — sign in and grant the drive.file permission.
4. After connecting, click ▼ Files on the Google Drive card to manage your authorized files.

Adding files

1. Expand the Google Drive card (click ▼ Files).
2. Click Add files — a Google Picker window opens inside Cosmo.
3. Browse your Drive and select one or more files. You can select multiple files at once.
4. Click Select — the files appear in your authorized list immediately.

Cosmo restarts its Google Drive connection in the background so the newly selected files are available right away.

Removing files

1. Expand the Google Drive card (click ▼ Files).
2. Hover over any file and click Remove.
3. The file is removed from Cosmo's access list immediately.

Removing a file from the list does not delete it from Google Drive.

Using Drive files in chat

Once files are authorized, just ask Cosmo:

"Summarize the Q3 report"
"What action items are in the meeting notes?"
"Compare the two spreadsheets I shared"

Cosmo automatically calls list_authorized_files to discover what's available, then reads the relevant content.

Migrating from an older connection

If your Google Drive card shows a "Your Google Drive connection needs to be updated" banner, your connection was created before the drive.file scope migration (COS-56). The older drive.readonly scope is no longer supported.

To migrate:

1. Click Disconnect on the Google Drive card.
2. Click Connect and sign in again — grant the drive.file permission when prompted.
3. Click Add files to re-authorize the files you want Cosmo to access.

Your files in Google Drive are not affected; only Cosmo's access needs to be re-established.

Troubleshooting

"No files have been shared with Cosmo yet"
You haven't added any files. Expand the Google Drive card and click Add files. Alternatively, Cosmo will prompt you with an Add files button directly in chat when it detects no files are authorized.

"File could not be found in Google Drive"
The file was deleted, moved to Trash, or its sharing permissions changed since you added it. Check if it still exists in your Drive, then remove and re-add it via Add files.

Cosmo says it can't read my PDF
Cosmo attempts PDF text extraction automatically. If it fails (encrypted, scanned image, or malformed PDF), convert the PDF to a Google Doc first: open it in Google Drive, choose File → Open with → Google Docs, then add the resulting Google Doc via the Picker.

Files added before a recent update aren't working
Earlier versions of the Google Drive connector required a setup step (setAppId) that is now fixed. Remove affected files and re-add them via the Picker — they'll work correctly after re-selection.

Picker doesn't open / shows a blank screen
Ensure MAIN_VITE_GOOGLE_PICKER_API_KEY and MAIN_VITE_GOOGLE_APP_ID are set in your environment. See the self-hosted configuration guide below.

Self-hosted setup

If you run your own Cosmo deployment, you need two extra values in packages/desktop/.env:

# Google Picker API key — create in Google Cloud Console
# Restrict it to "Google Picker API" only
MAIN_VITE_GOOGLE_PICKER_API_KEY=your_api_key_here

# Google Cloud project number — find it in Cloud Console → Project info
# Required for drive.file scope: without this, selected files return 404
MAIN_VITE_GOOGLE_APP_ID=123456789012

The project number is the numeric prefix of your OAuth client ID (e.g. 123456789012 from 123456789012-abc.apps.googleusercontent.com).

Your Google Cloud project also needs the Google Picker API enabled in addition to the Drive API.

Revoking access

• Remove individual files: use ▼ Files → Remove on each file in the Integrations panel.
• Disconnect entirely: click Disconnect on the Google Drive card. Your OAuth tokens are deleted from Cosmo's server immediately.
• Revoke from Google: visit myaccount.google.com/permissions, find Cosmo, and remove access. This invalidates all tokens regardless of whether you've disconnected in the app.