Pi for Excel

Open-source, multi-model AI sidebar add-in for Microsoft Excel. Powered by Pi.

Pi for Excel gives you a conversational AI assistant that can read, write, and format your spreadsheets — directly from an Excel sidebar panel. Bring your own API key or OAuth login for Anthropic, OpenAI, Google Gemini, or GitHub Copilot.

Features

Core spreadsheet tools — 16 built-in tools that the AI can call to interact with your workbook:

Tool	What it does
get_workbook_overview	Structural blueprint — sheets, headers, named ranges, tables, charts, pivots
read_range	Read cells in compact (markdown), CSV, or detailed (with formatting) mode
write_cells	Write values/formulas with overwrite protection and auto-verification
fill_formula	AutoFill a formula across a range (relative refs adjust automatically)
search_workbook	Find text, values, or formula references across all sheets
modify_structure	Insert/delete rows/columns, add/rename/delete/hide sheets
format_cells	Apply formatting — fonts, colors, number formats, borders, named styles
conditional_format	Add or clear conditional formatting rules
trace_dependencies	Trace formula lineage (precedents upstream or dependents downstream)
explain_formula	Plain-language formula explanation with cited cell references
view_settings	Gridlines, headings, freeze panes, tab color, sheet visibility
comments	Read, add, update, reply, resolve/reopen cell comments
workbook_history	List/restore automatic in-between-saves backups for workbook mutations
instructions	Persistent user-level and workbook-level guidance for the AI
conventions	Configurable formatting defaults (currency, negatives, zeros, decimal places)
skills	Bundled Agent Skills for task-specific workflows

Multi-model support — use any supported provider; switch models mid-conversation:

• Anthropic (Claude) — API key or OAuth
• OpenAI / OpenAI Codex — API key
• Google Gemini — API key
• GitHub Copilot — OAuth

Session management — multiple session tabs per workbook, auto-save/restore, session history, /resume to pick up where you left off.

Auto-context injection — the AI automatically receives the workbook blueprint, your current selection, and recent cell changes before every turn. No need to manually describe what you're looking at.

Workbook recovery — automatic checkpoints before every mutation. One-click revert from the sidebar if something goes wrong.

Formatting conventions — define your house style once (currency symbol, negative style, decimal places) and the AI follows it automatically.

Slash commands — /model, /login, /settings, /rules, /extensions, /integrations, /export, /compact, /new, /resume, /history, /shortcuts, and more.

Extensions — install sidebar extensions (mini-apps) from chat. The AI can generate and install extension code directly via the extensions_manager tool. Extensions run in an iframe sandbox by default.

Integrations — opt-in external tool integrations:

• Web Search (Brave Search) — look up external facts without leaving Excel
• MCP Gateway — connect to user-configured MCP servers for custom tool access

Feature-flagged capabilities (managed via /experimental):

• Tmux bridge — local terminal control from the sidebar
• Python / LibreOffice bridge — run Python scripts and convert files locally
• Files workspace write/delete gate — shared artifact storage across sessions (assistant built-in docs under assistant-docs/ are always available read-only)
• External skills discovery — opt-in loading of locally configured external SKILL.md sources
• Advanced extension controls — remote URL opt-in, permission enforcement, sandbox rollback, and Widget API v2

(Web Search + MCP are managed in /integrations.)

Install

1. Download manifest.prod.xml
2. Add it to Excel — see install guide for step-by-step instructions (macOS + Windows)
3. Click Open Pi in the ribbon
4. Connect a provider (paste an API key or sign in with OAuth)
5. Start chatting — try What sheets do I have? or Summarize my current selection

Developer Quick Start

Prerequisites

• Node.js ≥ 20
• mkcert — for local HTTPS (required by Office.js)

Setup

git clone https://github.com/tmustier/pi-for-excel.git
cd pi-for-excel
npm install

# Generate local HTTPS certs (Office.js requires HTTPS)
mkcert -install   # one-time CA setup
mkcert localhost   # creates localhost.pem + localhost-key.pem
mv localhost-key.pem key.pem
mv localhost.pem cert.pem

Run

npm run dev        # Vite dev server on https://localhost:3000

Then sideload the dev manifest into Excel:

macOS (Microsoft docs):

cp manifest.xml ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/

Then open Excel → Insert → My Add-ins → Pi for Excel.

Windows (Microsoft docs):

Open Excel → Insert → My Add-ins → Upload My Add-in → select manifest.xml.

The dev manifest points to https://localhost:3000. The production manifest (manifest.prod.xml) points to the hosted Vercel deployment.

Useful commands

