goetta-finance

A local-first tool that connects SimpleFIN to Claude. Your bank data lives only on your machine, in a DuckDB file you own. Claude reads it through an MCP server; you read it through a small web dashboard at localhost:8765.

See PROJECT_PLAN.md for the full vision and roadmap.

Requirements

• Python 3.11+

• A SimpleFIN Bridge account (about $1.50/month) — sign up at https://bridge.simplefin.org/

Related MCP server: plaid-mcp

Install

pipx install goetta-finance      # recommended
# or:  pip install goetta-finance

pipx is the cleanest way to install a Python CLI: it lives in its own isolated environment and puts the goetta-finance command on your PATH. That global path is also the stable thing to point Claude Desktop's MCP config at — no project venv path to chase.

git clone https://github.com/griffin-goepper/goetta-finance-mcp.git
cd goetta-finance-mcp
python -m venv .venv
.venv/Scripts/activate         # Windows
# source .venv/bin/activate    # macOS/Linux
pip install -e ".[dev]"

Quick start

goetta-finance init       # interactive setup wizard
goetta-finance sync       # pull fresh data from SimpleFIN
goetta-finance web        # open the dashboard at http://127.0.0.1:8765

The init wizard walks four steps:

1. Claim a SimpleFIN setup token → access URL (stored at ~/.local/share/goetta-finance/config.json, mode 0600 on POSIX).

2. Initialize the DuckDB store.

3. Pull initial history (up to 90 days).

