Excel AI Bridge — alpha

Install the bridge and 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 install copies one file into Excel's startup folder and the bridge itself into a folder of its own under your AppData, and uninstalling — from Windows' Add or remove programs, like any other app — takes both away again. The last section shows you where.

If you downloaded a release bundle, it already contains a finished AIBridge.xlam, the bridge itself as one program, bridgehost.exe, and install.cmd. The download is about 81 MB, because bridgehost.exe carries its own copy of the .NET runtime. Follow the short path below — about five minutes, with nothing else to install first. Windows shows one prompt, **Open File - Security Warning for `install.cmd` (publisher Unknown publisher**), and nothing more. 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 anything else installed, or the Trust Center setting Trust access to the VBA project object model, for this short path. That setting belongs only to building from source. The zip already carries everything the bridge runs on.

Steps

  1. Download the bundle and unpack it.

You were given a link of the form https://bridge.ram.sh/download/<your invite>/latest.zip (the invite is the code you got with your access). Paste it into your browser's address bar and press Enter. The browser saves one file, excel-ai-bridge-<version>.zip, about 81 MB, in your Downloads folder. If instead you have access to the project's repository, the same bundle is attached to the latest GitHub release as excel-ai-bridge-<version>-cs.zip, without the invite.json the link adds.

When the download has finished, close the browser. Then open the folder the zip was saved to (your Downloads folder, unless you chose another) and double-click excel-ai-bridge-<version>.zip. Windows shows the zip's contents with an Extract all button on the ribbon; press it, then Extract in the dialog. It takes a few seconds. When it finishes a new window opens on the unpacked folder, Downloads\excel-ai-bridge-<version>, holding AIBridge.xlam, bridgehost.exe (the bridge and its tray icon, one file), install.cmd, install_ui.ps1, connect_ui.ps1, uninstall.cmd, AIBridge.ico, README-cs.txt, VERSION, invite.json (your invite, added by the download link), and the docs subfolder. You do not have to keep this folder. The install copies the bundle to a fixed place of its own, %LOCALAPPDATA%\ExcelAIBridge\releases\<version>, and runs from there; once the install says it is ready you can delete the unpacked folder and the zip with it.

If another archiver (7-Zip, WinRAR) opens the zip instead, use its Extract command to the same effect, or select the zip in the Downloads folder and use Windows' own Extract all from the ribbon.

If you do not see AIBridge.xlam in the unpacked folder, you may be looking at a source checkout that has not been built yet; in that case jump to Building from source.

  1. Double-click `install.cmd` in the unpacked folder.

Save your work in Excel first. Windows asks once: Open File - Security Warning, publisher Unknown publisher. That is Windows treating a script you downloaded as unsigned; there is no installer. Choose Run. That is the only Windows prompt: the install clears the download mark from every file it copies, so neither the bridge nor uninstall.cmd asks again.

A small window, Starting Excel AI Bridge, shows a progress bar while the script creates %APPDATA%\Microsoft\Excel\XLSTART if the folder does not exist yet, copies the prebuilt AIBridge.xlam there, copies the bundle to %LOCALAPPDATA%\ExcelAIBridge\releases\<version>, runs bridgehost.exe from there once so Windows can check it, and remembers that folder so Connect AI can start it later. When it says Excel AI Bridge is ready, press Open Excel. (If Excel was open, the window asks you to close it and double-click install.cmd again.)

Nothing here needs an administrator and no setting changes anywhere in Excel: one file in Excel's own startup folder, loaded in every session from now on, and one copy of the bridge under your own AppData. It does add one entry to Windows' **Add or remove programs list, "Excel AI Bridge", whose Uninstall** runs the uninstall.cmd below. (From a terminal, install.cmd in the unpacked folder does the same and returns at once.)

  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.

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.

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 bridge from the folder install.cmd installed it to, then attaches as usual. The tray icon shows the bridge running; if the icon is not next to the clock, click the ^ (Show hidden icons) arrow at the left end of the icons by the clock to find it. 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.

Private holds the privacy controls: Mark private hides the selected cells from the AI, Select all jumps to every private cell on the sheet, Highlight private shades them, and Hidden private keeps hidden rows and columns from the AI until you press it (it then reads Hidden readable). They do their job with nothing connected, and the third tutorial puts them to work.

AI changes holds Undo AI change and Undo all, which take back what the AI changed in this workbook, because Excel's own Undo does not cover the AI's changes. Both are greyed while there is nothing of the AI's to take back here, except that Undo AI change stays lit while it shows how your last undo went.

Status is three small buttons, each an icon and two words. While no bridge is running, as now, they read Not running: Connect AI (rest the pointer on it for the whole sentence), No private, and No edits; once a bridge runs with nothing attached, the first reads Not attached. Once an assistant is working, the first names the workbook it is reading (a long name ends in ...; rest the pointer on it for the whole name), the second counts the cells you have marked private, and the third says when the AI last read or changed this workbook. Click one for a card that says what it means; the Task pane says what the AI last did and where. It is a receipt, not a promise: it reports what happened, after it happened.

Assistant is one large button that names who is on the other end. With nothing attached it reads No AI; once an assistant connects it shows the model the assistant says it is, or Model unknown if it has not said, and a click shows the rest. A long model name ends in ... on the button; rest the pointer on it for the whole name.

Read-back is one large button whose label is how much the AI tells you after it changes your workbook: Off, Risky only or Every change. It starts on Auto, which follows what suits the connected model, so it reads Auto: followed by the level it picked for your model; click it to pick another.

