Everything you need to get started and get the most out of Groundwork
Groundwork is designed to be simple — but we've documented everything just in case.
Download the installer from the Download page and double-click Groundwork_Setup.exe.
Windows may show a SmartScreen warning — "Windows protected your PC." This happens because Groundwork isn't yet code-signed. Click More info → Run anyway. The app is completely safe.
Groundwork uses Microsoft Edge WebView2 to display its interface. On most Windows 10/11 machines it's already installed. If it's not, the installer will prompt you to download it (it's free and takes about 30 seconds).
When you open Groundwork for the first time, it walks you through a 6-step setup:
Groundwork imports transaction files from your bank. Most banks let you export these from your online account.
1. Log into your bank's website and find the transaction export/download option (usually under Account Activity or Statements).
2. In Groundwork, click the Import button in the Ledger or top toolbar.
3. Select your account, choose the file, and click Import.
4. Groundwork automatically categorizes transactions and removes duplicates.
Fastest way: download the prebuilt binary from the Download page — no Python or system packages needed.
tar -xzf Groundwork-linux-x86_64.tar.gz cd Groundwork ./Groundwork
Requires Python 3.11+ and a few system packages — the exact webkit2gtk package name depends on your distro version.
sudo apt install python3-gi python3-gi-cairo gir1.2-webkit2-4.0 python3-tk pip3 install -r requirements.txt python3 launch.py
sudo apt install python3-gi python3-gi-cairo gir1.2-webkit2-4.1 python3-tk pip3 install -r requirements.txt python3 launch.py
sudo dnf install python3-gobject webkit2gtk4.0 python3-tkinter pip3 install -r requirements.txt python3 launch.py
Download the .zip from the Download page, unzip it, and drag Groundwork.app into your Applications folder.
macOS may show a Gatekeeper warning — "Groundwork can't be opened because it is from an unidentified developer." This happens because the app isn't yet code-signed. Right-click the app, choose Open, then confirm Open again in the dialog. You only need to do this once.
The Budget page shows your monthly income and expenses side by side. Every expense row tracks how much you've spent so far this month from your imported transactions.
Click + Add expense and type the name and amount. Groundwork automatically matches it to your transactions.
Sinking funds are savings goals you contribute to monthly — like a car repair fund or vacation savings. Add one from the Budget page and Groundwork tracks your progress automatically.
The Debt page is where Groundwork earns its keep. Add every debt you have — credit cards, car loans, student loans, leases — and Groundwork builds a payoff schedule.
Snowball pays off the smallest balance first — gives you quick wins and momentum.
Avalanche pays off the highest interest rate first — saves the most money mathematically.
Both work. Pick the one you'll actually stick to.
You can record activity directly on a debt card — charges, payments, and interest — with a running total, so the balance reflects what you've actually done rather than just its starting figure. Link a payment to the matching transaction in your checking account (from either the debt ledger or the main Ledger) and Groundwork keeps both records in sync, with no double-entry. Unlinking later leaves both records intact.
For a payment you make every month, save the pattern once. Each month Groundwork prepares a draft you can confirm, edit, or skip — no re-entering the same payment over and over. Because these payments move the account balance, your payoff projection reflects what you've really paid.
The Ledger is your full transaction history. Every imported transaction appears here, categorized and searchable.
Click any transaction to change its category. Groundwork remembers your choice and applies it to similar transactions in future imports.
If a transaction covers multiple categories (like a Target run that included groceries and clothing), click the transaction and choose Split.
Click the checkmark on any transaction to mark it as cleared — confirmed against your bank statement.
Net worth = everything you own minus everything you owe. Groundwork tracks it over time so you can see the trend.
Your checking and savings balances pull automatically from your imported transactions. Enter your home value, retirement accounts, investments, and mortgage balance manually or link them.
The Gift page helps you plan gifts for everyone in your life without getting blindsided.
Click + Person and add the people you buy gifts for. Tag them as Family, Friend, Coworker, or Other.
Each person can have multiple occasions — Birthday, Anniversary, Christmas, Mother's Day, etc. Each occasion has a date and a budget.
The top of the page shows everyone with an occasion in the next 90 days. Click Budget it to add their gift to this month's budget automatically.
For Christmas, vacations, or any recurring occasion, create a Seasonal Fund with a target amount and a funded-by date. Groundwork tells you how much to save each month to hit it.
The Investments page tracks your holdings — stocks, ETFs, and other positions — with their cost basis and current value, and prices update automatically. Your total rolls into your Net Worth.
Add each position with its symbol, number of shares, and what you paid. Groundwork shows your gain or loss and keeps the value current.
The Report Center has ten built-in reports, several of which can include an AI-written narrative.
Every report has a Print button. The narrative reports (such as the Monthly Spending Summary and Distance Traveled) are written by AI — locally on your machine by default, or by Anthropic's Claude if you've switched to cloud mode. See AI features.
Thinking about a big purchase? Enter its name and cost on the Before You Buy page, and Groundwork shows exactly what it does to your monthly budget and your debt-free date.
It isn't there to talk you out of anything — it's there to make sure you know the real cost, in dollars and in time, before you decide.
The Trip Planner helps you plan a trip that actually fits your finances. Enter your destination, dates, and whether you're flying or driving.
Groundwork estimates the cost from real inputs — your monthly surplus, your vehicle's MPG and current gas prices if you're driving, your actual dining history for meals, plus hotel and activity estimates — and shows what the trip costs in debt-free days, so you can decide with your eyes open.
Your data is stored locally at:
To back up manually, go to Settings → Data & Backup → Back up now. This creates a timestamped copy you can save anywhere.
Groundwork can write a plain-English monthly report and other narrative insights. AI is completely optional, and it runs one of two ways — local by default.
Out of the box, Groundwork runs AI on your own machine using Ollama. Nothing ever leaves your computer, there's no API key, and there's no cost. In Settings → AI, click Set up Local AI and Groundwork installs Ollama and a small language model for you (a few GB of disk space). Every other feature of Groundwork works fully whether or not you set this up.
If you'd rather use Anthropic's Claude API — for example on a machine that can't comfortably run a local model — switch to cloud mode in Settings → AI and paste your own Anthropic API key from console.anthropic.com.
In local mode, nothing is sent anywhere. In cloud mode, only when you explicitly generate an AI report, Groundwork sends aggregated numbers — income total, spending total, top categories, and a debt summary. No account numbers, no transaction descriptions, no names.
Groundwork is built on one principle: your financial data is yours.
Groundwork is actively maintained. If something breaks:
1. In the app, click ⚑ Report in the top bar.
2. Describe what you were doing when it broke.
3. Click Open in mail app — the report goes to support@groundworkfinance.app with your error log attached.
Or just email support@groundworkfinance.app directly.