@office-agents/bridge

Local development bridge for Office add-ins.

It lets a running add-in connect back to a local HTTPS/WebSocket server so external tools and CLIs can invoke real Office.js operations inside Excel, PowerPoint, or Word.

What it does

• keeps a live registry of connected add-in sessions
• exposes session metadata and recent bridge events
• lets you invoke any registered add-in tool remotely
• supports raw Office.js execution through each app's escape-hatch tool
• forwards console messages, window errors, and unhandled promise rejections

Start the bridge

pnpm bridge:serve
pnpm bridge:stop

Or run the bridge CLI through the root script:

pnpm bridge -- list
pnpm bridge -- exec word --code "const body = context.document.body; body.load('text'); await context.sync(); return body.text;"

Package-local equivalents:

pnpm --filter @office-agents/bridge start
pnpm --filter @office-agents/bridge run cli -- list

The server defaults to:

• HTTPS API: https://localhost:4017
• WebSocket: wss://localhost:4017/ws

It expects the Office Add-in dev cert files at:

• ~/.office-addin-dev-certs/localhost.crt
• ~/.office-addin-dev-certs/localhost.key

Override with:

• OFFICE_BRIDGE_CERT
• OFFICE_BRIDGE_KEY

CLI usage

office-bridge list
office-bridge inspect word
office-bridge metadata excel
office-bridge events word --limit 20
office-bridge exec word --code "return { href: window.location.href, title: document.title }"
office-bridge exec word --sandbox --code "const body = context.document.body; body.load('text'); await context.sync(); return body.text;"
office-bridge tool excel screenshot_range --input '{"sheetId":1,"range":"A1:F20"}' --out range.png
office-bridge screenshot word --pages 1 --out page1.png
office-bridge screenshot excel --sheet-id 1 --range A1:F20 --out range.png
office-bridge screenshot powerpoint --slide-index 0 --out slide1.png
office-bridge vfs ls word /home/user
office-bridge vfs pull word /home/user/uploads/report.docx ./report.docx
office-bridge vfs push word ./local.txt /home/user/uploads/local.txt

If the bridge is already running, pnpm bridge:serve / office-bridge serve will report the existing healthy server instead of failing with EADDRINUSE.

To stop the bridge from another shell:

office-bridge stop
# or
pnpm bridge:stop

Exec modes

office-bridge exec uses unsafe direct evaluation by default so development agents can access the full taskpane runtime, browser globals, and Office host objects without going through sandboxedEval().

Use --sandbox if you explicitly want to run through the app's existing raw Office.js tool (eval_officejs / execute_office_js).

Screenshot commands

Use screenshot for a simpler image-to-file workflow:

office-bridge screenshot word --pages 1 --out page1.png
office-bridge screenshot excel --sheet-id 1 --range A1:F20 --out range.png
office-bridge screenshot powerpoint --slide-index 0 --out slide1.png

The CLI strips image base64 from printed JSON output, so screenshot commands don't flood stdout or model context windows.

You can also save image-returning tool calls directly with --out:

office-bridge tool excel screenshot_range --input '{"sheetId":1,"range":"A1:F20"}' --out range.png

VFS commands

The bridge can move files between the add-in VFS and your local filesystem:

office-bridge vfs ls word /home/user
office-bridge vfs pull word /home/user/uploads/report.docx ./report.docx
office-bridge vfs push word ./notes.txt /home/user/uploads/notes.txt
office-bridge vfs rm word /home/user/uploads/notes.txt

vfs ls currently enumerates files via a VFS snapshot in the add-in runtime, so it is meant for development/debugging rather than high-performance file browsing.

Browser integration

Apps import startOfficeBridge() from @office-agents/bridge/client and pass the current AppAdapter.

The client auto-enables on localhost by default. You can override with:

• query: ?office_bridge=1
• query URL override: ?office_bridge_url=wss://localhost:4017/ws
• localStorage: office-agents-bridge-enabled
• localStorage URL: office-agents-bridge-url