OpenArgentum

Getting Started with OpenArgentum

A step-by-step guide to setting up and using OpenArgentum for managing your personal finances.

What You’ll Need

  1. A computer running macOS, Linux, or Windows (with WSL)
  2. Python 3.11 or newer – Download here if you don’t have it (3.10 is the minimum; 3.11+ is recommended)
  3. Node.js 20.19 or newer – Download here (choose the LTS version). Vite 8, which builds the app, requires 20.19+.
  4. A way to reach the Google Gemini API – the simplest is an API key from Google AI Studio (“Create API Key”, then copy it). For real financial data, Google recommends their paid data terms — see Your data & privacy below.

Don’t have an API key yet? You can still install the app and add the key later through the Settings page. You can also explore the app with a built-in demo database — see Try the Demo below — which needs no key at all.

What it costs: Very little — for typical personal-finance usage, expect Gemini costs in the cents. Heavy statement imports may hit Gemini’s rate limits, in which case they’ll queue and process sequentially. Browsing your existing data is always free — only statement import and the Aurelia assistant call Gemini.

Your data & privacy

OpenArgentum stores everything locally in a SQLite database on your machine — no cloud sync, no account, no telemetry. It reaches out to exactly one external service, on purpose: to read and categorize your statements, the contents of the files you import are sent to the Google Gemini API. That is the only data that leaves your machine, and it only happens for AI features (statement import and the Aurelia assistant). Browsing your existing data makes no external calls, and OpenArgentum never connects to your bank.

Google’s data protection terms differ by billing tier:

Ultimately, this is your call. Pick the option you’re comfortable with, and review the current Gemini API terms before you commit.

Installation

Open a terminal and run:

git clone https://github.com/amithmathew/OpenArgentum.git
cd OpenArgentum
./start.sh

The script will:

When you see OpenArgentum with a URL in the terminal, open http://localhost:8099 in your browser.

Try the Demo First

Not ready to import your own statements yet? OpenArgentum ships with a sample database of realistic transactions so you can explore every feature before adding a key.

Browsing the demo makes no external calls and needs no Gemini key. Any changes you make to the demo reset when you restart the server. While the demo database is active, a banner at the top of the app reminds you you’re on sample data.

Moving to your own data

The sample data stays in demo.db either way, so you can always switch back for a look.

First-Time Setup

The onboarding wizard will guide you through:

  1. API Key – Paste your Gemini API key (or choose GCP credentials if you have them)
  2. Done! – That’s all the setup needed

Importing Your Bank Statements

  1. Go to the Import page (click “Import” in the sidebar, or the “More” menu on mobile)
  2. Drag and drop your bank statement files (PDF, CSV, or ZIP)
  3. Click Ingest to process each statement
  4. The AI will automatically:
    • Extract all transactions
    • Assign categories (Groceries, Dining, Transportation, etc.)
    • Assign spend tiers (Essential, Lifestyle, Discretionary)
    • Detect duplicate transactions from overlapping statements
    • Identify potential transfers between accounts

Tip: You can upload multiple statements at once. The app processes them one at a time and skips duplicates automatically.

Exploring Your Finances

Dashboard

The Dashboard shows your spending at a glance:

Transactions

The Transactions page shows all your transactions with:

On desktop: You can select multiple transactions and bulk-assign categories, tiers, tags, or projects.

On mobile: Tap a transaction to expand its details. Use the expanded view to change category or tier.

Categories & Tiers

The Classify page lets you manage:

Projects

Projects help you track spending on specific goals or trips:

Asking Aurelia

Aurelia is your AI assistant. Open the chat by:

What You Can Ask

Questions about your spending:

Comparisons:

Visualizations:

Organizing your data:

How Proposals Work

When you ask Aurelia to make changes:

  1. She finds the matching transactions and shows you a proposal
  2. The proposal lists the affected transactions and what will change
  3. You click Approve to apply the changes, or Reject to cancel
  4. If you change your mind, click Undo to reverse any approved change

Aurelia never makes changes without your permission. Every modification requires explicit approval.

Accessing on Your Phone

You can use OpenArgentum from your phone or tablet on the same Wi-Fi network:

  1. Stop the app if it’s running (Ctrl+C in the terminal)
  2. Restart with network access: 
    ./start.sh --headless
  3. The terminal will show a PIN and a network address like http://192.168.1.50:8099
  4. Open that address in your phone’s browser
  5. Enter the PIN when prompted

The app is fully optimized for mobile – you’ll get a bottom tab bar for navigation, touch-friendly controls, and swipeable tables.

Security: Network access is off by default. The --headless flag enables it with PIN protection. Only devices on your local network can access it.

Tips

Troubleshooting

The app won’t start:

AI features aren’t working:

The chat shows “Chat encountered an error”:

Transactions look wrong after import:

Can’t access from my phone:

This site is open source. Improve this page.