Omniscio

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

  1. 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.
  2. Enable Sheets. Settings → Google Sheets → toggle sheetsEnabled on. 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:

  1. A sheet with its own Trusted Sheets entry uses that entry, and no folder is consulted.
  2. 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.
  3. 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

  1. Open the spreadsheet in Omniscio's Sheets project to verify it loads correctly.
  2. Go to Settings → Google Sheets → Trusted Sheets → Add trusted sheet.
  3. Enter the Spreadsheet ID — the long string from the Google Sheets URL between /d/ and /edit (e.g., 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms).
  4. Enter a Label (e.g., "PLMS") — a friendly name shown in the settings list.
  5. Enter the Editable columns as comma-separated letters (e.g., "C, D"). These are converted to 0-based column indices internally.
  6. 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:

  1. Backend API — getSheetDataRich() in sheets-api-service.ts calls the Google Sheets API with spreadsheets.get({ includeGridData: true }) and a targeted fields mask to fetch only effectiveValue, formattedValue, effectiveFormat, and columnMetadata.pixelSize. It returns SheetDataRichResult containing CellRichValue[][] (cells with optional CellFormat) and ColumnMeta[] (column pixel widths).
  2. IPC channel — SHEETS_READ_RICH in sheets-handlers.ts exposes the rich data to the renderer. Zod-validated input: { spreadsheetId, range }.
  3. Store — useSheetsStore in sheets-store.ts calls SHEETS_READ_RICH in loadSheetData() and stores the result as cellData (rich cells) and columnWidths (column metadata). The store also holds trustedConfig (the active TrustedSheet | null) and exposes isColumnEditable(col) and setTrustedConfig().
  4. Grid rendering — buildCellStyle() in cell-format-helpers.ts converts CellFormat into inline CSS properties (backgroundColor, color, fontWeight, fontStyle, fontSize, textAlign, justifyContent, width). The CellGrid component in CellGrid.tsx applies these styles to each cell and uses dynamic column widths in the virtualizer. A filled cell with no foregroundColor gets an explicit text color from readableTextOn(): 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, via whiteTextContrast() in accent-contrast.ts); a fill that is not #rrggbb leaves the color to the theme. An explicit text color is never overridden.

Trusted sheets configuration

  • Types — CellRichValue (extends CellValue with optional CellFormat), ColumnMeta (carries widthPx), and TrustedSheet (carries spreadsheetId, label, editableColumns as 0-based column indices) are defined in types.ts.
  • AppSettings — trustedSheets: TrustedSheet[] persisted in config.json. Zod schema in ipc-schemas.ts validates each entry (max 50 sheets, column indices 0–702).
  • Store — isColumnEditable(col) returns true if the column is in the active trustedConfig.editableColumns, or if no trusted config is active and readOnly is false. startEditing(row, col) checks editability and either enters edit mode (editable column) or sets editBlockedAt (non-editable column, triggers the dialog).
  • Settings UI — SheetsSettings component 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.

Last verified 2026-10-06