Support holds Report a bug, Ask for a feature, and My reports. All three open one short form in your browser, served by the bridge on this computer — the questions the ribbon used to ask one at a time, on one page; what you send is filed as an issue — an outward-facing action, not a no-op. The same page lists what you have reported from this computer and where each one stands (per machine, no account, and no ticket numbers). No workbook contents are included. The page only exists while a bridge is running (at this point in the install you may not have one yet), and the buttons say so rather than failing quietly. They are on the ribbon so that the way to complain is visible from inside Excel rather than buried in a document.

Version is the last button on the tab, and its label says whether your copy is current: Up to date, Update ready when a newer release is out, One step left when an update needs one thing from you in Claude, or Versions differ until you restart Excel after an update. Click it for a card that says what to do, if anything, with a What's new button that opens the list of what changed in each release.

  1. Check which Google account is yours.

The bridge only lets in the Google account your seat names. That is what makes it your bridge rather than everyone's: the connector address is not a secret, so without that one address anyone who saw it could sign in with their own Gmail and read your workbook.

Your seat answers which Google account will use this bridge? - it is the address your invite was made for, and nothing on this computer adds or removes an account. The Account button in the ribbon's Account group opens the Account page. It shows your seat - its Google address, plan and state - and the broker's verdict on the last sign-in: allowed by your seat, or refused because that account is not the seat's, with the time in UTC. The same page switches account and signs out.

A bridge without a seat reads %LOCALAPPDATA%\ExcelAIBridge\allowed.json on this computer, but no page writes it. An empty list never means "anyone": it means nobody yet, and every sign-in is refused. Somebody signing in with another Google account is turned away; to let another person in, ask whoever gave you the invite for an invite in that person's name.

The Account button shows where the sign-in stands, with its own badge: Signed out, Signed in, Wrong account, Reconnect needed, Paused or No license. Once your license's plan is known it reads the plan instead - Alpha, Pro or Firm - beside the signed-in or signed-out badge. Hover it for the full story - who signed in, your license's plan and state, and what to do next. The tray icon says the same thing without opening anything - a green tile with a check while somebody is signed in, blue with … while nobody is, amber with ! just after a refusal, red with ✕ while the link is down, and a bare grey B while the AI Bridge is not running - and hovering it says the same in words. Its menu carries Allowed accounts..., Switch account and Sign out.

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

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

C# engine bundle

The bundle your download link serves is the C# engine's; a GitHub release attaches the same bundle as excel-ai-bridge-<version>-cs.zip. It carries one self-contained program, bridgehost.exe — the bridge itself, and also the tray icon it starts (bridgehost.exe --tray) — so nothing has to be unpacked and no .NET download is needed. The download is about 81 MB because the program carries its own copy of the .NET runtime.

You install it exactly the same way: unpack the zip and run `install.cmd` from the unpacked folder. It copies the same AIBridge.xlam into the same XLSTART folder, and runs the program once (bridgehost.exe --print-version). That last step is deliberate: Windows checks a program the first time it runs, and it happens here, while you are looking at the install, instead of on your first Connect AI. The install first clears the download mark from every file it copied, so no Windows protected your PC screen comes with it, and the tray starting at sign-in is not stopped by one either.

The install ends by starting the tray icon, and it starts again each time you sign in to Windows, before you open Excel. If the icon is not next to the clock, Windows has put it with the hidden icons: click the ^ (Show hidden icons) arrow at the left end of the icons by the clock to find it. Until you connect, the icon's menu reads Not running: press Connect AI in Excel. Connect AI on the AI Bridge tab starts bridgehost.exe from the folder the install recorded, the same icon changes to show the bridge, and the ribbon behaves as the rest of this tutorial describes.

Uninstalling is the same uninstall.cmd, which runs bridgehost.exe --recover and bridgehost.exe --report-uninstalled before it deletes AIBridge.xlam from XLSTART, and stops the tray starting at sign-in.

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, daily tool-call counts, and per-action outcome and timing counts (how many calls ended ok, refused, busy, timed out or in error, and two duration bucket bounds). It never sends workbook content, cell values, addresses, sheet names, or file names. Ask Claude for the bridge's privacy report and it lists exactly those fields. Uninstall reports uninstalled.

Uninstalling

Open Windows' Add or remove programs, find Excel AI Bridge and press Uninstall. That runs uninstall.cmd out of the installed folder; you can also run it yourself, with Excel closed (or let the script ask): 

%LOCALAPPDATA%\ExcelAIBridge\releases\<version>\uninstall.cmd

Add /y — uninstall.cmd /y, or set EXCEL_BRIDGE_UNINSTALL_YES=1 — and it closes Excel without asking, which is what an unattended run needs. /y also means the script never waits for a keypress at the end, so it exits on its own even when a launcher gives it no console; run by hand without /y, it still holds the window open until a key is pressed.

It unlocks any workbook a previous bridge left encrypted, deletes AIBridge.xlam from XLSTART, removes the Add or remove programs entry, stops any bridge still running out of the installed folder, and last of all deletes that folder — so nothing of the bridge is left on disk. That last step is handed to a detached window, which keeps trying for about twenty seconds: a scanner, or a tray that was just closed, can hold a file open for a moment after the script itself has finished. So the version folder can still be there — and briefly empty — for a few seconds after uninstalled is printed; it is gone within half a minute. Each step of the uninstall with the time it finished, when the folder removal started, each retry and when it ended, and what it did and to what are written to %LOCALAPPDATA%\ExcelAIBridge\uninstall-removal.txt, so a slow uninstall shows which step took the time. The note at %LOCALAPPDATA%\ExcelAIBridge\uninstall-incomplete.txt is written when that step starts and taken away again when the folder goes — so that a machine switched off mid-removal still says what it was in the middle of. It means the folder was really left behind only once that half minute has passed. Reopen Excel and the AI Bridge tab is gone.

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 claude.ai through the hosted broker — one URL pasted into claude.ai, no tunnel.