个人理财助手

1. Install Ollama and pull a capable model

ollama pull llama3.3:70b # or qwen2.5-coder:32b, deepseek-r1, etc.

2. Install claude-code-router

npm install -g @musistudio/claude-code-router

Use on claude.ai (no installation)

If you use Claude on the web or mobile and don't want to install anything, use the Projects template:

1. Create a new Project on claude.ai
2. Paste the contents of projects-template/PROJECT_INSTRUCTIONS.md into the Project instructions field
3. Start chatting — budgeting, debt advice, savings goals, net worth tracking, and tax questions all work conversationally

Limitations: claude.ai runs in a browser and cannot access your computer's filesystem. That means no CSV import, no local SQLite database, no bank sync, no live prices, and no Monte Carlo simulations — those all require files or local storage that the browser can't reach. What works: conversational budgeting, tax questions, debt advice, savings goals, and net worth tracking based on what you tell it. For the full experience, use the Claude Code skill below.

---

Install in Claude Code

Clone the repo and add it as a skill:

git clone --recurse-submodules https://github.com/googlarz/finance-assistant.git
cd finance-assistant
pip install -r requirements.txt

Add as a skill in ~/.claude/settings.json:

{
  "skills": [
    {
      "name": "finance-assistant",
      "path": "/path/to/finance-assistant"
    }
  ]
}

Then start a session: What's my financial health?

Verify your install

python3 skill.py --version    # finance-assistant 3.9.2
python3 skill.py --doctor     # runs health checks on your setup

---

Install in Claude Cowork

Cowork gives you the same agent capabilities as Claude Code in a desktop-friendly interface. For the best experience, set it up as a dedicated project:

1. Create a new project Open Cowork → Projects → New Project. Name it something like Finance.

2. Add a project instruction In the project's Instructions field, add:

Always load and use the Finance Assistant skill /finance-assistant.
Start every session by running skill.py to load my profile and surface any alerts.

3. Start the project Open the Finance project and say: What's my financial health?

Claude will load your profile, surface any session alerts (budget warnings, upcoming bills, tax deadlines), and be ready for any finance question.

Tip: Pin the Finance project to your Cowork sidebar so it's one click away at the start of each day.

---

Quick Start

Example Conversations

Screenshot

3. Configure it to route to your local Ollama (see router README)

```

Full recipe + accuracy harness: docs/sovereignty.md walks through setup and ships a sovereignty_check.py harness that measures the local model's tax-reasoning accuracy against the deterministic engine on your hardware — so you can see the tradeoff before trusting it, instead of taking this README's word for it.

Honest tradeoff: open local models are meaningfully weaker than Claude on multi-step tax reasoning, bracket math, and "explain why" answers. You will get less precise tax calculations and worse advice quality. Use this mode if data sovereignty matters more than answer quality — e.g. when working with confidential client data or during the EU sovereignty audit at your job. For your own personal finances, the privacy gain over the standard local-first model (your data never leaves your machine; only the conversation does) is usually not worth the quality drop.

About the "Real math. Real law." promise at the top of this README: that guarantee holds on the default Claude path — the tax engines apply real statute and the calculations are bracket-accurate regardless of model, but interpreting your situation correctly (which rule applies, what's deductible) is where a weaker local model degrades. Sovereignty mode explicitly trades away the advice-quality half of that promise. The deterministic math (locales/<code>/tax_calculator.py, invoked by scripts/tax_engine.py) runs the same either way; the reasoning around it does not. Pick the default path for anything tax-accuracy-critical.

---

Module Reference

Insight Pipeline

The insight engine (insight_engine.py) runs after every major data update. It dispatches to domain-specific generators:

budget_insights → savings_insights → investment_insights
→ debt_insights → insurance_insights → tax_insights → net_worth_insights

Each insight carries a 4-level status: - ready — actionable right now - needs_input — needs one more fact from you - needs_evidence — needs a document or statement - detected — background risk found, FYI

And a confidence label: Definitive | Likely | Debatable | Avoid

Locale Plugin System

Tax rules are country-specific plugins in locales/<country_code>/. Each locale exports a standard interface:

LOCALE_CODE = "de"
SUPPORTED_YEARS = [2024, 2025, 2026]
def get_tax_rules(year) -> dict
def calculate_tax(profile, year) -> dict
def get_filing_deadlines(year) -> list[dict]
def get_social_contributions(gross, year) -> dict
def generate_tax_claims(profile, year) -> list[dict]

The German locale is fully bundled via the locales/ submodule. New locales can be scaffolded automatically via locale_loader.py.

`ModuleNotFoundError: No module named 'locales'`

The locale data lives in a git submodule. If you cloned without --recurse-submodules, run:

git submodule update --init --recursive

Then re-run python3 skill.py --doctor to verify.

1,208 tests — all modules, all locales, all official tax authority cases

Troubleshooting