Google Sheets integration (agent-driven spreadsheets with rich formatting)
Omniscio's Google Sheets integration lets you view and edit Google Sheets directly inside Omniscio. The built-in Sheets virtual project renders spreadsheets with their native Google Sheets formatting — background colors, text colors, bold, italic, font size, horizontal alignment, and actual column widths — so the grid inside Omniscio looks like the real spreadsheet, not a plain-text table.
On this page
What it is
Omniscio's Google Sheets integration lets you view and edit Google Sheets directly inside Omniscio. The built-in Sheets virtual project renders spreadsheets with their native Google Sheets formatting — background colors, text colors, bold, italic, font size, horizontal alignment, and actual column widths — so the grid inside Omniscio looks like the real spreadsheet, not a plain-text table. Claude also gets ten Sheets tool-use calls inside any chat conversation, so you can ask in plain English ("read the first sheet of the Q1 budget and tell me total spend", "add a row with today's date and these values to my expenses sheet") and the agent decides which tool to call. Sheets shares the same single "Connect Google" OAuth as Calendar, Drive, and Gmail — one consent, all four integrations.
Where to find it
Connect Google at Settings → Google, turn Sheets on at Settings → Google Sheets, then open the built-in Sheets virtual project in the sidebar.
How it behaves
How to use it
Connecting and enabling
- Connect Google once. Settings → Google → Connect Google. A browser tab opens; approve the scopes for Calendar, Drive, Sheets, and Gmail. Omniscio catches the OAuth redirect on a loopback HTTP server, encrypts the refresh token via
safeStorage, and stores it. - Enable Sheets. Settings → Google Sheets → toggle
sheetsEnabledon. The OAuth scopes were already requested at connect time; this flag controls whether Omniscio actually sends Sheets requests at runtime.
Viewing spreadsheets with rich formatting
Open the Sheets virtual project in the sidebar. Select a spreadsheet from the list. Omniscio renders the sheet grid with formatting that matches Google Sheets:
- Background colors — colored cells display their actual background (default white is filtered out to keep the grid clean).
- Text colors — non-black text renders in its Google Sheets color.
- Readable text on colored cells — a colored cell whose text has no color of its own gets black or white text, whichever reads better on that fill, so it stays legible in the dark theme.
- Bold, italic — text weight and style are preserved.
- Font size — non-default sizes (anything other than 10pt) are rendered at their actual size.
- Horizontal alignment — LEFT, CENTER, and RIGHT alignment is applied to each cell.
- Column widths — columns render at their actual Google Sheets pixel width instead of a fixed 100px.
Moving around the grid with the keyboard. Arrow keys move between cells; Tab and Shift+Tab move right and left, the same as Google Sheets; F2 or typing starts an edit; Enter saves it and Escape cancels it. Press Escape on a cell that is not being edited to leave the grid: focus jumps to the next control after it, so a keyboard user is never stuck inside the sheet. Each cell tells screen readers about that key (aria-keyshortcuts="Escape"), and Tab inside the grid still moves between cells.
Previously, all cells were plain text at fixed-width columns. The backend now uses spreadsheets.get with includeGridData: true to fetch values and formatting in a single API call, rather than the old spreadsheets.values.get which returned raw values only. Default formatting (white background, black text, 10pt Arial) is filtered out to keep the data payload clean.
The spreadsheet list — ordering, pinning, and trusted auto-pin
The Sheets list shows your recently modified spreadsheets, but you can keep specific sheets at the top:
- Pin / unpin — hover a row and click the pin icon to pin a spreadsheet (on touch/mobile the icon is always shown). Pinned sheets sort above the unpinned, recently-modified ones; click the pin again to unpin.
- Trusted sheets are auto-pinned — any spreadsheet configured as a Trusted Sheet (see below) shows a solid pin with no unpin button (its tooltip reads "Trusted spreadsheet (auto-pinned)") and always sorts to the very top, above manually-pinned sheets. Trusted sheets are managed from Settings, not from this list.
- Ordering — the list is grouped trusted → pinned → recent. When any trusted or pinned sheet is present, a small Pinned header appears above the group.
- Always visible — trusted and pinned spreadsheets appear even when they fall outside your recent-activity window, so a sheet you rarely edit but rely on never drops off the list. Omniscio fetches each pinned/trusted sheet the recent list didn't already return and prepends it.
Asking the agent
In any Claude session, type natural-language requests. Ten tools are available: list spreadsheets, get spreadsheet metadata, read a range, update cells, create a new spreadsheet, add a sheet/tab, delete a sheet, insert rows, insert columns, and apply formatting. Results render as markdown tables; ranges and updates link back to the spreadsheet.
Trusted Sheets (column-level edit permissions)
What trusted sheets are
By default, double-clicking a cell in the Sheets grid shows a warning dialog about Apps Scripts and formulas before enabling editing. Trusted Sheets let you mark specific spreadsheets as safe and specify which columns are editable. For a trusted sheet, the editable columns unlock automatically with no warning dialog, while non-editable columns remain locked. Leave the column list blank and every column is editable — the same meaning the list has for an assistant's writes.
The same list is also what lets an AI change a spreadsheet for you. Ask Omniscio, or any session you
start, can read any spreadsheet your connected Google account can see, but it can change only a
spreadsheet on your Trusted Sheets list — and it cannot add one to that list itself. A change to
anything else comes back refused with the code SHEET_NOT_TRUSTED and a link straight to
Settings → Google Sheets → Trusted Sheets, so the assistant tells you which spreadsheet needs
approving instead of failing silently. Reading is never blocked. Creating a brand-new spreadsheet
needs no approval either — there is nothing to approve yet — and the Sheets chat can keep filling in
that same spreadsheet for as long as the chat you made it in stays open, so "make me a tracker and
write the headers" works in one go. That allowance is remembered only for that chat and only while
the app is running: clear the chat, open a different spreadsheet, or restart Omniscio and the sheet
is back to needing your approval, exactly like any other. That allowance carries data only: if the
chat tries to write a formula (=, +, @, or a - that is not a number) into a spreadsheet it
created, the write is refused, because a formula runs when the sheet is opened and could send your
data somewhere. Add the spreadsheet to the Trusted Sheets list when you want it writable by any
assistant — formulas included — and your entry, with its column limit, takes over at once.
Trusted folders (approve a whole folder once)
If your sheets live together in a Drive folder, you do not have to approve each one. Settings → Google Sheets → Trusted folders takes a Drive folder link (or its ID) and a label, and from then on every spreadsheet inside that folder is writable by an assistant — plus its subfolders if you leave Include subfolders on. Two more options sit on each entry: Editable columns (the same column limit a single sheet entry has) and Use trusted folders, the switch that turns the whole feature off without losing your entries. Sheets on the plain Trusted Sheets list keep working either way.
How it decides, in order:
- A sheet with its own Trusted Sheets entry uses that entry, and no folder is consulted.
- Otherwise the nearest trusted folder above the sheet decides. Sheets moved out of the folder stop being editable at once, because the folder is checked on every write rather than remembered.
- If the folder cannot be checked — no Drive answer, a slow answer, a Google sign-in that has not granted Drive folder access — the change is refused. It is never allowed by default.
Folder checks need one extra Google permission (drive.metadata.readonly), which Google classifies
as restricted — it is not on the set this app submits to Google for verification, so an ordinary
Google sign-in never asks for it. The one switch over it is the in-development Lab feature Trusted
Sheets folder checks (trustedSheetFoldersDriveScopeEnabled, off by default). While it is off,
folder entries grant nothing and a write to a sheet inside one is refused with a message saying so —
add the spreadsheet itself to the Trusted Sheets list instead. Turn the Lab feature on and the
request follows the folder entries: while you have any trusted folder, the ordinary Connect
Google asks for it too, so reconnecting never drops it silently. Until you grant it, a folder entry
is saved as Waiting for access — never active — and shows one Grant Google Drive folder
access click that takes you to the Google Account card. If a reconnect declines it, the entries go
back to waiting with that same click, so you are never left with a folder that looks approved while
every write into it is refused. With no folder entries the ordinary connection asks for nothing
extra. A connection that runs through a relay cannot grant it at all; those sheets need their own
Trusted Sheets entry.
An assistant that is refused gets the same plain answer either way (code SHEET_NOT_TRUSTED,
SHEET_FOLDER_UNCHECKED or SHEET_COLUMN_NOT_ALLOWED), with a link straight to the setting, and it
can ask you for many sheets and folders in one card instead of one card per spreadsheet.
Visual indicators
When a trusted sheet is open:
- Editable column headers are tinted green (
bg-green-50 text-green-700), signaling that those columns accept input. - Non-editable columns show reduced opacity and a default cursor (not the cell-edit cursor).
- The lock button in the sheet editor header shows the editable column letters (e.g., "C, D editable") instead of the generic "Locked" label.
- Double-clicking an editable column starts editing immediately — no confirmation dialog.
- Double-clicking a non-editable column shows a "Column not editable" message explaining that only the configured columns are editable, with a pointer to Settings.
How to set up a trusted sheet
- Open the spreadsheet in Omniscio's Sheets project to verify it loads correctly.
- Go to Settings → Google Sheets → Trusted Sheets → Add trusted sheet.
- Enter the Spreadsheet ID — the long string from the Google Sheets URL between
/d/and/edit(e.g.,1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms). - Enter a Label (e.g., "PLMS") — a friendly name shown in the settings list.
- Enter the Editable columns as comma-separated letters (e.g., "C, D"). These are converted to 0-based column indices internally.
- Click Add.
To remove a trusted sheet, click the trash icon next to it in the Settings list. A confirmation dialog prevents accidental deletion.
How it works
Rich formatting pipeline
The rich data path flows through these layers:
- Backend API —
getSheetDataRich()in sheets-api-service.ts calls the Google Sheets API withspreadsheets.get({ includeGridData: true })and a targetedfieldsmask to fetch onlyeffectiveValue,formattedValue,effectiveFormat, andcolumnMetadata.pixelSize. It returnsSheetDataRichResultcontainingCellRichValue[][](cells with optionalCellFormat) andColumnMeta[](column pixel widths). - IPC channel —
SHEETS_READ_RICHin sheets-handlers.ts exposes the rich data to the renderer. Zod-validated input:{ spreadsheetId, range }. - Store —
useSheetsStorein sheets-store.ts callsSHEETS_READ_RICHinloadSheetData()and stores the result ascellData(rich cells) andcolumnWidths(column metadata). The store also holdstrustedConfig(the activeTrustedSheet | null) and exposesisColumnEditable(col)andsetTrustedConfig(). - Grid rendering —
buildCellStyle()in cell-format-helpers.ts convertsCellFormatinto inline CSS properties (backgroundColor, color, fontWeight, fontStyle, fontSize, textAlign, justifyContent, width). TheCellGridcomponent in CellGrid.tsx applies these styles to each cell and uses dynamic column widths in the virtualizer. A filled cell with noforegroundColorgets an explicit text color fromreadableTextOn(): the mapper drops black text as default, so without it the cell would inherit the theme's text color — light text on a pale fill in the dark theme. It picks black or white by WCAG contrast against the fill (black contrast = 21 ÷ white contrast, viawhiteTextContrast()in accent-contrast.ts); a fill that is not#rrggbbleaves the color to the theme. An explicit text color is never overridden.
Trusted sheets configuration
- Types —
CellRichValue(extendsCellValuewith optionalCellFormat),ColumnMeta(carrieswidthPx), andTrustedSheet(carriesspreadsheetId,label,editableColumnsas 0-based column indices) are defined in types.ts. - AppSettings —
trustedSheets: TrustedSheet[]persisted inconfig.json. Zod schema in ipc-schemas.ts validates each entry (max 50 sheets, column indices 0–702). - Store —
isColumnEditable(col)returnstrueif the column is in the activetrustedConfig.editableColumns, or if no trusted config is active andreadOnlyis false.startEditing(row, col)checks editability and either enters edit mode (editable column) or setseditBlockedAt(non-editable column, triggers the dialog). - Settings UI —
SheetsSettingscomponent in SheetsSettings.tsx renders the add/remove interface. Column letters (A, B, C, ...) are converted to 0-based indices on save and back to letters for display.
Spreadsheet list ordering
fetchSpreadsheets() in sheets-store.ts is the single source for the list: it loads the recent spreadsheets (SHEETS_LIST), reads trustedSheets + pinnedSheetIds from settings in the same pass, then back-fills any trusted/pinned sheet missing from the recent results via SHEETS_GET and prepends them (this replaced the former standalone loadPinnedSheets action and its mount effect). SpreadsheetList.tsx sorts by priority — trusted 0, pinned 1, recent 2 — and renders the Pinned header when any priority sheet is present; SpreadsheetListItem.tsx derives isPinned/isTrusted from the store and renders trusted rows as a static (non-toggle) pin.
Agent tool-use path (unchanged)
Google OAuth lives in google-auth-service.ts — single flow, loopback HTTP redirect, encrypted refresh token. The Sheets AI service is sheets-ai-service.ts: ten tools (list_spreadsheets, get_spreadsheet, read_range, update_cells, create_spreadsheet, add_sheet, delete_sheet, insert_rows, insert_columns, format_cells) wrapping the googleapis npm package. They run inside a token loop — agent message → Claude returns tool_use → Omniscio executes via googleapis → result appended → repeat until stop_reason='end_turn' — with a circuit breaker that backs off on repeated API failures and per-account cost tracking. Errors return as tool results so the agent can recover. IPC handler: sheets-handlers.ts (channels SHEETS_AI_CHAT, SHEETS_READ_RICH, plus non-AI list/CRUD endpoints). Settings flag: sheetsEnabled in types.ts.
Related
- INDEX.md — full library index
- google-integrations.md — umbrella doc for Calendar + Drive + Sheets, shared OAuth
- drive-integration.md — sibling Google integration with similar agent-driven UX
- gmail-integration.md — Gmail uses the same Google OAuth flow
Last verified 2026-10-06