local-budget

Brand: PRESS v0.7.2 — The report's colour and type tokens are generated from the press skill, not maintained here. The token blocks marked press:tokens are generated; edit press/brand/tokens.json and re-emit instead.

A local-first, agent-first personal spending agent for your bank/financial statements. Your data stays in one local data/budget.db on your own machine — full account numbers and every transaction. You don't click through an app to understand your money; you talk to it from a Claude Code session pointed at this repo, through a small MCP server and a set of no-code skills. The server runs no inference — it just exposes deterministic, column-guarded tools; the reasoning happens in your Claude Code session under your own subscription auth.

How it works

1. Import. Drop a bank statement export (.qfx/.ofx/.csv) in your inbox and run budget intake (or budget import <file>). Account numbers are masked at import time; the raw transaction is stored once in data/budget.db.

2. The MCP server. The committed .mcp.json wires up uv run budget-mcp — a standalone stdio MCP server that exposes 32 deterministic tools (18 read, 14 write) over budget.db. Every tool runs behind a connection-scoped, column-level SQLite authorizer (db.agent_connect): imported facts are immutable, and account numbers, raw OFX, and raw payee/memo are read-denied — the sanitized merchant_norm is the agent's only merchant text. Read tools return a {data, rendered} pair so the agent can print an exact, deterministic markdown block instead of paraphrasing numbers.

3. The skills. Eight no-code budget-* skills (under .claude/skills/) orchestrate those tools in your session — grounded in a shared budget-analyst persona that enforces "never invent a number, print the tool's rendered block verbatim, confirm before any write."

4. The dashboard (optional). budget serve starts a loopback-only web dashboard at http://127.0.0.1:8770 — a deterministic visual glance at your spending. It runs no Claude inference.

Open a Claude Code session in this repo and the MCP tools (.mcp.json) and the budget skills (.claude/skills/) load automatically. Then just ask: "How much did I spend on groceries this month?", "Categorize my unreviewed merchants," "Give me a monthly brief."

Privacy

• One local DB. Everything lives in data/budget.db, which is gitignored and never committed.

• Account numbers masked at import and read-denied to the agent; raw payee/memo read-denied by the authorizer — the agent sees only the sanitized merchant_norm.

• The agent can never alter an imported fact. The write authorizer permits only the derived category columns and the app-config tables — not the imported transaction rows. No tool can rewrite history.

• The dashboard is loopback-only by default; binding a non-loopback host requires a 32+ char LOCAL_BUDGET_API_TOKEN (see .env.example).

Quick start

uv sync

# import a bank statement export
uv run budget import ~/Downloads/statement.qfx
# …or drop exports in your inbox and run:
uv run budget intake

# then open a Claude Code session in this repo and ask your money questions —
# the budget skills + MCP tools auto-load from .mcp.json and .claude/skills/.

For the optional visual dashboard:

uv run budget serve --open   # http://127.0.0.1:8770 (loopback-only)

Run uv run budget --help for the full CLI (import, intake, report, reconcile, recurring, limits, subscriptions, backup, …).

Skills

All eight reference the shared budget-analyst persona; visual reports follow the shared budget-visualizer discipline.

Evals

Skills are tested like code. scripts/eval.py runs a deterministic mock tier (replays committed transcripts, no spend) in CI, plus an opt-in live tier (--live, drives claude -p) that is cost-capped for when you want to verify real model behavior.

What's committed vs. local

Install the commit guard so personal data can't slip into git:

ln -sf ../../scripts/secret-scan.sh .git/hooks/pre-commit

Requirements

Python 3.12. MIT licensed (see LICENSE).