Excel AI Bridge — alpha

Install the add-in

Excel AI Bridge lets an AI assistant read and write a workbook you have open, while a privacy guard keeps the cells you mark hidden from it. Two halves have to be in place before any of that works: an add-in inside Excel, and a bridge program the AI talks to.

This tutorial installs the first half only. By the end you will have an AI Bridge tab on Excel's ribbon and nothing connected to it yet. Connecting an assistant is the next tutorial.

Nothing here is permanent. The whole install is one file copied into one folder, and uninstalling is deleting that file again — the last section shows you where.

If you downloaded a release bundle, it already contains a finished AIBridge.xlam, an official Python runtime under python\, and install.cmd. The download is about 45 MB (embeddable Python plus the packages the bridge needs). Follow the short path below — about five minutes, no Python of your own, no venv, no pip. Windows may show one Unknown publisher prompt for install.cmd; that is the downloaded script, not a program we compiled, and it is the only extra click. The from-source path is only for people building the add-in themselves.

Prerequisites

You need two things. Each has a check you can run, and each check tells you what you should see.

Windows. The bridge drives Excel through COM, a Windows-only interface. Excel for Mac and Excel for the web cannot be driven this way, and there is no version of this project for them.

Excel for Windows, the desktop app. Not the browser version. To prove Excel is installed and reachable over COM — which is what actually matters — open a terminal (press the Windows key, type cmd, press Enter) and paste this in one line: 

powershell -Command "$x = New-Object -ComObject Excel.Application; $x.Version; $x.Quit()"

You should see a version number such as 16.0. If you get a red error saying the COM class is not registered, Excel for Windows is not installed on this machine, and nothing below will work.

You do not need a Python install, a virtual environment, or the Trust Center setting Trust access to the VBA project object model for this short path. Those belong only to building from source. The zip already carries Python's official embeddable runtime.

Steps

  1. Download the bundle, unpack it, and confirm `AIBridge.xlam` is there.

Download https://bridge.ram.sh/download/<your invite>/latest.zip (the invite is the code you got with your access) — paste that address into a browser with your own code in place of <your invite>. If instead you have access to the project's repository, the same zip is attached to the latest GitHub release, and git clone works too (then use the from-source path below if you need to build).

Either way you end up with one folder holding a finished AIBridge.xlam next to README.md, build_addin.py, and the addin, src and docs subfolders. Put it wherever you keep your own files; this tutorial uses a folder called excel-ai-bridge under your user folder.

Open a terminal there: press the Windows key, type cmd, press Enter, then cd into the folder and list it. /d lets cd change drive as well as folder, which matters if the project is not on C:. 

   cd /d %USERPROFILE%\excel-ai-bridge
   dir

The terminal in the project folder, listing build_addin.py, requirements.txt, addin, src and docs

If dir does not list AIBridge.xlam, you may have unpacked a zip that contains another folder of the same name, or you may be looking at a source checkout that has not been built yet — in that case jump to Building from source. Everything after this depends on the terminal sitting in the folder that holds the add-in file.

  1. Run `install.cmd` from the unpacked folder.

Save your work first. Then, still in that terminal: 

   install.cmd

Windows SmartScreen may ask once because the script came from the download zip and is an Unknown publisher. That click is expected; there is no installer and no .exe of ours. Choose to run it.

install.cmd asks before it closes Excel, creates %APPDATA%\Microsoft\Excel\XLSTART if the folder may not exist yet, copies the prebuilt AIBridge.xlam there, and remembers this unpacked folder so Connect AI can start the embedded Python later. It prints installed: and the XLSTART path when it is done.

The terminal answering INFO: No tasks are running which match the specified criteria

The terminal showing installed: ...XLSTART\AIBridge.xlam and a dir listing of the XLSTART folder

There is no installer, no registry entry, and no setting changed anywhere in Excel — one file, in one folder, loaded in every Excel session from now on.

  1. Open Excel again, and find the AI Bridge tab.

Start Excel the way you normally do and open any workbook — the other tutorials use a throwaway one you can build later, but for this step a blank workbook is fine.

Along the ribbon's tab strip, after View and Help, there is now a tab labelled AI Bridge. Click it.

Excel with the AI Bridge tab selected, showing its Connection, Mark, View, Status and Support groups

Seeing this tab is the proof that the install worked, because the tab is drawn by the add-in itself. If it is missing, Excel did not load the file: re-check that AIBridge.xlam is in the XLSTART folder from step 2, and that you fully closed Excel before copying it there rather than after.

The tab's own label changes with the connection — it reads AI Bridge now, and becomes AI Bridge - connected once an assistant is attached, so you can see the state without leaving whichever tab you are working in.

  1. Read the ribbon before anything is connected.

The AI Bridge ribbon, with the Connect AI button, the Status lines and the three Support buttons (Report a bug, Ask for a feature, My reports)

Left to right, this is what you are looking at with no assistant attached:

Connection holds a single large button, and its label is the connection light. Right now it reads Connect AI: no bridge is running and this workbook has not asked for one. Press it and the add-in starts the embedded Python (python\pythonw.exe with src\server.py --broker from the unpacked folder), then attaches as usual. The tray icon shows the bridge running. The label changes to Waiting for AI until an assistant picks this workbook up. Two more labels exist for later: AI connected when a bridge holds this workbook, and Connect here when one is holding a different one. That last case — an assistant reading a workbook you did not mean — is the mistake this whole tab exists to make visible.

