← Back to Home
What is this?
WaterfallBridge already explains why any KPI changed by breaking the change down into its real
drivers. The AI Assistant simply removes every button-click between you and that answer.
You talk to it in plain language; it operates WaterfallBridge for you — uploading your file, running the
Bridge, reading the chart, and writing the key findings in words anyone can understand.
There are two ways to use it, and this guide walks you through both, step by step:
- The "Ask AI" panel built right into the web app — the easiest option for everyone.
- Your AI coding tool — Claude Code, Cursor, or Codex — if you already work there.
No install needed for the web panel. Way 1 — the in-app "Ask AI" panel — now
runs entirely in your browser on any operating system; just add your own AI provider API key.
The downloadable AI Agent is only for Way 2 (Claude Code / Cursor / Codex via MCP) and is
currently Windows-only.
Important — the AI does not invent your numbers. Every result is computed by the
deterministic WaterfallBridge engine: the same transparent, auditable, closed-form math that powers the
normal app. The AI is only the operator — it clicks the buttons for you and explains what
the engine calculated. The algorithm is, and always will be, 100 % WaterfallBridge.
What you need depends on which way you choose. Way 1 (the "Ask AI" panel) needs no download at all — skip straight to it. Only Way 2 needs the AI Agent:
| You need | Why |
|---|
A WaterfallBridge account
with an active subscription |
The Bridge calculation runs through your account. (You can try the free demo first, but full analysis needs a subscription.) |
The WaterfallBridge AI Agent
(Way 2 only — a small Windows app) |
Only needed to connect Claude Code / Cursor / Codex via MCP. One click to install — no Node, no Chrome, no technical setup. Windows only for now. The "Ask AI" panel (Way 1) does NOT need this. |
An AI model to drive it
(your own — not resold by us) |
This is the "brain" that understands your sentence. WaterfallBridge does not bundle or resell AI usage, so you bring your own:
- Way 1 · "Ask AI" panel: paste your own AI provider API key — any compatible provider works (e.g. OpenAI, Anthropic, DeepSeek). It is stored in your browser only; the provider bills you for usage.
- Way 2 · Claude Code / Cursor / Codex: no separate key needed — it runs on your existing subscription or plan for that AI tool.
|
Privacy in one line: your spreadsheet is processed locally (in your browser for Way 1),
only lightweight algorithm requests reach our server to run the Bridge math,
no user data is stored on our servers, and your AI key stays in your browser (Way 1) or on
your machine (Way 2).
Just want to chat in the browser? Go straight to
Way 1 · the "Ask AI"
panel below — there is
nothing to download or install. The AI Agent install steps only
matter if you want to use Claude Code / Cursor / Codex (
Way 2).
Install the AI Agent — for Way 2 only (one time)
⬇ Download AI Agent (Windows)
Only for Claude Code / Cursor / Codex (Way 2). The "Ask AI" panel needs no download. Windows-only for now.
- Download the installer,
WaterfallBridge-Setup.exe.
- Double-click it.
- The wizard asks which AI tools to connect. Tick the ones you use:
- ☑ Cursor IDE · ☐ Claude Desktop · ☐ Codex CLI
- ☑ Start the helper automatically when Windows starts (optional — you can untick it and start it on demand instead).
- Click Install. There is no admin / UAC prompt — it installs just for you.
Way 1 Use the "Ask AI" panel in the web app
This is the simplest option. Everything happens in your browser — perfect if you've never used an AI coding tool.
- Open the WaterfallBridge web app and sign in to your account.
- Look at the top-right of the header and click Ask AI. A chat panel slides in from the right.
- The header shows "In-page · ready" with a green dot — the assistant is
running right inside this browser tab. There is nothing to download, install, or launch.
No install, any OS. The "Ask AI" panel works in any modern browser on Windows, macOS, or
Linux. (If you happen to have the optional AI Agent running, the panel will use it automatically — but it is
never required for the panel.)
- Click the ⚙ gear icon at the top-right of the chat panel.
- Pick a provider (OpenAI, Anthropic, DeepSeek, or any compatible one), paste your
AI provider API key, choose a model, and click Use this.
Where do I get a key? From your AI provider's account dashboard (e.g. OpenAI, Anthropic, or
DeepSeek). Your key is stored in this browser only and is never sent to
WaterfallBridge's servers — the assistant talks to your provider directly from your browser.
Attach your spreadsheet with the 📎 button in the chat box (or import it via the app's
Import File button first), then type what you want in plain language. For example:
You
“Analyze this file and tell me why profit dropped this quarter.”
The assistant then does everything for you, narrating each step:
- Checks your file — it reads the attached spreadsheet and verifies the data is in a shape it can analyze.
- Prepares the data — it reshapes your columns into the Bridge format automatically.
- Runs the Bridge — the WaterfallBridge engine computes the breakdown.
- Explains the result — it reads the chart and contribution table and writes the key drivers and insights in plain words.
Your file never leaves your browser. In the panel the AI reads the workbook you attach
with 📎 (or the one already loaded in the app) right here in the tab — there are no folder-permission
prompts and nothing is uploaded to our servers.
If your data isn't tidy, the assistant will stop and tell you exactly what to fix
(for example "remove the merged cells" or "this looks like a pivot table"). Fix it, save, and ask again.
See the
Data Preparation Guide for the simple rules.
- Ask follow-ups in the same chat: “Now break it down by region instead,” or “Export the result to Excel.”
- When you're done, just close the panel or the tab — there is no background helper to shut down in the in-page panel.
Way 2 Use it from Claude Code, Cursor, or Codex
If you already work inside an AI tool, WaterfallBridge plugs in as a tool source (an "MCP server") so you can analyze files without leaving it.
Claude CodeCursorCodexClaude Desktop
This way uses your own AI tool subscription. The language model comes from your existing
Claude Code / Cursor / Codex plan — WaterfallBridge does not resell AI usage and you do
not need a separate AI provider API key here (e.g. OpenAI / Anthropic — that key is only for the in-app "Ask AI" panel).
- Run the same WaterfallBridge AI Agent installer from Step 0 above.
- In the wizard, tick the AI tools you use (Cursor, Claude Desktop, and/or Codex). The
installer automatically writes the connection settings for you — no JSON editing required.
- Restart your AI tool so it picks up the new connection.
- You'll now see waterfall-bridge listed as an available tool source inside that app
(e.g. in Cursor under Settings → MCP).
Doing it by hand? Advanced users can add the connection manually. The server is named
waterfall-bridge and points at the installed WaterfallBridge-Agent.exe in
--mode=stdio. The installer does this for you automatically, so most people can skip it.
The very first time, let the assistant log in to your WaterfallBridge account. Just ask:
You
“Use waterfall-bridge to log in as me@example.com, then we'll analyze a file.”
Your login session is saved encrypted on your machine, so you only do this once — after that the AI never sees your password again.
From then on, just describe the job and point it at a file:
You
“Use waterfall-bridge to analyze D:\Data\sales-2024.xlsx and tell me the top drivers behind the revenue change.”
The assistant chains the steps automatically — open the app, prepare the file, run the Bridge, read the chart, and summarize:
open app → inspect & prepare file → run bridge → read chart data → explain drivers
No panel here — the AI talks to you in chat. If your workbook has several sheets, or your
data needs tidying, the assistant won't pop up a window — it will simply ask you in the
conversation (e.g. "Which worksheet should I use?" or "Please remove the merged cells first").
Answer in chat and it continues.
You may also be asked to approve folder access the first time the AI reads a file outside
your default folders. Confirm it and the analysis proceeds.
Works in both the "Ask AI" panel and your AI tool. The clearer your question, the better the explanation.
You“Why did our gross margin % fall from Q1 to Q2? Use the file margin.xlsx on my Desktop.”
You“Analyze orders.csv in Downloads and break the revenue change down by product.”
You“Compare this year vs last year in kpi.xlsx and give me the three biggest drivers, then export the result.”
Tip: mention the file name, the KPI you care about
(revenue, margin %, conversion rate…), and the dimension to break it down by (region,
product, channel…). That's all the AI needs.
| If you see… | Do this |
|---|
| The "Ask AI" panel header doesn't say "In-page · ready" |
Open the ⚙ gear and add an AI provider API key, then pick a model and click Use this. The panel runs in your browser — no Agent install is required for it. |
| The AI says it has no file to analyze (Way 1 panel) |
Attach your spreadsheet with the 📎 button in the chat box, or import it via the app's Import File button first, then ask again. |
| "Failed to fetch" / model list won't load (Way 1 panel) |
Some providers block direct browser calls (CORS). The panel falls back to built-in model suggestions — just type/pick a model id. If your provider blocks the key entirely in the browser, use Way 2 (Cursor / Codex) instead. |
| The AI stops and asks you to fix the data |
Your sheet has merged cells, a pivot/crosstab layout, title rows, or mixed text in number columns. Follow the Data Preparation Guide, save, and ask again. |
| "waterfall-bridge" doesn't appear in Cursor / Claude / Codex |
Fully restart the AI tool after installing. Confirm you ticked that tool in the installer wizard. |
| It asks which worksheet to use |
Your workbook has multiple sheets. Just tell it the sheet name in your reply. |
| You want to free up memory (Way 2 only) |
The in-page panel (Way 1) has no background process to stop. For Way 2, end WaterfallBridge-Agent.exe in Task Manager. |
In short
- ☑ Way 1 — "Ask AI" panel: no download. Open the app, click Ask AI, add your AI provider API key (e.g. OpenAI / Anthropic / DeepSeek — stays in your browser).
- ☑ Way 2 — Claude Code / Cursor / Codex: install the WaterfallBridge AI Agent once (Windows), using your existing AI tool plan.
- ☑ Describe your question in one sentence — the AI runs the analysis and explains it.
- ☑ Remember: WaterfallBridge does the math; the AI only operates it.