Unofficial tool — not affiliated with or endorsed by Monarch Money, Inc. Use at your own risk.
A self-hosted personal finance dashboard that pulls your Monarch Money account data and builds a rolling balance forecast. Everything runs on your own computer. No data ever leaves your device except the direct connection to Monarch's own servers and, optionally, your chosen AI provider.
This is an unofficial, community-built tool. It is not affiliated with, endorsed by, sponsored by, or in any way connected to Monarch Money, Inc.
This tool automates a real Chromium browser session using your own Monarch credentials via Playwright. It intercepts the same GraphQL network calls that the Monarch web application makes — it makes no additional or undocumented API requests beyond what your browser would make normally.
This may violate Monarch's Terms of Service. Use it for personal use only, at your own discretion, and at your own risk. The author makes no guarantees about continued compatibility. If Monarch updates their web app, this tool may stop working without notice.
Support for this tool comes from the individual who created it, not from Monarch Money. Do not contact Monarch Money's support team with questions about this tool.
Butterfly Effect uses data from Monarch Money, recurring transactions, and future transactions you enter to project your account balance forward in time — by default 45 days, configurable to any horizon you like. It highlights upcoming low-balance windows, lets you model one-off transfers or expenses, and can optionally generate AI-powered narrative insights about spending patterns and upcoming bills.
Key capabilities:
- Forecast chart — rolling account balance projection based on your Monarch recurring schedule
- Scenario Modeling — enter upcoming real or potential income or expenses, one-time or recurring, to more accurately model your future balances
- Transaction Overrides — correct the amount, dates, or frequency of recurring transactions, or skip/delete them altogether
- AI Insights (optional) — fine-tune predictions with seasonal expense patterns, savings or transfer recommendations, and more based on your Monarch goals and existing forecast scenario
- Calendar Integration (optional) — use public calendars to supplement Monarch's recurring or one-time transactions
- Dark mode — prevent safety squints and preserve your retinal health
- A Monarch Money account
- Python 3.11 or later (not required if using the bundled Mac app from Releases)
- Mac (running from source):
brew install pythonor download from python.org - Linux:
sudo apt install python3 python3-venv(Debian/Ubuntu) orsudo dnf install python3(Fedora) - Windows: Download and run the installer from python.org/downloads — check "Add Python to PATH" during install. Or use winget:
winget install Python.Python.3.12
- Mac (running from source):
Optional — for AI insights: An API key from one of these providers (pick one). See Setting up AI Insights below for step-by-step instructions.
- Anthropic (Claude) — recommended
- OpenAI (GPT)
- Google (Gemini)
Mac: Go to the Releases page and download Butterfly.Effect-mac.dmg. Open the .dmg, drag the app to your Applications folder, and double-click to launch.
The first time you open it, macOS may warn you it's from an unidentified developer. Right-click the app → Open → Open to proceed. You only need to do this once.
Linux: Go to the Releases page and download butterfly-effect-linux-x86_64.AppImage. Make it executable and run it:
chmod +x butterfly-effect-*-linux-x86_64.AppImage
./butterfly-effect-*-linux-x86_64.AppImageWindows (or running from source on any platform): Clone or download this repository, then launch with the platform script for your OS:
git clone https://github.com/vendaface/butterfly-effect.git
cd butterfly-effect
Mac (bundled app): Python is bundled — no extra installation needed. Double-click Butterfly Effect in your Applications folder. A startup page opens in your browser while the server starts.
Mac (from source) / Linux: Run ./run.sh from the project folder. On first run the script creates a Python virtual environment and installs all required packages (takes a couple of minutes). The startup page will guide you if Python is missing or too old.
Windows: Double-click Start Butterfly Effect - Windows.cmd in the project folder, or run it from a Command Prompt. On first run it creates a Python virtual environment, installs all required packages, and downloads the Chromium browser used for Monarch data fetching — this takes a few minutes and only happens once. The startup screen shows progress and will guide you if Python is not found.
Windows tip: If Python was just installed and
Start Butterfly Effect - Windows.cmdcan't find it, open a new Command Prompt window before running it again — the PATH update from the Python installer only applies to new windows.
Once setup is complete the app takes you to the Settings page. The Monarch Connection section (highlighted with a blue border) is the only required step:
- Click Connect to Monarch — a Chrome browser window opens automatically. Log in to Monarch when prompted; the window closes on its own after a successful login.
- Wait a moment for your Monarch accounts to populate, then select your primary bill pay account from the dropdown. Click Save Monarch Settings to complete the setup.
Once these two steps are complete, the Go to Dashboard → button at the top of the page will be enabled. Click it to pull your transactions and open your forecast — this may take 30 seconds or so on the first fetch.
Further down the Settings page are AI Insights and Forecast Settings. These are both optional on first run and can always be customized later.
The first time you open the dashboard the app fetches your transaction history from Monarch. Your forecast chart appears at the top of the left pane when it's done. After the first run, your data stays cached so the dashboard loads instantly on future visits.
Starting the app:
- Mac (bundled): Double-click Butterfly Effect in Applications, or double-click
Start Butterfly Effect - Mac.commandin the project folder. - Mac / Linux (from source): Run
./run.shfrom the project folder. - Windows: Double-click
Start Butterfly Effect - Windows.cmd, or run it from a Command Prompt.
A startup page opens in your browser and redirects automatically once the server is ready. You can also bookmark http://localhost:5002.
Refresh Forecast — click the button in the upper right whenever you want updated transaction data from Monarch. Takes 1–2 minutes.
Run AI Analysis — generates fresh AI insights. Run this once a day or whenever you want an updated analysis. Requires an AI API key in Settings → AI Insights.
AI Insights drawer — click the AI tab on the right edge of the window to slide the panel in over the transaction schedule. Click the × inside, or click the tab again, to close it.
Resize columns — drag the vertical handle between the two panes to adjust how much width each side gets.
Settings — click the gear icon (⚙) in the top-right to open Settings. Key options:
| Setting | Description |
|---|---|
| Primary Account | Select the account used for bill payments — refresh the list if you don't see it |
| AI Insights | Enable AI Insights (off by default); set your preferred provider (Anthropic, OpenAI, or Google), choose your model and add your API key; set how many months of transaction history to include; customize how long before the analysis is labeled stale. Kick off an AI Analysis right from Settings and watch it run live |
| Forecast Horizon | How many days to project forward (default: 45) |
| Buffer Threshold | Get a warning when your balance drops below this dollar amount |
| User Context & AI Corrections | Hand-edit your AI corrections in free text (also stored in user_context.md) |
| Calendar Integration | Overlay custom calendar transaction events onto the forecast chart with Google Calendar, iCloud, or a custom ICS feed |
| App Settings | Change the default port, turn on debug mode, or reset to factory defaults |
The main dashboard uses an adjustable, two-column layout to maximize data visibility. The left pane always shows your balance graph, stat cards, and transfer recommendations. The right pane scrolls independently through your upcoming transaction schedule. Drag the handle between the two panes to resize them as needed.
The optional AI Insights can be shown or hidden using a slide-in panel.
Hover over any date on the balance graph to see that day's transactions.
The right pane shows a scrollable agenda of upcoming dates with clickable transactions showing merchants and amounts. The panel header shows the last-refreshed timestamp so you know how current the data is.
Click any transaction in the schedule to edit its data. Change dates, amounts, suppress the series entirely, or skip a single occurrence. The forecast updates instantly when you save.
Click the AI tab on the right edge of the window to slide the panel in from the right. It overlays the transaction schedule without shifting the graph. Transfer recommendations and seasonal spending observations appear here. The Corrections panel below lets you feed the AI specific facts about your finances to fix its accuracy.
Add transfers or expenses to model their impact on the forecast without modifying your real data. Modeling transactions can be one-time or recurring, and may be removed at any time.
Switch between light and dark mode using the icon in the header.
On first launch the app opens a startup splash page and then takes you directly to the Settings page with the Monarch Connection section highlighted. If no Python installation is detected the startup screen provides instructions for installing it before continuing.
Connect to Monarch via a temporary Chrome window. Your credentials go directly to Monarch — they are never seen or stored by this app.
Configure your AI provider, model, and API key here. The Last generated line shows the timestamp, token counts, and cost of the most recent analysis. You can kick off a new analysis directly from this page and watch the live progress log, or update it from the dashboard. The AI Insights button indicates the freshness of your last update, which is a customizable number of hours.
AI Insights is optional but adds meaningful value — seasonal spending patterns, predicted upcoming expenses, and transfer recommendations tailored to your actual history. You need an API key from one provider. The feature is off by default; you enable it in Settings → AI Insights.
All three providers work. Anthropic's Claude is recommended because the prompt is tuned and tested against it, but OpenAI and Google Gemini produce good results too.
Cost: AI analysis runs once on demand (you click "Run AI Analysis"). A single analysis call uses roughly 3,000–8,000 tokens depending on how many months of history you include. At current pricing this is fractions of a cent per run — typically under $0.05. None of the providers charge for having an account or holding an API key; you only pay for what you use.
- Go to console.anthropic.com and sign up or sign in.
- In the left sidebar click API Keys.
- Click Create Key, give it a name (e.g. "Butterfly Effect"), and click Create Key.
- Copy the key — it starts with
sk-ant-api03-…. You won't be able to see it again after closing this dialog, so copy it now. - In the app go to Settings → AI Insights, set the provider to Anthropic, and paste the key into the API Key field. Click Save AI Settings.
New Anthropic accounts receive a small free credit to start. After that, usage is billed at published rates.
- Go to platform.openai.com and sign up or sign in.
- Click your profile icon in the top-right corner and choose Your profile, then select API keys in the left sidebar — or go directly to platform.openai.com/api-keys.
- Click Create new secret key, give it a name, and click Create secret key.
- Copy the key — it starts with
sk-proj-…orsk-…. Store it somewhere safe; it won't be shown again. - In the app go to Settings → AI Insights, set the provider to OpenAI, and paste the key into the API Key field. Click Save AI Settings.
OpenAI requires a paid account (add a credit card under Billing → Payment methods) before API keys will work. Usage is billed at published rates.
- Go to aistudio.google.com and sign in with a Google account.
- Click Get API key in the left sidebar, then Create API key.
- Copy the key — it starts with
AIza…. - In the app go to Settings → AI Insights, set the provider to Google, and paste the key into the API Key field. Click Save AI Settings.
Google AI Studio keys include a generous free tier. Usage beyond the free tier is billed at published rates.
- Two-column fixed-viewport layout — graph, stat cards, and transfer recommendations always visible on the left; transaction schedule scrolls independently on the right
- Resizable columns — drag the handle between panes to fit your screen
- AI Insights drawer — slides in over the schedule on demand; doesn't disturb the layout when closed
- Forecast balance chart with recurring payments projected forward, configurable to any number of days
- AI insights (optional) — seasonal spending patterns, predicted upcoming expenses, transfer recommendations to maintain a balance above your configured buffer amount
- Variable Payments — override Monarch's learned amount for variable monthly payments like credit cards; enter $0 to suppress a payment from the forecast entirely for a month
- Billing Day Overrides — correct the day-of-month for any recurring payment whose billing date Monarch has learned incorrectly
- Scenario Modeling — temporarily model one-time transfers or expenses to see how they affect your balance forecast
- Corrections & Context — feed the AI specific facts about your finances to improve its accuracy
- Startup page — animated loading screen with live progress updates and helpful error messages if Python is missing or too old
- Dark mode — toggle in Settings or with the moon icon in the header
"Setup needed" error on the dashboard — click → Open Settings in the error box and complete the Monarch Connection section (connect to Monarch and select your primary account).
Startup page shows a Python error — follow the on-screen instructions to install Python 3.11 or later:
- Linux:
sudo apt install python3 python3-venv(Debian/Ubuntu) orsudo dnf install python3(Fedora) - Windows: Download from python.org/downloads and check "Add Python to PATH" during install, then open a new Command Prompt window and run
"Start Butterfly Effect - Windows.cmd"again.
Forecast is slow — this is normal on first run. The app opens a browser, logs into Monarch, and fetches months of transaction history. Subsequent loads use a cached session and are much faster.
Monarch login fails — a Chrome window opens for you to log in. Complete any two-factor authentication steps there; the window closes automatically once you're logged in.
Account list looks incomplete after connecting — click Refresh Accounts in Settings → Monarch Connection.
"API key is not configured" — go to Settings → AI Insights, select your AI provider, and paste in your key. See Setting up AI Insights for step-by-step instructions.
Browser doesn't open automatically — navigate to http://localhost:5002 in your browser manually.
The app was working and suddenly stopped — Monarch occasionally updates their web app, which can break the data-fetching layer. Check the project page on GitHub for updates.
All your data stays on your computer. Nothing is uploaded to any cloud service operated by this tool.
Here is exactly where data flows and where it is stored:
- When you click Connect to Monarch, a Chromium browser window opens on your machine. You log in directly to
app.monarchmoney.com— your credentials go from your keyboard to Monarch's servers, nowhere else. - After a successful login, Playwright saves your session cookies to
browser_state.json. Subsequent data fetches use this saved session (headless, no visible window) to avoid repeated logins. - All future data fetches go directly from your computer to
api.monarch.com— the same GraphQL endpoint your browser uses when you visit Monarch normally.
All runtime data is stored in your user data directory — never in a cloud service or the app bundle:
- Mac:
~/Library/Application Support/Butterfly Effect/ - Linux:
~/.local/share/butterfly-effect/ - Windows:
%APPDATA%\Butterfly Effect\(typicallyC:\Users\[yourname]\AppData\Roaming\Butterfly Effect\)
| File | What it contains | Leaves your device? |
|---|---|---|
.env |
AI API key | Never |
browser_state.json |
Monarch session cookies | Never |
config.yaml |
App preferences (account ID, forecast horizon, etc.) | Never |
insights.json |
AI analysis output | Only if you configure an AI provider |
payment_overrides.json |
Your variable payment amounts | Never |
payment_day_overrides.json |
Your billing day corrections | Never |
scenarios.json |
Scenario modeling events | Never |
monarch_accounts_cache.json |
Account names and IDs from Monarch | Never |
monarch_raw_cache.json |
Cached Monarch transaction data | Never |
user_context.md |
Corrections you feed to the AI | Only if you configure an AI provider |
All sensitive files are written with owner-only permissions so other users on the same machine cannot read them.
The local web server uses CSRF tokens to protect all state-changing API calls. Every form submission and data-mutation request from the browser is validated against a per-session token that outside pages cannot read. Response headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy) are set on all API routes.
The app runs a local web server at http://localhost:5002 by default. This server is only accessible from your own computer — it does not listen on a network interface accessible to other devices.
If you enable AI Insights, the app sends a summary of your recent transactions and recurring payments to the AI provider you choose (Anthropic, OpenAI, or Google). Before enabling this feature, review the privacy policy of your chosen provider:
Your AI API key is stored only in .env on your device. It is sent only to your chosen provider's API endpoint to authenticate requests — it is never transmitted to any server operated by this tool or its author.
Mac / Linux:
# Start (foreground — stops when you close the terminal)
./run.sh
# Start as a background daemon
./server.sh start
# Other daemon controls
./server.sh stop # stop the server
./server.sh restart # restart after config changes
./server.sh status # check if running
./server.sh logs # tail the server logWindows:
rem Start (foreground — from Command Prompt or double-click)
"Start Butterfly Effect - Windows.cmd"
rem Background daemon (from PowerShell)
.\server.ps1 start
.\server.ps1 stop
.\server.ps1 restart
.\server.ps1 status
.\server.ps1 logsAll runtime files live in your user data directory:
- Mac:
~/Library/Application Support/Butterfly Effect/ - Linux:
~/.local/share/butterfly-effect/ - Windows:
%APPDATA%\Butterfly Effect\
| File | Purpose |
|---|---|
config.yaml |
Main configuration (auto-created on first launch) |
.env |
AI API key (auto-created when you save an AI key) |
browser_state.json |
Saved Monarch login session |
monarch_raw_cache.json |
Cached Monarch transaction data (enables instant startup) |
monarch_accounts_cache.json |
Cached account list from Monarch |
insights.json |
Latest AI analysis output |
payment_overrides.json |
Variable payment amounts you've set |
payment_day_overrides.json |
Billing day corrections |
scenarios.json |
Scenario modeling events |
dismissed_suggestions.json |
AI suggestions you've dismissed |
user_context.md |
Corrections and facts injected into AI prompts |
Mac / Linux:
./reset-for-testing.shWindows:
reset.cmdKills the running server, deletes all cached and generated files, and removes the virtual environment. You will be asked to confirm before anything is deleted.
- No official Monarch API exists — this tool intercepts the same network calls the Monarch web app makes. Changes to Monarch's web app may break it without warning.
- Designed for desktop use; mobile layout is not optimized.
MIT — see LICENSE file.
This software is provided "as is", without warranty of any kind. The author is not responsible for any account issues, data loss, or Terms of Service consequences that may arise from its use.