Google Sheets integration (agent-driven spreadsheets with rich formatting)

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.
• 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.

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.

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 /src/main/services/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 /src/main/ipc/sheets-handlers.ts exposes the rich data to the renderer. Zod-validated input: { spreadsheetId, range }.
3. Store — useSheetsStore in /src/renderer/src/stores/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 /src/renderer/src/features/sheets/cell-format-helpers.ts converts CellFormat into inline CSS properties (backgroundColor, color, fontWeight, fontStyle, fontSize, textAlign, justifyContent, width). The CellGrid component in /src/renderer/src/features/sheets/CellGrid.tsx applies these styles to each cell and uses dynamic column widths in the virtualizer.

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 /src/shared/types.ts.
• AppSettings — trustedSheets: TrustedSheet[] persisted in config.json. Zod schema in /src/shared/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 /src/renderer/src/features/settings/sections/sheets/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 /src/renderer/src/stores/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). /src/renderer/src/features/sheets/SpreadsheetList.tsx sorts by priority — trusted 0, pinned 1, recent 2 — and renders the Pinned header when any priority sheet is present; /src/renderer/src/features/sheets/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 /src/main/services/google/google-auth-service.ts — single flow, loopback HTTP redirect, encrypted refresh token. The Sheets AI service is /src/main/services/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: /src/main/ipc/sheets-handlers.ts (channels SHEETS_AI_CHAT, SHEETS_READ_RICH, plus non-AI list/CRUD endpoints). Settings flag: sheetsEnabled in /src/shared/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