← 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.
Platform note: The AI Assistant is currently available for Windows. Support
for macOS and other systems is coming soon.
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.
⬇ Download AI Agent (Windows)
Required for both the "Ask AI" panel and Claude Code / Cursor / Codex. Windows-only for now.
The first two items are needed for both ways; the third — the AI model — depends on which way you choose:
| 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
(a small Windows app) |
This is the helper that lets the AI actually operate the app on your computer. One click to install — no Node, no Chrome, no technical setup. Windows only for now. |
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). It is encrypted and stays on your machine; 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, 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 on your machine.
Install the AI Agent (one time)
- 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).
If you only want the in-app "Ask AI" panel, you don't need to tick any AI tool.
- Click Install. There is no admin / UAC prompt — it installs just for you.
That's the only install. The same Agent powers both ways below — the in-app panel
and the external AI tools. You set it up once.
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.
- If you see a banner that says "AI Agent not detected", click Start AI Agent.
Your browser shows a one-time prompt: "Open WaterfallBridge AI?" — tick
Always allow and click Open.
- Within a few seconds the little status dot turns green — the assistant is ready.
No tray icon? That's fine. The "Start AI Agent" button launches the helper on demand,
quietly in the background — no extra window appears.
- Click the ⚙ gear icon at the top-right of the chat panel.
- Paste your AI provider API key (e.g. OpenAI, Anthropic, or another compatible provider) and save.
Where do I get a key? From your AI provider's account dashboard (e.g. OpenAI or Anthropic). Your key is
encrypted with Windows DPAPI before being written to disk and is never sent to
WaterfallBridge.
Type what you want in plain language. For example:
You
“Analyze sales-2024.xlsx in my Downloads folder and tell me why profit dropped this quarter.”
The assistant then does everything for you, narrating each step:
- Finds & checks your file — it locates the 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.
The first time the AI opens a local file, you'll get a small permission prompt:
Deny / Allow once / Allow & remember. Pick Allow once or
Allow & remember so it can read your file. This is a safety feature — the AI can only touch
folders you approve (by default your Downloads, Desktop, and Documents).
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.”
- To stop the helper when you're done: click the ⚙ gear → Stop AI Agent. It shuts down cleanly and frees up memory.
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 [email protected], 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 |
|---|
| "AI Agent not detected" in the panel, and Start AI Agent doesn't work |
Make sure the Agent is installed (Step 0). If a browser dialog says "No app is set to open this URL", the install didn't finish — reinstall WaterfallBridge-Setup.exe. |
| The AI says it can't read your file |
Approve the folder-access prompt (Allow once / Allow & remember). By default only Downloads, Desktop, and Documents are allowed — ask the AI to use a file there, or grant the folder when prompted. |
| 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 |
In the panel: ⚙ gear → Stop AI Agent. Or end WaterfallBridge-Agent.exe in Task Manager. |
In short
- ☑ Install the WaterfallBridge AI Agent once.
- ☑ Add your AI provider API key — e.g. OpenAI / Anthropic (stays on your machine).
- ☑ Use the Ask AI panel in the browser, or your AI coding tool.
- ☑ Describe your question in one sentence — the AI runs the analysis and explains it.
- ☑ Remember: WaterfallBridge does the math; the AI only operates it.