Hermes for Excel

An agentic AI add-in for Microsoft Excel. Hermes doesn't just answer questions — it executes actions on your live workbook in a closed loop: it reads, writes, formats, charts, looks at the results, and iterates until the job is done.

Capabilities

Core — always available (Office.js, 17 actions):

Category	What the agent can do
Read	read_range, read_sheet_names, read_table, read_selection
Write	write_range, write_formula, calculate (full workbook recalc)
Sheets	create_sheet, rename_sheet, delete_sheet
Format	format_range (bold/italic/fill/colors/sizes/number formats), auto_fit
Tables	create_table, add_table_row, sort_table
Charts	create_chart, configure_chart

Power Bridge — optional VSTO companion (full COM object model, 15 actions):

Category	What the agent can do
Equations	insert_equation — genuine native equations (OMML math zones) from linear syntax or LaTeX — editable in Excel's own equation editor
Analysis	create_pivot_table (real pivots with layout + consolidation functions), goal_seek, add_power_query (a real Power Query from your M code, materialized or connection-only)
Charts pro	configure_chart_pro (combo charts, secondary axis, trendlines with equation/R²), create_slicer (functional, on tables or pivots)
Reporting	export_pdf, page_setup (orientation, print area, fit-to-pages, margins…)
Protection	protect_sheet (granular allowances), protect_workbook (structure/windows)
Agent vision	capture_range — the agent literally sees your sheet (cells and shapes/equations) as an image and reasons about it
Escape hatches	execute_mso (any built-in Ribbon command), undo, evaluate (arbitrary Excel formulas)

Everything runs locally: the bridge is loopback-only (127.0.0.1) and token-authenticated; the only thing that leaves your machine is the LLM traffic from your own gateway.

Components

Piece	What it does	Required?
Web add-in (React + Office.js)	The chat taskpane inside Excel; executes core actions via Office.js	Yes
Hermes Gateway (hermes-agent)	The local agent runtime (LLM orchestration, SSE streaming)	Yes
Caddy	Local HTTPS reverse proxy (mandatory: Office.js requires HTTPS)	Yes
Power Bridge (VSTO companion)	Loopback HTTP server inside Excel that unlocks the pro actions	optional

Platform: Windows desktop Excel (2016+ / Microsoft 365).

---

Quick start (users)

Everything installs per-user — no admin rights needed.

0. Prerequisites

• Windows 10/11 with Excel 2016+ or Microsoft 365 desktop.

• The Hermes Gateway running locally — this is the hermes-agent product (separate project; install it per its own documentation). In its .env:

  API_SERVER_ENABLED=true
  API_SERVER_KEY=secret_testing_key   # choose your own; you'll enter it in the add-in (step 5)

  Start it — the API listens on http://localhost:8642.

• Caddy 2: download and rename the file to caddy.exe and place it next to the Caddyfile.

Only for the optional Power Bridge (step 3):

• .NET Framework 4.8 (inbox on Windows 10/11).
• VSTO Runtime (the MSI checks for it).

1. Download

From Releases:

• hermes-web-addin-dist.zip — the built web add-in
• Caddyfile — the production proxy config
• manifest.xml — the add-in manifest
• Hermes.PowerBridge-x.y.z.msi — the Power Bridge (optional, recommended)

2. Run the add-in frontend

Create C:\hermes-excel and put there: caddy.exe, the Caddyfile, and the unzipped hermes-web-addin-dist.zip (it extracts as a dist folder). The layout:

C:\hermes-excel\caddy.exe
C:\hermes-excel\Caddyfile
C:\hermes-excel\dist\

Then run in PowerShell:

cd C:\hermes-excel
.\caddy.exe run --config Caddyfile

This serves the add-in at https://localhost:3000 and proxies the gateway and the bridge. (First run: let Caddy install its local root certificate when asked.)

Unzipped somewhere else? Set $env:HERMES_ADDIN_DIST = "D:\your\path" in the same window before running Caddy.

3. Install the Power Bridge (optional but recommended)

Run Hermes.PowerBridge-x.y.z.msi. On the first Excel start afterwards you'll see "Microsoft Office Customization Installer — Publisher cannot be verified" → click Install. This prompt is expected for unsigned builds (see Roadmap); it appears only once.

4. Sideload the add-in in Excel

1. Drop manifest.xml in C:\hermes-excel (the same folder from step 2 works). Share it: right-click → Properties → Sharing → Share… → Share → copy the Network path it shows (e.g. \\YOUR-PC\hermes-excel) → Done.
2. Excel → File → Options → Trust Center → Trust Center Settings → Trusted Add-in Catalogs → paste the network path → Add catalog → check Show in Menu → OK.
3. Restart Excel → Insert → My Add-ins → SHARED FOLDER → Hermes for Excel.

5. Connect the add-in to the gateway

1. In the taskpane header, click the gear icon (Connection settings).
2. Gateway URL: leave the default (https://localhost:3000).
3. API key: the API_SERVER_KEY value from the gateway's .env (step 0).
4. Model (only if the gateway default fails): some Hermes versions default new API sessions to an unresolved hermes-agent alias and then fail with MODEL_NOT_FOUND. Set this to a real model ID from your gateway (e.g. moonshotai/kimi-k3) to force it.
5. Save & reconnect — the connection indicator (plug icon) shows a green dot. Without this key the gateway rejects requests with 403 Invalid gateway API key.

6. Verify

• The plug icon shows a green dot (hover it for gateway details).
• If the bridge is installed, the lightning icon lights up (hover for bridge version).
• Try: "inserta la ecuación de Colebrook en B2"

---

Troubleshooting

• Taskpane shows 502 / doesn't load: Caddy isn't running (step 2) or the gateway is down. The bridge badge shows "unavailable" if the MSI isn't installed — core features still work.
• Bridge asks to reload the taskpane: Excel restarted and the auth token rotated — reload the add-in (right-click taskpane → Reload).
• VSTO add-in issues (devs): see docs/vsto-addin-troubleshooting.md.

Roadmap

• Code signing (removes the VSTO trust prompt + SmartScreen) once the project has traction — OSS-friendly options (SignPath, Certum) first.
• AppSource distribution for one-click add-in install (first review ~1-2 weeks).
• Auto-update for the bridge MSI.

Contributing

See CONTRIBUTING.md — full dev setup, architecture notes, and the VSTO load-failure field guide. Release history lives in CHANGELOG.md; to report a vulnerability use the private flow in SECURITY.md (never a public issue).

License

AGPL-3.0 — free for the community; any derivative work (even offered as a network service) must stay open under the same terms.