4. Auto-write the Claude Desktop MCP config (merges into the existing file; preserves any other servers you've configured).

Re-running init is safe — each step detects existing state and offers to skip or replace.

Commands

Importing historical data

SimpleFIN typically returns ~90 days of history when you first connect. If your bank offers statements or CSV exports going back further, you can backfill:

1. Convert your bank's export into a normalized CSV (any tool you like — the format is deliberately bank-agnostic):

   posted,amount,description,transacted_at,ref_number,memo,source_file
   2019-07-15,-12.34,Debit Purchase VISA Coffee Shop,2019-07-13,1000000001,,2019-08 statement.pdf
   2019-07-26,1250.00,Deposit,,2000000002,,2019-08 statement.pdf

   Amounts are signed the way the store expects: spending negative, deposits/credits positive. transacted_at, ref_number, memo, and source_file may be empty.

2. Import into an existing account (find ids with goetta-finance account list):

   goetta-finance import transactions history.csv --account ACT-<id> --dry-run   # inspect first
   goetta-finance import transactions history.csv --account ACT-<id>

   Rows get deterministic IMP- ids, so re-running the same file updates instead of duplicating. By default, rows posted on/after the account's earliest synced transaction are skipped — the live feed owns that region (--before/--allow-overlap override). Category rules apply to imported history retroactively, like everything else.

3. Optionally import end-of-day balance history (header date,balance,source_file; liability balances negative when owed):

   goetta-finance import balances balances.csv --account ACT-<id>

   Imported snapshots land at 23:59:59 UTC on each date; that timestamp fingerprint is how you'd identify (or delete) them later, since snapshots carry no source column.

On Windows, stop the daemon first (create daemon.stop next to data.duckdb) — the import CLI needs the DuckDB write lock.

Manual accounts and liabilities

SimpleFIN can't reach every account — 401(k) providers, HSAs, brokerages outside its bank list, and student-loan servicers all sit outside. goetta-finance account lets you track those by hand so they show up in MCP queries and the dashboard alongside synced accounts.

The four subcommands

# Create a manual account. Prompts interactively for any missing flags.
goetta-finance account add \
  --name "Apple Savings" \
  --org "Apple" \
  --type savings \
  --balance 30000 \
  [--as-of 2026-05-17]     # observation date, defaults to today (UTC)

# Mark an account as a liability (or clear the flag). Works on any account id.
goetta-finance account add ... --liability      # at creation time
goetta-finance account set-liability MANUAL-<uuid> true     # after the fact
goetta-finance account set-liability ACT-<simplefin-id> true   # SimpleFIN accounts too

# Update the balance on a manual account (also writes a balance_snapshot).
goetta-finance account set-balance MANUAL-<uuid> 32500 [--as-of 2026-05-17]

# List all accounts. Manual + liability rows are tagged in the output.
goetta-finance account list

# Remove a manual account. Two layers of safety: cascade-delete its snapshots
# (--force) AND type the account name to confirm (skip with --yes for scripts).
goetta-finance account remove MANUAL-<uuid> --force

Sign convention for liabilities

A liability always reduces net worth, regardless of how the source signs the balance. The signed-balance formula is:

CASE WHEN is_liability THEN -ABS(balance) ELSE balance END

So you can enter a student loan either way and the math comes out right:

• account add --type loan --balance 22500 --liability (positive amount owed)

• A SimpleFIN credit card showing balance = -500 and you've flipped it to is_liability=true

Both contribute -500 and -22500 respectively to net worth — collapsing the loan-servicer convention and the SimpleFIN convention to one answer. The dashboard's net-worth chart and the accounts page footer respect the formula. When writing sql_query SELECTs against the accounts table, reach for the same CASE WHEN expression to compute totals correctly.

is_liability is independent of type on purpose — type describes what kind of account it is (loan, credit, investment), while is_liability controls how net-worth math treats it. A margin account is type=investment but functionally a liability; you can flip the flag without changing the type.

Linked transfers

Manual balances go stale the moment money actually moves — but the contributions are usually already in your data, as the transfer legs on a synced checking account. A transfer link connects the two so the manual balance rolls forward automatically:

# See what looks linkable. Candidates are detected when a synced account's
# transactions carry a payee exactly matching a manual account's name —
# each comes with the ready-made link command.
goetta-finance account links

# Link it: from then on, matching transactions on the synced account roll
# the manual balance forward on every sync (and immediately at link time).
goetta-finance account link MANUAL-<uuid> --from ACT-<simplefin-id> \
  --pattern "Apple Savings" [--match contains|regex]

# Remove a link by id. Already-applied transfers stay in the balance.
goetta-finance account unlink <id>

How it behaves:

• A debit out of the source credits the manual account (and money moving back debits it). The pattern is matched against the transaction's payee and description; pending transactions wait until they settle.

• Everything posted at or before the account's balance date is assumed to already be in that balance — linking never double-counts history, and an applications ledger guarantees each transaction applies at most once ever, across re-syncs and re-links.

• set-balance stays the true-up. Transfer sums can't see interest, so update the balance from a real statement occasionally: the true-up re-anchors the link at its --as-of date and re-applies anything posted after it against your fresh number.

• Every consumer updates for free. The roll-forward writes a genuine balance + snapshot through the same path as set-balance, so net worth, the over-time chart, balance goals, and the goal pace math all follow without special cases.

• Liability accounts can't be linked yet — a manual loan's stored sign is ambiguous (everything reads it through ABS()), so paydown tracking still goes through set-balance true-ups.

Heads-up

• Retroactive flag. Toggling is_liability re-treats all historical balance_snapshots for that account under the new value in net-worth-over-time charts. This is almost always what you want; if it isn't, flip the flag back.

• CC-credit edge case. A credit card with is_liability=true and a positive balance (you overpaid and now have a credit) computes as -balance instead of +balance. Rare; set-liability false while the credit exists, then re-enable, is the workaround.

• Balance is authoritative. Payments to a manual loan don't auto-decrement the balance — re-run set-balance from your servicer's monthly statement. For asset accounts fed by visible transfers, a linked transfer (above) automates exactly that.

Transaction categorization

Every transaction resolves to a category at read time through a SQL view (transactions_with_category). Three layers, outermost wins:

1. Manual override — a row in transaction_overrides for that transaction id.

2. Rule match — the lowest-priority rule in category_rules whose pattern matches the transaction's description and whose optional amount bounds (compared against the absolute amount; min inclusive, max exclusive) are satisfied.

3. Uncategorized — the fallback when nothing else matches.

Read-time resolution is the feature, not an optimization: adding or editing a rule applies retroactively to every existing transaction with zero data migration. A category_id column on transactions would silently break that.

Migration 0004 ships 14 default categories (Groceries, Dining, Transportation, Gas, Utilities, Subscriptions, Rent/Mortgage, Healthcare, Entertainment, Shopping, Travel, Transfers, Income, Uncategorized). Migration 0007 trims the default rule seed to a deliberately minimal universal set: a single (?i)transfer regex → Transfers (every bank uses "transfer" somewhere in inter-account descriptions) and five global subscriptions (Spotify, Netflix, Hulu, Disney Plus, Amazon Prime). Earlier versions shipped 38 US-merchant-specific defaults (Kroger, Starbucks, Shell, etc.) — they were noise for non-US users and bias for the rest. Expect most of your spending to land in Uncategorized on first install. That's the design: curate by adding rules for your descriptions. The MCP top_uncategorized_patterns tool (or the category set-rule CLI) is the curation path.

CLI

# Inspect what was seeded vs. what you've added.
goetta-finance category list                 # all categories with txn + rule counts
goetta-finance category default-rules        # the is_default=TRUE rule set

# Add a rule. Pattern matches case-insensitively against transaction description.
goetta-finance category set-rule Dining --match contains --pattern 'CHIPOTLE'
goetta-finance category set-rule Dining --match regex --pattern '(?i)venmo.*lunch'

# Amount bounds refine a pattern match by abs(amount) — dual-use merchants
# split cleanly (small gas-station buys are snacks, big ones are fuel).
# min is inclusive, max exclusive: no gap or overlap at exactly $20.
goetta-finance category set-rule Vice --pattern 'SPEEDWAY' --max-amount 20
goetta-finance category set-rule Gas  --pattern 'SPEEDWAY' --min-amount 20

# Remove a rule. Defaults require --force AND a typed-pattern confirmation;
# user-added rules just need the id.
goetta-finance category remove-rule 42
goetta-finance category remove-rule 7 --force        # default rule, prompts for the pattern

# Add a custom category.
goetta-finance category add --name "Gardening" --color "#4ade80"

# Recategorize a single transaction (manual override beats any rule).
goetta-finance transaction categorize <txn-id> Groceries
goetta-finance transaction uncategorize <txn-id>     # back to rule resolution

# Category names are case-insensitive ("dining" → "Dining") and typos get
# a "Did you mean?" suggestion via difflib.

From Claude

The spending_by_category(start, end) MCP tool aggregates per-category totals over a date range. By default it returns spending only (amount < 0, non-spending categories like Transfers and Income excluded) as positive magnitudes sorted descending. Pass include_non_spending=True to add them — Income rows come back with a negative total (cash in), Transfers positive (outflow to your own accounts).

get_transactions(category="Dining", ...) filters server-side through the view. Every transaction Claude sees carries a resolved category field — falling back to "Uncategorized", never None.

Curation is conversational. The whole maintenance loop runs in chat — no terminal needed:

You: "what's still uncategorized this month?" Claude calls top_uncategorized_patterns → "$85 CRUMBL COOKIES (3×), $60 NEW GYM LLC (2×)..." You: "Crumbl is dining, the gym is healthcare" Claude calls add_category_rule twice. Rules apply retroactively; done.

One-off fixes use categorize_transaction (override beats any rule) and uncategorize_transaction (undo). The MCP rule-write path runs the same pattern validation as the CLI.

For anything custom, query the view directly via sql_query:

SELECT category, COUNT(*), SUM(-amount) AS total
FROM transactions_with_category
WHERE posted >= '2026-01-01' AND amount < 0
GROUP BY category ORDER BY total DESC;

Dashboard

• By category page: pie chart of the last 30 days' spending, Income excluded.

• Transactions page: per-row colored category badge + a category-filter dropdown that narrows via HTMX without a page reload. The badge tooltip pre-fills the CLI command to recategorize that specific transaction id — copy-paste-ready.

Inline categorize-from-dashboard (HTMX dropdown + write endpoint) is deliberately not in v1; use the CLI. The reason: the standalone goetta-finance web opens the DuckDB store read-only, so a write endpoint would only work in daemon mode and forking dashboard behavior on writability isn't worth it until dogfooding shows frequent re-categorization friction.

Heads-up

• Rule patterns are MCP-reachable. A transaction memo can carry text that tricks Claude into calling add_category_rule (or running category set-rule ... --pattern <evil-regex>). Both surfaces run the same best-effort validator (refuses uncompilable regexes, nested quantifiers like (X+)+, large counted repetitions like (.*a){25}) but CPython's re engine doesn't release the GIL so a runtime regex timeout isn't possible. The load-bearing runtime defense is the existing query_sql statement-timeout watchdog (GOETTA_FINANCE_SQL_TIMEOUT_SECONDS, default 30s). See CLAUDE.md for the threat model.

• One category per transaction. Costco-style mixed purchases get one label. No splits in v1.

• Default rules don't re-seed if you delete them. Migrations run once per database; the slate stays where you leave it. New defaults arrive only via new migration files — never edits to shipped ones.

See CUSTOMIZATION.md for the full map of user-tunable surfaces (rules, prefix list, categories, flags, colors).

Pending transactions

Unsettled ("pending") transactions from SimpleFIN are stored alongside posted ones with pending = TRUE. They're a snapshot of the bank's in-flight state, not history: each sync replaces the pending set with what the feed currently reports, so a pending row disappears when its hold is released, and settles in place (or under a new id — banks reissue ids at settlement, in which case the old pending row is removed and the posted row arrives fresh).

What that means in practice:

• Spending caps, spending_by_category, and the by-month matrix count pending charges — they're committed money, and a cap is an early-warning device. The monthly income/spending bars exclude them; transfer roll-forward waits for settlement.

• The dashboard marks pending rows with a pending badge and muted styling on the Transactions page; get_transactions and /api/v1/transactions carry a pending field per row.

• Prefer rules over per-transaction overrides for pending rows. A rule matches the settled transaction whatever id it arrives under. A categorize_transaction override is keyed to the id, so it's dropped if the bank reissues the id at settlement — both the CLI and the MCP tool warn when you categorize a pending row.

• Dates can shift at settlement. A pending row missing a posted timestamp is dated by its transaction time; the real settlement time replaces it when it posts, which can move a transaction across month buckets.

• A hold that stays pending longer than the sync window may temporarily vanish from the store and reappear when it settles — temporary under-counting beats permanently double-counting a hold that settled under a new id.

Goals

Lightweight thresholds, not envelope budgeting: cap a category's spending per calendar month/year, track an account balance toward a target, or track contributions into an account per period. Progress is computed at read time — nothing is stored, so recategorizing transactions or a fresh sync changes goal progress retroactively, exactly like the categorization view.

# Cap net spending in a category per calendar month (or --period year).
goetta-finance goal add-spending Groceries --limit 400 --period month

# Track a balance: at_least = savings target / emergency-fund floor,
# at_most = debt ceiling / paydown. --by adds required-per-month pace math.
goetta-finance goal add-balance <account-id> --target 10000 --direction at_least --by 2027-06-01
goetta-finance goal add-balance <card-id> --target 2000 --direction at_most

# Contribute at least X into an account per month/year, counted from the
# account's own feed (--pattern) and/or its transfer-link ledger.
goetta-finance goal add-contribution <ira-id> --target 7500 --period year \
    --pattern "CASH CONTRIBUTION CURRENT YEAR" --baseline 3000 --baseline-date 2026-03-01
goetta-finance goal add-contribution <manual-savings-id> --target 800   # linked manual: no pattern needed

# Declare a recurring contribution no feed can see (payroll deduction):
# 150.00 accrues per biweekly payday, calculated from the anchor's schedule.
goetta-finance goal add-contribution <hsa-id> --target 4400 --period year \
    --recurring 150.00 --recurring-anchor 2026-01-09

goetta-finance goal list          # progress, status, and pace per goal
goetta-finance goal remove 3      # confirms unless --yes

Semantics worth knowing:

• Cap math matches the pie exactly. Spending caps reuse the same net-spending SQL as spending_by_category and the dashboard pie: refunds reduce the total, hidden accounts are excluded, pending transactions count, and periods are UTC calendar buckets.

• Liability accounts evaluate the absolute balance (amount owed): --direction at_most --target 2000 on a credit card means "owe under 2000" whichever way the institution signs the balance.

• Contribution goals sum absolute values of settled matched transactions (description OR payee, contains/regex like transfer links) — brokerages often sign cash-in negative — plus applied linked transfers, plus an optional pre-history --baseline counted into the period containing --baseline-date. Synced accounts require --pattern; manual accounts fed by transfer links need zero extra config. Ahead of the funding clock is on_track — the inverse of caps.

• Recurring contributions are declared, not observed. --recurring + --recurring-interval (weekly/biweekly/monthly) + --recurring-anchor accrue an amount per scheduled payday by calculation — for payroll deductions no feed can ever see. The payday series extends both directions from the anchor (monthly clamps to the month end: an anchor on the 31st pays Feb 28), each elapsed payday ticks the goal and its history bars, required_monthly nets out future scheduled paydays, and a goal whose schedule alone covers the target stays on_track between paydays. The CLI/dashboard prose and the MCP tool both disclose the declared portion.

• Status is on_track / at_risk (ahead of linear pace, or trend projects past --by; for contributions, behind the funding clock) / over (cap blown, ceiling breached) / met. Balance goals derive pace from the last 90 days of balance snapshots.

• Breach summary after sync. goetta-finance sync prints a yellow goal: line for each goal at status over; the daemon logs the same at WARNING after scheduled syncs. at_risk never fires a warning — it's pace noise by design.

• From Claude: list_goals (progress + pace), set_goal, remove_goal. The dashboard has a Goals page with progress bars.

Daemon mode

goetta-finance daemon runs one long-lived process that hosts:

• The dashboard at http://127.0.0.1:8765/

• The MCP endpoint at http://127.0.0.1:8765/api/mcp (streamable-HTTP transport — Claude Code and Claude Desktop both support this)

• An internal scheduler that runs collect() daily at --sync-at local time (default 06:00)

One process means one DuckDB write handle, which is what sidesteps the Windows DuckDB-lock conflict between serve and web. If the laptop was closed past the daily tick, the scheduler detects "we slept through it" on wake and runs a catch-up sync immediately.

goetta-finance daemon                         # defaults: 127.0.0.1:8765, sync at 06:00 local
goetta-finance daemon --sync-at 03:30         # sync nightly at 3:30am
goetta-finance daemon --no-schedule           # MCP + dashboard only, no automatic sync
goetta-finance daemon --no-mcp                # dashboard + scheduler only (e.g. headless server)

To register the daemon's MCP endpoint with Claude Code:

claude mcp add goetta-finance --scope user --transport http http://127.0.0.1:8765/api/mcp

(Re-run goetta-finance init to pick the daemon path interactively — it will also clear any stale stdio registration first.)

Stopping the daemon gracefully. Create a file named daemon.stop next to data.duckdb (the daemon prints the exact path at startup); the daemon notices within a couple of seconds, shuts down cleanly, and releases the DB lock. Prefer this over killing the process: a hard kill can freeze uncheckpointed WAL content, and DuckDB refuses to replay WAL that contains view DDL — a force-kill right after a schema migration can leave the database unopenable until the WAL is moved aside. The daemon never deletes the stop file (a stale one makes it exit at startup, loudly) — remove the file when you want the daemon to run again. This composes with supervisor scripts: have the supervisor skip its restart loop while daemon.stop exists, and a bounce becomes "create file, wait for exit, do your maintenance, delete file, relaunch".

In v1 the daemon does not auto-start. Keep it running in a separate terminal, or install one of the scheduling snippets below to start it at login.

Scheduling

You can run goetta-finance two ways: with the daemon (continuous, lazy-sync triggered too), or with an OS scheduler running goetta-finance sync periodically. The daemon is the better default when you want the MCP endpoint always available. Use the OS scheduler when you just want fresh data and the dashboard on demand.

Linux — systemd user units

# ~/.config/systemd/user/goetta-finance.service
[Unit]
Description=goetta-finance daily sync

[Service]
Type=oneshot
ExecStart=%h/.local/bin/goetta-finance sync

# ~/.config/systemd/user/goetta-finance.timer
[Unit]
Description=goetta-finance daily sync at 06:00

[Timer]
OnCalendar=*-*-* 06:00:00
Persistent=true

[Install]
WantedBy=timers.target

systemctl --user daemon-reload
systemctl --user enable --now goetta-finance.timer

Replace goetta-finance sync with goetta-finance daemon and drop the timer if you want the daemon at login instead.

macOS — launchd

<!-- ~/Library/LaunchAgents/com.user.goetta-finance.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.user.goetta-finance</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/goetta-finance</string>
    <string>sync</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict><key>Hour</key><integer>6</integer><key>Minute</key><integer>0</integer></dict>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.user.goetta-finance.plist

For daemon-at-login, swap the ProgramArguments to [..., "daemon"] and replace StartCalendarInterval with <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>.

Windows — Task Scheduler

# Daily sync at 06:00
schtasks /Create /TN "goetta-finance sync" `
  /TR '"C:\path\to\goetta-finance.exe" sync' `
  /SC DAILY /ST 06:00

# Or start the daemon at login (foreground in a window)
schtasks /Create /TN "goetta-finance daemon" `
  /TR '"C:\path\to\goetta-finance.exe" daemon' `
  /SC ONLOGON

Claude clients

goetta-finance serve is a stdio MCP server — it talks to a Claude client over a local pipe. Which clients work:

init runs through whichever clients it detects in step [4/4]. You can re-run init at any time to refresh registrations without going through the SimpleFIN steps again.

Using it from Claude

Once registered, restart your Claude client and try things like:

• "What's my checking balance?" → list_accounts

• "Show me everything I spent at Starbucks last month" → get_transactions(search="Starbucks", ...)

• "Chart my net worth over the last 90 days" → account_balance_history + Claude renders an inline chart artifact

• "How much did I spend on dining last month?" → spending_by_category returns categorized totals (non-spending categories excluded by default)

• "What's still uncategorized?" → top_uncategorized_patterns surfaces the biggest gaps; tell Claude which category each belongs to and it adds the rules

• "Is the data current?" → sync_status reports last sync + freshness

• "Am I on track with my dining budget?" → list_goals reports progress, pace, and status per goal

The MCP server exposes eighteen tools:

• list_accounts — all accounts with current balances (hidden accounts excluded by default)

• get_transactions — filter by account, date range, category, text search; up to 1000 rows. Every row carries a resolved category field.

• account_balance_history — per-account balance snapshots over time

• spending_by_category — categorized spending totals between two dates. Non-spending categories (Transfers, Income) excluded by default; opt in via include_non_spending=True.

• top_uncategorized_patterns — the curation entry point: the largest spending patterns sitting in Uncategorized, normalized via your prefixes.txt

• categorize_transaction / uncategorize_transaction — per-transaction override and its undo

• add_category_rule — add a rule from conversation; retroactive, validator-gated (same ReDoS checks as the CLI). Optional min_amount/max_amount refine matches by absolute amount (min inclusive, max exclusive).

• remove_category_rule — delete a user rule by id, equally retroactive. Default (seeded) rules are refused — those need the CLI's typed-confirmation remove-rule --force.

• list_goals — every goal with progress, status, and pace computed fresh (spending caps use the same math as spending_by_category)

• set_goal / remove_goal — create and delete goals from conversation; validator-gated identically to the CLI

• list_transfer_links — manual-account roll-forward links plus detected candidates (payee matching a linkless manual account's name), each with a ready-made link command

• link_account_transfers / unlink_account_transfers — create and delete transfer links from conversation; pattern-validated identically to the CLI, applies eligible transfers immediately

• sql_query — read-only SQL against the local DuckDB store (see security notes below). Prefer transactions_with_category over the bare transactions table when you want category info.

• sync_status — report when the SimpleFIN data was last synced and whether it's stale

• sync_now — trigger a fresh pull from SimpleFIN

sql_query is the workhorse for anything the other tools don't cover: most natural-language questions collapse to a SQL query plus a Claude-rendered artifact. The MCP server intentionally has no chart tool — Claude renders inline charts as artifacts from the data tools return.

The web dashboard

goetta-finance web serves seven views at http://127.0.0.1:8765:

• Accounts — current balances and as-of timestamps

• Net worth — Plotly line chart from balance snapshots

• Spending — monthly income (up) and spending (down) stacked bars

• By category — pie chart of the last 30 days' spending (Income excluded)

• Goals — progress bars and status badges per goal, evaluated at page load

• Transactions — sortable, searchable table with a category filter and a colored category badge per row. Filters update via HTMX without full page reloads. The badge tooltip carries the pre-filled CLI command to recategorize that specific transaction.

• Sync — last sync time and recent warnings/errors

The dashboard binds to 127.0.0.1 only by default. If you pass a non-loopback --host, the CLI prints a warning — there is no auth. Don't expose this to a network you don't fully trust.

Every surface also pins the Host header to the address it was bound to (the DNS-rebinding defense — see "Privacy and security"), so a request arriving under any other name gets 421 Invalid Host header. Behind a reverse proxy that forwards its own hostname, name it explicitly:

# daemon on loopback, reached from a phone through `tailscale serve`
goetta-finance daemon --allow-host mybox.tailnet.ts.net

--allow-host is repeatable, accepts an optional port (host.example:443), and always keeps loopback working.

Companion frontends (/api/v1 + --dash-dir)

If you want to build your own dashboard UI, the daemon (and web) also serve a read-only JSON API under /api/v1 — the same data the HTML pages render, machine-readable:

Conventions: GET-only, money as strings (never floats), timestamps ISO 8601 UTC. There is deliberately no CORS — serve your frontend same-origin instead:

goetta-finance daemon --dash-dir /path/to/your-spa/dist
# → your app at http://127.0.0.1:8765/dash/, calling /api/v1 same-origin

--dash-dir mounts any static single-page-app build (a folder containing index.html) at /dash. Use hash-based routing in the SPA — unknown deep paths under a static mount 404. The API has the same security posture as the HTML dashboard: no auth, whoever can reach the port can read your finances. For phone access, reach it over a VPN rather than your LAN — either bind the daemon to the VPN interface (--host 100.85.1.2) or keep it on loopback and put a tunnel in front of it (tailscale serve https / http://127.0.0.1:8765). A tunnel forwards its own hostname in Host, so pass --allow-host <that hostname> or every proxied request gets 421.

Where your data lives

Default paths (XDG-compliant on Linux/macOS, follows the same layout on Windows):

~/.local/share/goetta-finance/
├── config.json          # mode 0600 on POSIX; contains your SimpleFIN access URL
├── data.duckdb          # the database
├── prefixes.txt         # description-prefix strip list (see CUSTOMIZATION.md)
└── backups/             # default destination; override with `backup configure --dir`

Override the location with GOETTA_FINANCE_HOME=/some/other/dir or $XDG_DATA_HOME.

The SimpleFIN access URL is sensitive — it grants read access to your bank data. The default chmod 0600 keeps it owner-only on Linux/macOS; on Windows, file ACLs apply.

Backups

goetta-finance backup configure --dir ~/OneDrive/goetta-backups   # once
goetta-finance backup now                                          # or on demand
goetta-finance backup list
goetta-finance backup verify ~/OneDrive/goetta-backups/goetta-backup-20260811T132403Z.zip
goetta-finance backup restore ~/OneDrive/goetta-backups/goetta-backup-20260811T132403Z.zip

The daemon backs up on its own — after each successful sync, at most once a day, so archives track actual data change instead of ticking on their own clock. A backup failure never fails the sync (the rows are already committed; the next sync retries the copy), and a destination that's offline or locked by your sync client is logged, not fatal. backup configure sets the destination and retention in config.json; --disable turns the scheduled backup off, leaving backup now available.

Each archive is a single self-contained .zip: your rows as JSON Lines, a manifest (versions, schema-migration stamp, row counts, a sha256 per file), and prefixes.txt. It defaults to $GOETTA_FINANCE_HOME/backups, keeps the last 14 archives plus one per month for a year, and prunes the rest. Archives compress well — a few years of transactions is typically a fraction of the DuckDB file. The monthly tier is there because the daily tier can't outlive its own window: fourteen days of faithfully backing up damaged data is fourteen copies of the damage.

Every archive is verified before it counts. The zip is staged under a temporary name, restored into a throwaway database, checked against its own manifest (checksums, row counts, and the sum of every transaction amount), and only then moved into place. An archive that fails any of those never appears in the directory — so a cloud-sync client watching the folder can never upload a partial or unrestorable file.

Getting it off the machine is your sync client's job, not goetta-finance's. Point --dest at a folder OneDrive/Dropbox/Drive already syncs. Uploading directly would mean network calls beyond SimpleFIN and cloud credentials to store, which this project doesn't do.

Your SimpleFIN access URL is not included. config.json travels with access_url stripped, because an archive bound for cloud storage should not carry a live credential to your bank feed. Re-claim a setup token and re-run init after a restore. --include-credentials opts in if you're backing up somewhere you trust with it.

Why a logical dump instead of a copy of data.duckdb: while the daemon is running — exactly when an automated backup has to work — DuckDB's exclusive lock denies every other read handle on the file, so it cannot be copied, and the store's connection has enable_external_access=false, which blocks EXPORT DATABASE and COPY ... TO. Rows therefore come out through the open connection and are written by Python. That artifact is also more durable: JSON Lines is readable without DuckDB and survives the binary corruption modes this project has actually hit.

backup restore never overwrites in place — it moves the existing database to data.duckdb.pre-restore-<timestamp> and builds a fresh one. It replays migrations to the archive's stamp, loads the rows, then applies any newer migrations on top, so an archive from an older version still restores into a current install. Stop the daemon first (via daemon.stop).

Privacy and security

• No telemetry, no auto-update checks, no analytics. The only outbound network call is to SimpleFIN itself during sync. The dashboard's HTMX and Plotly assets are bundled locally — no CDN requests when you load it.

• sql_query has three layers of defense in depth to prevent prompt injection through transaction memo / payee fields:

  1. A pre-flight prefix whitelist (SELECT/WITH/SHOW/DESCRIBE). EXPLAIN is deliberately excluded.

  2. A BEGIN TRANSACTION READ ONLY wrapper — DuckDB's storage layer refuses in-database mutations that slip the whitelist (e.g., WITH cte AS (...) DELETE FROM accounts).

  3. The DuckDB connection is opened with enable_external_access=false (immutable at runtime), which blocks read_csv, read_blob, COPY ... TO 'file', and httpfs URLs — closing the information-disclosure and filesystem-exfiltration vectors.

  See CLAUDE.md "Things to avoid" for the full threat model and regression tests.

• The Host header is pinned on every HTTP surface (dashboard, /api/v1, /dash, /api/mcp). Binding to loopback is not protection by itself: a web page you visit can re-point its own domain at 127.0.0.1, after which the browser treats this server as same-origin and CORS never applies. Checking Host breaks that — the rebound request still carries the attacker's domain and gets 421. The allowlist is derived from the bind address plus any --allow-host names you add for a reverse proxy; a wildcard bind (0.0.0.0) can't be enumerated, so it disables the check and the CLI says so.

Known limitations

• Microsoft Store install of Claude Desktop: see the Claude clients table above. Use Claude Code or the direct-download Claude Desktop until init learns the MSIX-sandboxed config path.

• On Windows, serve and web cannot run simultaneously as separate processes. DuckDB takes an exclusive OS file lock on the database even for a read-only handle. Use goetta-finance daemon (one process, both surfaces) to avoid the conflict, or stop one before starting the other. macOS/Linux use advisory POSIX locks so concurrent read-only + read-write may work, but it isn't relied upon.

• Pending transactions are a snapshot, not history. They're stored and counted (see "Pending transactions" above), but ids are bank-unstable: per-transaction category overrides on pending rows may not survive settlement, and a long-lived hold can temporarily vanish between syncs.

• No cross-currency arithmetic. Each account row displays its own currency, and aggregate labels (net worth, chart axes) derive from your accounts — a GBP-only install shows GBP, mixed-currency installs show "mixed". But cross-account totals still sum raw numbers without FX conversion, so a mixed-currency net worth is not meaningful. Manual accounts default to USD; pass --currency EUR to account add to override.

• Categorization is flat and rule-based. No hierarchy, no transaction splits, no LLM auto-categorization, no transfer dedup (transfers between your own accounts show up in both balances). The default rules are USA-merchant biased; you'll add your own — see "Transaction categorization" above.

• backup now cannot run while the daemon holds the database lock — it says so and exits. That's what the daemon's own post-sync backup is for; use it, or stop the daemon via daemon.stop first. Backups also only happen on days a sync succeeds: if the daemon is down for a week, so are the backups.

• Restoring an archive taken before migration 0016 leaves the seeded categories in place. 0011 rebuilt transaction_overrides through a staging table, and the rename left categories holding a foreign-key dependency record naming a table that no longer existed, which broke every DELETE/TRUNCATE/upsert against it. Migration 0016 repairs that, so current databases are fine — but restore replays migrations only to the archive's stamp before loading rows, so an older archive lands in a database that still has the defect. Restore works within that limit (it inserts missing categories and updates the unconstrained columns) and reports anything it could not write.

• No inline category editing in the dashboard. Recategorize via the goetta-finance transaction categorize CLI; the transactions page surfaces the exact command in each badge's tooltip.

Development

pip install -e ".[dev]"

# All tests (POSIX-only file-permission test skips on Windows)
pytest

# Targeted runs
pytest tests/test_collector.py -v
pytest -k "query_sql" -v

# Lint and type-check
ruff check .
ruff format --check .
mypy --strict src/goetta_finance

A passing change has all four clean.

Security tooling

One-time setup:

pipx install pre-commit
pre-commit install

# gitleaks is a Go binary, install via your OS package manager:
#   macOS:   brew install gitleaks
#   Windows: winget install gitleaks
#   Linux:   see https://github.com/gitleaks/gitleaks/releases or your distro's repo

pre-commit install wires bandit / ruff / gitleaks into your git commit flow automatically. Manual audit run (e.g. before tagging a release):

bandit -r src/ -c pyproject.toml
pip-audit
gitleaks detect --source . --redact
ruff check .                       # includes ruff's S (bandit-derived) rules

Raw scanner output is git-ignored on purpose — see docs/SECURITY_AUDIT_2026-05.md for the narrative-summary policy. New findings should be reported there, not in raw JSON.

CLAUDE.md documents the operating principles, project layout, and patterns for adding new MCP tools, storage backends, or SimpleFIN fields. Read it before opening a PR.

License

MIT © 2026 Griffin Goepper. Use it, fork it, ship it.

Contributions welcome — see CONTRIBUTING.md.