# Tusk Ledger — comprehensive site content for LLMs > This file is the long-form companion to `/llms.txt`. It includes the > full content of every section on tuskledger.com — quick facts, all > features, every FAQ, the architecture description, the comparison > table, the install path, and the glossary — concatenated into one > markdown document so AI crawlers can ingest the entire site in a > single fetch instead of rendering JS or following links. Both files > follow the emerging llmstxt.org convention. Last updated: 2026-05-01 Site: https://www.tuskledger.com Main app repo: https://github.com/BradMorphsters/tuskledger MCP server repo: https://github.com/BradMorphsters/tuskledger-mcp License: MIT --- ## What Tusk Ledger is A local-first personal finance app for one human and their household. Mint died; the SaaS replacements want a subscription and your data on their servers. Tusk Ledger runs entirely on your laptop: the database is one SQLite file in your home folder, bank sync is Plaid talking direct from your machine to your bank, no Tusk Ledger server exists, and zero telemetry leaves your computer. It is built by one human, in active daily use by that human, and designed so an AI assistant (Claude, Cursor, Cowork, Claude Code) can help you install it, customize it, and run it without you needing to know Python. ## Quick Facts - **Stack:** Python 3.12 + FastAPI + SQLAlchemy + SQLite + Alembic (backend); React 18 + Vite + Recharts (frontend) - **Data location:** One SQLite file in your home folder. Move it, back it up, delete it like any other file - **Bank sync:** Plaid (you apply for your own production access; BYO API keys — Tusk Ledger doesn't proxy) - **Auth:** Optional email + TOTP MFA (single-user laptops can skip via DEV_BYPASS_AUTH) - **Agent surface:** AGENTS.md at repo root, `tuskledger doctor` JSON health-check CLI, CopyToAssistant UX hooks on errors, optional MCP server for typed AI-assistant access, optional local-LLM (Ollama) Dashboard AI Insights card AND in-app Ask panel - **Local LLM (optional):** Ollama at 127.0.0.1:11434, default model `llama3.1:8b` — powers TWO surfaces: (1) Dashboard's AI Insights narrative card, (2) in-app Ask panel (floating bottom-right button). Both feed pre-computed numbers to the model; the model only writes prose around them, never invents dollar amounts. Off by default; flip `LLM_ENABLED=true` to enable. Without the LLM, the Ask panel falls back to templated one-line answers from the same JSON bundles - **Telemetry:** None — no analytics, no phone-home, no third-party scripts - **Status:** Running daily by the maintainer; free Plaid tier covers ~100 accounts which is permanent for one household --- ## Features (homepage tile grid) ### Trading Tax Per-account FIFO matching mirroring the 1099-B. Chain-correct wash-sale calculator, cross-account transfer reconciliation, Form 8949 CSV, pre-flight sell modal, tax-loss harvest finder. ### Retirement Projection Multi-decade Monte Carlo with bracket-aware tax math, Roth conversion ladder, IRMAA, RMDs, survivor scenario, sequence-of-returns stress, age-banded spending phases. ### Bills Calendar 30-day forward calendar with paycheck overlay, per-day running balance, projected low-point tile, drag-to-reschedule for one-off events. ### Loans Full amortization with extra-payment slider, bi-weekly comparison, refinance modeler, PMI drop-off detection, HELOC modeling, multi-loan stacked timeline. ### Tax Prep Pack HSA contribution tracker, capital-loss carryover, Schedule C bucketizer with capital-vs-expense routing, business mileage. One PDF for your CPA. ### Budgets + Business Per-category targets with personal/business split. Auto-rollover for variable categories. Force-tag/untag overrides for the subscription detector. ### Ask — local-LLM chat Floating panel of curated questions ("how much did I spend", "what changed in my net worth", "what bills are coming up"). Numbers are pre-computed in Python; a local Ollama model writes the prose. No data leaves your laptop. --- ## Per-page tour (in-app pages, in order) ### Dashboard The page you open every morning. Net-worth + cash + month-delta tiles, anomaly insights surfaced before you go looking, and stale-balance alerts on accounts that haven't synced. - Net worth, assets, debt, this-month delta — with year-over-year overlay - Anomaly cards: subscription price changes, unusual spend, new merchants - Daily snapshot, payoff countdown tile, stale-balance alerts on manual accounts ### Transactions A spreadsheet that knows what categories are. Search, filter, edit in bulk, attach notes, pin for later — and when you recategorize a one-off, the app offers to make it a permanent rule. - Full-text search, saved filters, per-business filter chip - Bulk recategorize / tag / business-tag on multi-select - Auto-suggested rules, transaction notes, pin-for-later, per-merchant drill-down ### Spending & Income Heatmap of when you spend, leaderboard of who you pay, year-over-year of how that's shifting. - Spending heatmap by day-of-month with month-over-month overlay - Top merchants leaderboard with sparklines and click-to-drill - Year-over-year comparison, cash flow calendar, per-business filter ### Bills Calendar A real calendar, not a list. Bills and paychecks land on actual dates with a running balance underneath, and a low-point tile flags the day you should worry about. - 30-day forward calendar with paycheck overlay and per-day running balance - Projected low-point tile flagging the day balance dips closest to zero - Drag-to-reschedule one-off events, mark paid inline, recurring detection ### Loans One page that answers "what if I paid an extra $200/mo?" without a spreadsheet. - Full amortization with extra-payment slider and instant payoff curve - Bi-weekly vs monthly comparison, refinance modeler, PMI drop-off detection - HELOC modeling, multi-loan stacked timeline, surfaces manual liabilities ### Investments · Trading Tax The page accountants charge $300/hour to assemble. - Per-account FIFO matching mirroring the 1099-B, plus inter-account transfer reconciliation - Chain-correct wash-sale calculator — interleaved chronological pass, per-symbol or all-accounts scope - Pre-flight sell modal, tax-loss harvest finder, cash & buying power, Form 8949 CSV export ### Retirement Projection A retirement model that knows about progressive brackets, RMDs, IRMAA, the 0% LTCG rule, and what happens when one spouse outlives the other. - Monte Carlo + fan chart + probability-of-success, sequence-of-returns stress preset - Roth conversion ladder, IRMAA premium tiers, RMD math, fill-to-bracket conversions - Survivor scenario, age-banded spending phases, mortgage-payoff step events, depletion-age line ### Tax Prep Pack A year-end summary that pulls from every other page. - HSA contribution tracker (incl. payroll deduction) + capital loss carryover with year tracking - Schedule C bucketizer with capital-vs-expense routing, QBI (Section 199A) deduction - One umbrella PDF report: every form line, every supporting tile, ready for your CPA ### Ask · local LLM chat A floating panel of curated questions answered by a local Ollama model running on your own laptop. Numbers are pre-computed in Python (no hallucinated dollars) and the LLM only writes prose around them. Your transactions never leave the machine. - Nine prompts ship today: spending total, net worth change, upcoming bills, portfolio status, where am I overspending, top merchants, income, stale accounts, savings rate - Time-horizon chips on each (today / 1w / 1mo / 1yr) — pick the window, get a one-paragraph answer - Powered by Ollama (llama3.1:8b default) bound to 127.0.0.1; no LLM means a templated fallback so the panel still answers, just without prose --- ## Why local-first ### Your data never leaves your machine One SQLite file, not a SaaS. Plaid runs over TLS direct from your laptop to your bank. No cloud, no analytics, no telemetry, no marketing emails to opt out of. ### No one can shut it down Mint went away. Many of its replacements will eventually too. Tusk Ledger is yours — fork it, host it, hack it. The bus factor is one (you). ### No subscription, no upsell Free Plaid tier covers up to 100 connected items. For a personal household that's permanent. Past that you're paying Plaid directly, not me. --- ## Architecture Plaid talks to your bank, your laptop talks to Plaid, and that's the entire round-trip. There is no Tusk Ledger server in the middle because there is no Tusk Ledger server. Your AI assistant connects via a second local process — the MCP server — that never leaves your machine either. And when you turn on the optional Dashboard AI insights card AND the in-app Ask panel, both feed a third local process — Ollama, running an open-weight model on your own hardware — that writes the narratives and answers. Local data, local compute, local model. No cloud anywhere in the loop. ``` ┌─── NO CLOUD SERVER ───┐ │ │ Bank ───TLS───► Plaid ───TLS───► Your Laptop │ ┌───────────────┼───────────────┐ │ │ │ SQLite ──────► FastAPI ───────► React UI │ │ ├───► MCP server (stdio) │ → AI assistant │ └───► Ollama (127.0.0.1) → AI Insights + Ask ``` - **DATA AT REST:** Encrypted-at-rest SQLite file, 0600 perms - **TRANSPORT:** Plaid TLS, FastAPI bound to 127.0.0.1 - **AUTH:** Optional email + TOTP MFA - **AI INSIGHTS + ASK:** Optional Ollama (llama3.1:8b default), 127.0.0.1 only — powers both the Dashboard narrative card and the in-app Ask panel --- ## Comparison vs other tools | | Mint | Empower | Quicken | Spreadsheet | Tusk Ledger | | --------------------------------------- | ---- | ------- | ------- | ----------- | ----------- | | Local-only data | ✗ | ✗ | partial | ✓ | ✓ | | Open source / inspectable | ✗ | ✗ | ✗ | ✓ | ✓ | | No subscription | partial | ✓ | ✗ | ✓ | ✓ | | Bank sync (Plaid) | ✓ | ✓ | ✓ | ✗ | ✓ | | Bills + paycheck calendar | ✓ | ✗ | ✓ | ✗ | ✓ | | Tax-aware retirement model | ✗ | partial | partial | ✗ | ✓ | | Wash-sale calculator | ✗ | ✗ | partial | ✗ | ✓ | | Schedule C bucketizer | ✗ | ✗ | partial | ✗ | ✓ | | Zero telemetry | ✗ | ✗ | ✗ | ✓ | ✓ | | Survives if vendor folds | ✗ | ✗ | ✗ | ✓ | ✓ | | AI assistant (MCP) hookup | ✗ | ✗ | ✗ | ✗ | ✓ | | Local LLM for AI insights | ✗ | ✗ | ✗ | ✗ | ✓ | | In-app local-LLM chat (Ask) | ✗ | ✗ | ✗ | ✗ | ✓ | --- ## Talk to your assistant — sample prompts (with MCP wired in) Once you've added the optional `tuskledger-mcp` server to your AI assistant's config, the assistant gets typed access to your Tusk Ledger data via 13 tools (list_accounts, query_transactions, get_holdings, get_retirement_projection, etc.). Useful prompts to get a feel for what's possible: **Daily check-ins** - "What's my cash position right now and any anomalous transactions in the last 7 days?" - "Did any subscriptions raise their price this week?" - "Show me transactions over $100 from last week, grouped by merchant" **Monthly rhythms** - "How am I tracking against budget this month? Which categories are over and by how much?" - "Recompute net worth and tell me the YoY change" - "List recurring bills due in the next 14 days with running balance" **Tax season** - "What's my YTD realized capital gain/loss from trading?" - "Are there any wash sales I should be aware of before I sell more?" - "Pull my HSA contributions and tell me how much room I have" **Customizing the app itself** - "Add a Dashboard tile that shows my coffee spending by week" - "Hide income from the Subscriptions tab — recategorize Patreon payouts as Income" - "Make the Investments page exclude Robinhood Comp1K from the totals" --- ## FAQ ### Why local-first? Your bank data should live where your bank statements live — on your machine. No SaaS to outlive, no breach to be in, no marketing emails to opt out of. SQLite is in your home folder; you can move it, back it up, or delete it like any other file. ### What if I switch computers? Copy the .db file. That's the entire app's state. Restore on the new machine, run ./start.sh, and you're back exactly where you left off. Plaid access tokens carry over too unless they've expired. ### How are backups handled? The app auto-snapshots the SQLite DB on every startup to a sibling folder. You decide what backup tooling fits the rest of your life — Time Machine, rsync, encrypted external drive, an iCloud Drive folder. The DB is one file. ### What if Plaid changes pricing? Plaid's free tier covers 100 connected items. For one household, that's permanent. If you go past it, you pay Plaid directly — there's no middle layer marking up your usage. If Plaid disappeared tomorrow you'd lose bank sync but keep every transaction you'd already pulled. ### Can I get my data out? It's already out. The whole DB is on your laptop in plain SQLite. Open it in DB Browser, dump it to CSV, query it from a Python REPL — there's no export button because there's no lock-in. ### Is Demo Mode required? Demo mode ships enabled by default so you can poke around with seeded data before linking real accounts. One toggle in Settings flips you to real mode; the app refuses to mix the two and prompts before the switch. ### Is auth required? Optional. There's full email/password + TOTP MFA support if you want it; on a single-user laptop many people skip it via DEV_BYPASS_AUTH. Your machine, your call. ### How do I report bugs / contribute? GitHub issues for bugs, GitHub PRs for code, GitHub discussions for ideas. The main app and the MCP server are separate repos with their own issue trackers — file the bug where the bug lives. ### What does the MCP server do — and is it required? `tuskledger-mcp` is a separate, optional Model Context Protocol server. Add it to your AI assistant's config (one `uvx` line) and Claude / Cursor / Cowork can call typed tools like list_accounts, query_transactions, get_holdings, get_retirement_projection — instead of scraping the React UI. The main app runs perfectly without it; the MCP server just makes agent-driven workflows fast. ### Does the MCP server send my data anywhere? No. It binds to 127.0.0.1 only and talks to your local Tusk Ledger backend over stdio. The "MCP cloud" doesn't exist — it's one Python process on your machine talking to another Python process on the same machine. Your assistant reads the responses, your assistant's provider sees those responses (whichever LLM you chose), and that's the entire trust boundary. ### How do the AI Insights work without sending my data to OpenAI / Anthropic? There's an optional Dashboard card that runs an open-weight LLM (llama3.1:8b by default) on your own hardware via Ollama. Your transactions never leave the laptop — Ollama binds to 127.0.0.1, the FastAPI backend feeds it pre-computed numbers, and the model writes a 2-3 paragraph plain-English narrative around those numbers. Off by default; flip `LLM_ENABLED=true` in backend/.env and pull a model with `ollama pull llama3.1:8b` to turn it on. On Apple Silicon a narrative renders in 5-15 seconds; on Intel hardware drop to phi3:mini or leave it off. ### Can the local LLM hallucinate the dollar amounts? No — by design. The narrative service builds the prompt from a structured JSON bundle of pre-computed totals, deltas, and category leaders, and the system prompt explicitly forbids the model from inventing numbers. Every dollar figure in the prompt is rounded to whole dollars at the serializer boundary so the model can't even see fractional cents. The model writes prose around the numbers; the numbers themselves come from Python. Same load-bearing invariant applies to percentages and merchant attributions. ### What is the Ask panel and how does it differ from the AI Insights card? Ask is a floating button in the bottom-right corner of the app that opens a slide-in panel of curated questions — "how much have I spent", "what changed in my net worth", "what bills are coming up", "where am I overspending", "top merchants", and a few more — each with horizon chips (today / 1w / 1mo / 1yr where it makes sense). Click a question, the local Ollama model writes a short answer using numbers pre-computed in Python. Same no-hallucination invariant as the Dashboard AI Insights card, just on-demand and per-question instead of a daily card. Both run on the same local Ollama process; turning LLM_ENABLED off makes Ask fall back to a templated one-line answer derived from the same JSON bundle, so the panel still answers without prose. Nothing leaves your laptop in either case. --- ## Install — three paths ### 1. Hand it to your AI assistant (recommended) Tell Claude Code / Cursor / Cowork: "Set up tuskledger." It clones the repo, reads AGENTS.md, installs the venv + node modules, walks you through Plaid setup, and gets the dev servers running. When something errors out, paste the error back; the gotchas are documented. ### 2. By hand (five lines) ``` git clone https://github.com/BradMorphsters/tuskledger.git cd tuskledger cp backend/.env.example backend/.env # then add your Plaid keys ./start.sh open http://127.0.0.1:5173 ``` ### 3. Wire in the MCP server (optional) Add to your AI assistant's MCP config: ``` {"mcpServers": {"tuskledger": {"command": "uvx", "args": ["tuskledger-mcp"]}}} ``` Now the assistant can call typed tools like `list_accounts`, `query_transactions`, `get_retirement_projection` without scraping the UI. --- ## Glossary **Tusk Ledger** — A local-first personal finance app that runs entirely on your laptop. Bank data syncs from Plaid direct to a SQLite file in your home folder; nothing is sent to a Tusk Ledger server because no Tusk Ledger server exists. **AI Insights card** — A Dashboard tile that summarizes the current month's spending in 2-3 plain-English paragraphs. The text is written by a local Ollama model around numbers pre-computed in Python — the model never invents dollar figures. **Ask panel** — A floating button in the bottom-right of the app that opens a slide-in panel of curated questions ("how much have I spent", "what changed in my net worth", etc.) with horizon chips. Each question is answered by the same local Ollama model that powers AI Insights, using pre-computed numbers. Falls back to a templated one-liner when the LLM is disabled. **No-hallucination invariant** — The design rule that keeps a small local model trustworthy in a finance app: every dollar figure shown to the user is computed in Python from the database, the prompt rounds to whole dollars at the serializer boundary, and the system prompt forbids the model from inventing any number. The model writes prose around the numbers; the numbers themselves come from code. **tuskledger-mcp** — An optional Model Context Protocol server that gives an AI assistant typed access to Tusk Ledger data without scraping the UI. Lives at github.com/BradMorphsters/tuskledger-mcp. **Common-account math** — How net worth deltas are computed honestly when accounts get added between two snapshots: the delta is taken on the INTERSECTION of accounts present in both snapshots, so a newly onboarded $200k 401(k) doesn't masquerade as $200k of growth. **Wash-sale chain-correct calculator** — Tusk Ledger's calculator for IRC §1091 wash sales does an interleaved chronological pass across all of a symbol's lots so a single replacement purchase can cascade through multiple losses. **Tax Prep Pack** — A year-end PDF report that pulls from every other page (HSA, capital loss carryover, Schedule C, mileage, QBI) and stitches them into a single document for your CPA. **Retirement projection** — A multi-decade two-phase (accumulation + withdrawal) simulator with progressive bracket math, RMDs, IRMAA tiers, Roth conversion ladder, survivor scenario, sequence-of-returns stress, Monte Carlo with fan chart and probability of success, age-banded spending phases, and pre-59½ bridge analysis. **Bills calendar** — A 30-day forward calendar with paychecks, bills, and a per-day running balance. Includes a projected low-point tile flagging the day balance dips closest to zero; supports drag-to-reschedule for one-off events. **Demo mode** — Tusk Ledger ships with a parallel synthetic dataset. One toggle in Settings flips between real and demo databases; the app refuses to mix them and prompts before each switch. **AGENTS.md** — A working-memory document at the repo root for AI assistants — describes permission boundaries, common operations, project conventions, and known footguns. **tuskledger doctor** — A CLI command that runs ~13 environment checks and emits a stable JSON shape an AI assistant can ingest. **BYO Plaid keys** — You apply for your own Plaid production access and put the keys in backend/.env. Tusk Ledger doesn't proxy or markup; you pay Plaid directly. Free tier covers 100 connected items. **DEV_BYPASS_AUTH** — A backend .env flag that skips the email/password + TOTP MFA login flow. Refuses to start if the server is bound to a non-localhost interface. --- ## Built with FastAPI · React · SQLAlchemy · SQLite · Vite · Plaid · Recharts · MCP · Ollama ## Links - Marketing site: https://www.tuskledger.com - Main app source: https://github.com/BradMorphsters/tuskledger - MCP server (lets your AI assistant query Tusk Ledger directly): https://github.com/BradMorphsters/tuskledger-mcp - Short llms.txt summary: https://www.tuskledger.com/llms.txt - This file: https://www.tuskledger.com/llms-full.txt