Command	Description
npm run dev	Start Vite dev server (port 3000, HTTPS)
npm run build	Production build → dist/
npm run check	Lint + typecheck + CSS theme checks
npm run typecheck	TypeScript type checking only
npm run lint	ESLint
npm run test:models	Unit tests — model ordering
npm run test:context	Unit tests — tools, context, sessions, extensions, integrations
npm run test:security	Security policy tests — proxy, CORS, sandbox, OAuth
npm run proxy:https	CORS proxy helper for OAuth flows (default https://localhost:3003)
npm run validate	Validate the Office add-in manifest

CORS proxy helper

Some OAuth token endpoints are blocked by CORS inside Office webviews. If OAuth login fails:

1. Run npm run proxy:https (defaults to https://localhost:3003)
2. In Pi → /settings → Proxy → enable and set the URL
3. Retry login

API-key auth generally works without the proxy.

Architecture

Pi for Excel is a single-page Office taskpane add-in built with:

• Vite — dev server + production bundler
• Lit — web components for the sidebar UI
• pi-agent-core — agent runtime (tool loop, streaming, state management)
• pi-ai — multi-provider LLM abstraction (Anthropic, OpenAI, Google, GitHub Copilot)
• pi-web-ui — shared web UI components (message rendering, storage, settings dialogs)
• Office.js — Excel workbook API

Source layout

src/
├── taskpane/          # App init, session management, tab layout, context injection
├── taskpane.html      # Entry HTML (loads Office.js + taskpane.ts)
├── taskpane.ts        # Entry script
├── boot.ts            # Pre-mount setup (CSS, patches)
├── tools/             # 16 core tools + feature-flagged tools + registry
├── prompt/            # System prompt builder
├── context/           # Workbook blueprint cache, selection/change tracking
├── auth/              # OAuth providers, API proxy, credential restore
├── models/            # Model ordering + version scoring
├── ui/                # Sidebar component, tool renderers, theme CSS
│   └── theme/         # Design tokens, component styles (DM Sans + teal-green palette)
├── commands/          # Slash command registry + builtins
├── extensions/        # Extension store, sandbox runtime, permissions
├── integrations/      # Web Search + MCP Gateway integration catalog
├── skills/            # Agent Skills catalog + runtime loader
├── experiments/       # Feature flag definitions + toggle logic
├── workbook/          # Workbook identity (hashed), session association, coordinator
├── conventions/       # Formatting defaults (currency, negatives, dp)
├── rules/             # Persistent user/workbook rules store
├── compaction/        # Auto-compaction thresholds + logic
├── storage/           # IndexedDB initialization
├── files/             # Files workspace (read/list always on; write/delete feature-gated)
├── audit/             # Workbook change audit log
├── messages/          # Message conversion helpers
├── debug/             # Debug mode utilities
├── stubs/             # Browser stubs for Node-only deps (Bedrock, stream, etc.)
├── compat/            # Compatibility patches (Lit, marked, model selector)
└── utils/             # Shared helpers (HTML escape, type guards, errors)

scripts/               # Dev helpers — CORS proxy, tmux/python bridges, manifest gen
tests/                 # Unit + security tests (~50 test files)
docs/                  # Current docs (install/deploy/features/policy) + archive/ for historical plans
skills/                # Bundled Agent Skill definitions (web-search, mcp-gateway)
public/assets/         # Add-in icons (16/32/80/128px)

Key design patterns

• Tool registry as single source of truth — src/tools/registry.ts defines all core tool names and construction. UI renderers, input humanizers, and prompt docs all derive from it.
• Workbook coordinator — serializes mutating tool calls per-workbook to prevent concurrent writes from multiple session tabs.
• Auto-context — the workbook blueprint, selection state, and recent changes are injected before each user message so the AI always knows what it's looking at.
• Execution policy — each tool is classified as read/none or mutate/content|structure to determine locking and checkpoint behavior.
• Recovery checkpoints — mutations automatically snapshot affected cells before writing, enabling one-click rollback.
• Extension sandbox — untrusted extensions (inline code, remote URLs) run in an iframe sandbox by default; built-in/local modules run on the host.

Deployment

The production build is a static site deployed to Vercel. See docs/deploy-vercel.md for maintainer setup.

Users install by downloading manifest.prod.xml and uploading it in Excel — the manifest points to the hosted Vercel URL. Updates are automatic (close and reopen the taskpane).

Documentation

Doc	Description
docs/install.md	Non-technical install guide
docs/deploy-vercel.md	Hosted deployment (Vercel)
docs/extensions.md	Extension authoring guide
docs/integrations-external-tools.md	Web Search + MCP integration setup
docs/security-threat-model.md	Security threat model
docs/compaction.md	Session compaction (/compact)
src/tools/DECISIONS.md	Tool behavior decisions log
src/ui/README.md	UI architecture + Tailwind v4 notes

Credits

• Pi by @badlogic (Mario Zechner) — the agent framework powering this project. Pi for Excel uses pi-agent-core, pi-ai, and pi-web-ui for the agent loop, LLM abstraction, and session storage.
• whimsical.ts by @mitsuhiko (Armin Ronacher) — the rotating "Working…" messages are adapted from his Pi extension, rewritten for a spreadsheet/finance audience.

License

MIT © Thomas Mustier