Mark and View are the privacy controls: Mark private hides the selected cells from the AI, Select all jumps to every private cell on the sheet, and Highlight private shades them. They do their job with nothing connected, and the third tutorial puts them to work.

Status is three plain-English lines, not icons, and with nothing attached they read AI not attached, No private cells, and `AI has not touched anything yet`. Once an assistant is working, the first line names the workbook it is reading, the second counts the cells you have marked private, and the third names the last thing the AI actually did — the tool, the range and the time. It is a receipt, not a promise: it reports what happened, after it happened.

Support holds Report a bug, Ask for a feature, and My reports. Each of the first two opens a short series of prompts; your answers are queued for the bridge and filed as an issue — an outward-facing action, not a no-op. My reports shows what you have reported from this computer and where each one stands (per machine, no account). No workbook contents are included. Nothing goes out until a bridge is running (at this point in the install you may not have one yet). They are on the ribbon so that the way to complain is visible from inside Excel rather than buried in a document.

Building from source

Use this path only if you are assembling the add-in from the VBA sources under addin\src — for example a git clone with no prebuilt AIBridge.xlam, or after you have changed the add-in code. Release-bundle customers can ignore this whole section.

From-source prerequisites

Python 3.11 or newer. In a terminal: 

py -3 --version

You should see Python 3.11.x or higher — this project is developed on 3.13. If you instead see 'py' is not recognized, try python --version. If neither works, install Python from <https://www.python.org/downloads/> and tick **Add python.exe to PATH** on the first screen of the installer. Close and reopen the terminal afterwards, or the new PATH will not be visible to it.

Trust access to the VBA project object model. Building from source uses a script that writes code into an Excel file, and Excel blocks that by default. In Excel: **File → Options → Trust Center → Trust Center Settings… → Macro Settings, then tick Trust access to the VBA project object model** and press OK. If you skip this, the build fails with *"Programmatic access to Visual Basic Project is not trusted"*. This setting only affects programs you run yourself; it does not lower the macro warnings you get on files from other people. Release-bundle customers who only copy the prebuilt AIBridge.xlam never need this setting.

From-source steps

  1. Create a private Python environment and install what the project needs.

A virtual environment is a folder of Python packages that belongs to this project alone. Using one means the install cannot break any other Python program on your machine, and deleting the folder undoes it completely. Work from the project folder (the same cd as in the short path above). 

   py -3 -m venv venv
   venv\Scripts\python.exe -m pip install -r requirements.txt

pip finishing with a Successfully installed line listing the project packages

The first command finishes in a few seconds and prints nothing. The second downloads eight packages — fastmcp, xlwings, pywin32, pytest, psutil, pystray, Pillow and pytest-timeout — and their dependencies. It prints a wall of Collecting … and Downloading … lines and can take a couple of minutes on a slow connection. The line that matters is the last one, beginning Successfully installed.

From here on, every command starts with venv\Scripts\python.exe rather than python. That is deliberate: it names the Python inside the environment you just made, so you never have to remember whether the environment is "activated".

  1. Build the add-in.
   venv\Scripts\python.exe build_addin.py
   dir build

The terminal showing built: ...\build\AIBridge.xlam and a dir listing containing AIBridge.xlam

The add-in is assembled from readable VBA text files under addin\src every time you build, so that the code going into Excel is code you could have read first. The script opens its own hidden copy of Excel to do the assembly, which is why it takes a few seconds and why the Trust Center setting above is required. It leaves your own Excel alone.

It prints one line, built: followed by a path, and dir build then shows the file itself, AIBridge.xlam, a few tens of kilobytes.

If this step fails with *"Programmatic access to Visual Basic Project is not trusted"*, go back and do the from-source Trust Center prerequisite. Nothing has been installed yet at this point — the file exists only inside the project folder.

Then install it the same way as the short path: close Excel, confirm with tasklist, create %APPDATA%\Microsoft\Excel\XLSTART if it does not exist, and copy build\AIBridge.xlam into that folder (or run venv\Scripts\python.exe build_addin.py --install, which rebuilds and copies for you). Reopen Excel and look for the AI Bridge tab.

What the bridge reports

On start and on a heartbeat the bridge sends installation metadata to the hosted broker so staff can see which invite is running: invite, bridge version, channel, last-seen, OS, Excel version, and daily tool-call counts. It never sends workbook content, cell values, or file names. privacy_report lists exactly those fields. Uninstall reports uninstalled.

Uninstalling

From the unpacked folder, with Excel closed (or let the script ask): 

uninstall.cmd

It unlocks any workbook a previous bridge left encrypted, then deletes AIBridge.xlam from XLSTART. Reopen Excel and the AI Bridge tab is gone. The unpacked folder is left in place; delete it yourself if you want the disk back.

Where next

Connect a Claude client — bind a workbook to the bridge and attach an assistant, so that Connect AI can turn into AI connected.

Next: connect.md Route C — the hosted broker, one URL pasted into claude.ai, no tunnel.