The Excel add-in

Download the bundle from https://bridge.ram.sh/download/<your invite>/latest.zip (the invite is the code you got with your access); it ships AIBridge.xlam prebuilt. To build it yourself:

venv\Scripts\python.exe build_addin.py

Builds AIBridge.xlam to build\AIBridge.xlam. To install it:

venv\Scripts\python.exe build_addin.py --install     # Excel must be CLOSED

This copies the built file into %APPDATA%\Microsoft\Excel\XLSTART, which is a trusted location, so it loads with no macro prompt. It loads in every Excel session; uninstall by deleting that one file with Excel closed.

Bind this workbook points the bridge at the active workbook. It works whether or not a bridge is running — the next one to start picks it up.

Private marks or unmarks the current selection. One press always leaves the selection wholly private; a second press leaves it wholly public.

Show private selects every private range on the sheet. Shade private shades them, per workbook, off by default.

Private ranges are stored as workbook AI_PRIVATE_* Names, so they travel with the file and survive with no bridge running. Each name is derived only from the sheet and the marked range's own address, so inserting, moving, or renaming a sheet, or marking and unmarking other ranges, never changes an existing private range's name or what it points at. The names are hidden, so they don't appear in the Name Box or the Paste Name dialog while you're building a formula.

The guard follows direct references across sheets: with Sheet1!C1 private, Sheet2!A1 = Sheet1!C1 and Sheet3!B2 = Sheet2!A1*2 are masked too, and a SUM over a range that contains C1 is masked with them. Marking still lists those cells and offers to mark them outright, so they stay covered if a formula is later pasted as a value.

Known limit: the guard reads formula text, so it does not follow INDIRECT, OFFSET arithmetic, references through a defined name, or values already copied elsewhere as constants.

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.

What every read tells you

Every read_range, analyze_sheet and get_active_selection reply carries:

• masked — the addresses whose values were replaced by [redacted], and

masking_note — one sentence saying so. Addresses only, never contents.

• suspicious_text — cells whose text looks like instructions, links or

commands (instruction-like, url-or-host, command-like). They are returned as data and flagged; nothing is hidden or blocked.

Every tool call is appended to %LOCALAPPDATA%\ExcelAIBridge\audit\<workbook-key>.jsonl with the caller's identity (the Google account that signed in, token:<id> for the bearer token, or local), the sheet and range, and how many cells were masked. privacy_report() returns the current private addresses and the recent audit.

When something goes wrong the AI writes the bug report, not you: it works out what happened, says it back to you in plain words, asks whether that is right, and then files the whole technical ticket itself — you never see a number or a link. AI Bridge → My reports shows what you have reported from this computer and where each one stands; see docs/report-a-bug.md.

write_cells refuses to replace a non-empty cell unless overwrite=true, and names what is there. Private cells are refused before that check and are never quoted.

Understanding a model

• trace(address, sheet, depth) — what feeds a cell (from formula text, across

sheets) and what it feeds (same sheet). Private cells appear by address with [redacted] values.

• analyze_workbook() — every sheet's map, which sheets reference which, and

how many private cells each holds.

• find_errors() — every #REF!, #DIV/0!, … with its direct precedents.
• format_cells([...]) — number format, bold, fill; journalled; undo_last_write

restores it. write_cells keeps a cell's own number format unless you pass number_format.

• get_instructions() — your standing instructions for this workbook, read

from %LOCALAPPDATA%\ExcelAIBridge\instructions\<workbook-key>.md. Edit the file by hand; no tool writes it.

Native operations

sort_range, apply_filter / clear_filter, add_conditional_format, add_validation_list. Each refuses a range that contains a private cell. Sorts, conditional formats and validations are journalled and reversed by undo_last_write; a filter changes no cell and is removed by clear_filter.

Connecting claude.ai

Run venv\Scripts\python.exe src\server.py --broker and paste the connector URL it prints into claude.ai — the hosted-broker route, no tunnel and no DNS; see Route C.

Using Skills with the bridge

claude.ai applies enabled Skills to any connector. Nothing to install here: enable the Skills you want in claude.ai and they apply to Excel AI Bridge conversations. Skills that suit a workbook: financial-model review, data cleaning, chart specification.

If a crash leaves a workbook encrypted

While a workbook is bound the bridge encrypts it on disk, so a program that opens the .xlsx behind the bridge's back gets nothing readable. The password comes off again when the bridge exits — but a hard kill, a crash or a power cut never gets to run that step, and the file is left as an .xlsx Excel will not open.

The next start puts it right by itself: before it binds anything, the bridge unlocks every workbook it holds a key for and finds still encrypted. Nothing is asked of you. That startup step is capped at two minutes in total, however many workbooks are waiting — anything it does not reach is left for the next start and named on screen, so recovery can never be the reason the bridge does not come up.

When the bridge will not start at all, run the same thing on its own:

venv\Scripts\python.exe src\recovery.py            # fix
venv\Scripts\python.exe src\recovery.py --dry-run  # report only

Excel AI Bridge recovery
  C:\books\Model.xlsx   encrypted, key on file        -> unlocked
  C:\books\Secret.xlsx  encrypted, you protected it   -> left alone
  C:\books\Open.xlsx    open in Excel                 -> left alone, in use
  C:\books\Old.xlsx     file missing                  -> stale key kept

--dry-run asks Excel which workbooks are open before it says what it would do, so it takes a moment longer than you might expect — and it says "would unlock" only about a workbook it really would.

It only ever touches a workbook it minted the password for. A file you protected yourself has no key here, so it is not merely skipped — recovery cannot see it, and it is left exactly as it is. Nor will it touch one another bridge has bound, one that is open in Excel, or a read-only file — and if it cannot tell (Excel will not answer, or the file that records which workbooks are bound is unreadable) it refuses rather than guesses, and says so.

The limitation, stated plainly. The passwords live in %LOCALAPPDATA%\ExcelAIBridge\keys\, encrypted with Windows DPAPI, which is bound to this Windows account on this machine. Copying those files to another computer, or restoring them after the profile is deleted or the OS is reinstalled, will not decrypt them — and a workbook stranded encrypted at that moment cannot be opened again. If you need a copy of a password somewhere else, take it out deliberately:

venv\Scripts\python.exe src\recovery.py --show C:\books\Model.xlsx

That is the only command that prints a password. --forget <path> drops a key you no longer want; nothing deletes one on its own, because it is the only copy.