Ledger

Local, private, multi-currency personal finance tracker. No accounts, no build step. Data lives in your browser (IndexedDB). Optional live sync uses a first-party household API on the same site: one encrypted LED1 snapshot, shared household token, no Dropbox or Google OAuth.

Run it

Service workers don't run from file://. For UI-only local work, python3 -m http.server 8000 still works. Household sync needs the /api/sync function: npx vercel dev or the test static server (node -e "require('./tests/static-server').startStaticServer(8000).then(({port})=>console.log(port))"). Production is the Vercel deploy — open the https URL, then Add to Home Screen on each phone. Works fully offline after first load; sync runs when you are back online.

Empty on first open: click Load sample data (or Settings → Load sample data) to explore a 3-month multi-currency dataset, then Wipe all data and drop in your real CSVs.

Getting your data in

Credit card: the web portal's "Download transactions / statement → CSV". Wealthsimple: Activity → Export, or Statements → CSV, once per account. Drag the files onto the app, confirm the column mapping once per format (it's remembered per file layout), and re-importing overlapping statements adds zero duplicates. There is no live bank connection by design - that needs a server holding your credentials, which is the one thing this app refuses to be.

A proposed daily review-queue (still no bank creds in the PWA) is documented in docs/adr/0001-household-payment-automation.md and exercised by the mocked spike in spike/household-ingest/.

Exchange rates: Settings → enter EUR-per-unit rates for USD/CAD (e.g. USD 0.92). Everything converts to your base currency (default CAD) through these manual rates; edit one and every view recalculates. Originals are never overwritten.

Jars are T. Harv Eker allocation buckets - income auto-splits by percentage, spending draws from each category's jar, all editable. The Recurring panel on Overview auto-detects subscriptions and flags price hikes.

AI check-in (local model)

Click ✦ in the header for a private chat with a model running on your own machine via Ollama. Nothing is sent to any cloud - the model answers from your ledger and can file transactions for you: "daily check-in: $18.75 Tim Hortons, $120 Loblaws, $500 freelance income into Amex" categorizes and saves everything, and you can ask "what did I spend today?" or "how's this month?".

1. Install Ollama and a tool-calling model: ollama pull qwen2.5:3b.
2. Allow the app's origin to call Ollama from the browser: launchctl setenv OLLAMA_ORIGINS "*" (or OLLAMA_ORIGINS="* ollama serve" from a terminal), then restart Ollama. The chat and Settings → Local AI → Test will say so if CORS blocks you.
3. Open ✦, pick the model in the dropdown, and check in.

Works on the deployed https URL too, as long as Ollama runs on the same machine - browsers allow https pages to reach http://localhost. Model choice and endpoint are stored per device and never synced. Transactions the model saves are marked with source ai (visible in the JSON export), and its category choices feed the same learning rules as manual edits.

Telegram daily check-in (local bridge)

The Telegram routine is optional and stays on your Mac. At 8:30pm, Hermes asks what you spent. When you reply, Hermes adds only the transaction details you confirm to a local queue. Ledger pulls that queue from http://127.0.0.1:8788, writes the transactions to its own IndexedDB, then acknowledges them. The bridge has no public network listener and does not read your ledger, bank accounts, or household-sync passphrase.

1. Start the local bridge: node bridge/ledger-bridge.js serve.
2. Open Ledger → Settings → Telegram daily check-in → Pair this Ledger. Pairing happens over loopback only; no key is shown or copied.
3. Hermes queues a confirmed transaction with: node bridge/ledger-bridge.js enqueue --date YYYY-MM-DD --desc "Merchant" --amount -12.34 --currency CAD --account "Cash" --category Dining.

Ledger also checks the queue whenever the app opens or returns to the foreground. It will not duplicate a queued transaction after an interrupted acknowledgement.

iPhone without opening Ledger on the Mac: a Mac background job encrypts the same queue into /api/bridge-inbox (LED1, same household token and passphrase as sync). Phones consume that inbox during normal sync. Setup: bridge/README-bridge-inbox.md. Tag non-Telegram sources with enqueue … --source grokbot.

Sync (optional, household devices)

Off by default. When on, each device encrypts a full snapshot with a passphrase (LED1 / AES-GCM) and GET/PUTs that ciphertext to /api/sync on this same origin. The server stores bytes it cannot read. Connect never leaves the home-screen PWA — there is no OAuth redirect.

Every device uses the same household token and the same passphrase. That is one household identity and one ciphertext (issue #13). Disconnect or wipe on one phone does not wipe the others or the household copy.

1. Once on the host: set HOUSEHOLD_SYNC_TOKEN in the Vercel project (encrypted env). Production also uses the private Blob store (BLOB_READ_WRITE_TOKEN) for household/ledger.bin. Local tests use a temp directory.
2. Once on each device (Hendrik’s phone, desktop, and the other phone): open Ledger → Settings → Sync → paste the household token → Connect household → enter the same passphrase → Unlock & sync.

If sync fails, open Settings → Sync diagnostics for service-worker state, connection status, and a concrete next step (missing token, reconnect, offline, wrong passphrase, conflict/rate limit). Secrets (token, passphrase) are never shown there.

This is the beginning of the README. Read the rest at the original. Read the full README ↗