Intro

This project is an Excel Web Add-in for automating repetitive spreadsheet work such as cleaning data, formatting sheets, and organizing workbook content. It combines a chat-driven React UI with Office.js, Clerk authentication, and a Convex backend so users can run Excel-focused workflows directly from the task pane.

Project Docs

Internal documentation for this project lives under docs/:

• Architecture Overview: docs/architecture.md
• Routing Guide: docs/routing.md
• Chat Tabs: docs/chat-tabs.md
• Messaging & Streaming: docs/messaging.md

Local Setup

1. Install prerequisites

   • Bun (used for scripts and dev server)

2. Install dependencies

   bun install

3. Install Office add-in development certificates

   bunx office-addin-dev-certs install

   The Office add-in development certificates are generated in ~/.office-addin-dev-certs/ (or C:\Users\{username}\.office-addin-dev-certs on Windows). These certificates are specifically designed for Office add-in development and are trusted by browsers for local HTTPS development.

4. Start Convex + Vite

   bun run dev

   The manifest points Excel to https://localhost:5173/index.html.

Environment Variables

• Create .env.local in the project root for browser-visible values:

  CONVEX_DEPLOYMENT=dev:your-deployment-name
  VITE_CONVEX_URL=https://your-deployment.convex.cloud
  VITE_CLERK_PUBLISHABLE_KEY=your-clerk-publishable-key
  VITE_OFFICE_CERT_DIR=/path/to/your/.office-addin-dev-certs

• Convex server variables can be set via bunx convex env set <KEY>=<VALUE>. These typically ship with the environment, but if you're onboarding a new machine double-check:

  CLERK_SECRET_KEY=sk_live_or_test_...
  CLERK_JWT_ISSUER_DOMAIN=https://your-domain.clerk.accounts.dev
  CLERK_WEBHOOK_SECRET=whsec_...
  
  # AI Provider Configuration
  AI_PROVIDER=openrouter  # or "google" or other providers
  OPENROUTER_API_KEY=or_live_or_test_...  # Required if AI_PROVIDER=openrouter
  GOOGLE_API_KEY=your-google-api-key  # Required if AI_PROVIDER=google

  CLERK_* values power Convex auth and webhooks. AI provider configuration (AI_PROVIDER, OPENROUTER_API_KEY, GOOGLE_API_KEY) authorizes the AI agent (see convex/ai/provider.ts).