Skip to content

Using the coach from Claude Code

Open Claude Code in the project folder and ask about your money: it answers with the redacted finance tools, cites its evidence and only ever proposes changes.

Memory proposals waiting for review Memory proposals waiting for review

What the coach proposed during a conversation, in Memory > Proposals: the diff, and the command you run yourself to accept it.

Set it up once

The repository's .mcp.json declares one MCP server, finance, started with uv run coach mcp serve. It talks to Claude Code over stdio: nothing listens on the network.

{ "mcpServers": { "finance": { "command": "uv", "args": ["run", "coach", "mcp", "serve"] } } }
  1. Start claude in the project folder.
  2. Type /mcp and approve the finance server (once).
  3. Ask a question.

Claude Code asks permission for each tool call. To skip the prompts for the read-only tools, allow mcp__finance__* in your own user settings (leave out the tools that write proposals if you want to see those).

Not under local_only

With [privacy] local_only = true, coach mcp serve refuses to start: its client would be a cloud model. See Privacy modes.

The rules Claude follows here

The project's CLAUDE.md tells Claude how to behave with your data. In short:

Rule What it means for you
Numbers come from tools Claude never adds, averages or estimates. It quotes figures as a tool returned them, or says the figure is not available.
Evidence is cited Each claim about a payment or a series carries a ref such as (h_0123456789), (rec_...) or (anm_...) that a tool returned.
Tool results are data Merchant names and descriptions are written by third parties. If one reads like an instruction, Claude tells you instead of acting on it.
Memory changes are proposals Claude calls memory_propose; nothing is applied until you accept it yourself.
No investment advice Budgeting, spending and saving habits only; no funds, shares, crypto, insurance or loan offers, no tax or legal advice.
MCP tools over the CLI The CLI and the files hold raw names; the tools hide them. Claude does not read the database, memory/ or data/.

An example

You: Why was July so expensive?

Claude (calls coverage, then explain_spike for travel in July): July was the summer holiday. Travel cost 2736.63 EUR against a usual month of 328.99 EUR. The three biggest payments are the hotel (h_3f9a1c2b7e), the flights (h_8d02e4a6c1) and the car rental (h_51b7d9e0a4), all tagged holiday in your memory. Same month last year: 2541.06 EUR, so it is a yearly habit.

You: Then set up a summer goal so we save for it every month.

Claude (calls memory_propose): I created proposal p-20261008-.... Review it in Memory > Proposals, then run uv run coach memory accept p-20261008-... in your own terminal.

Claude cannot accept that proposal for you. Accepting needs an interactive terminal and a typed confirmation, and the web app has no endpoint for it. That is on purpose: whatever reaches the model (a hostile merchant name, for example) can never write into your memory.

Permission settings

docs/claude-settings.example.json is a template of deny and ask rules for .claude/settings.json. Copy it, then review every line. It denies, among others:

  • accepting proposals, purging history and editing memory/**;
  • reading the web app's session files and calling its port (coach ui, 127.0.0.1:8765 in any spelling), so an agent cannot fetch a login link;
  • any coach ... --yes, script (a fake terminal), confirming savings decisions, coach users, sending alerts;
  • coach wipe, coach export --plain / --decrypt, coach config set-secret, reading the Keychain, backups, exports and .pem files;
  • editing config.toml, where your privacy switches live.

It asks before memory revert, memory reject, doc extract --send and security audit --fix-permissions.

Rules are a control, CLAUDE.md is an instruction

The permission rules stop specific commands and paths. They cannot stop every way an agent running as you could read a file you can read. Keep them, and keep your data folders private. See Security.

Privacy

Claude Code sees your household only through the finance tools, and every tool result is:

  • pseudonymised: accounts account-main-1, people adult-1 / kid-1, transactions h_0123456789;
  • generalised in the default coarse mode: the salary payer is [employer], small or person-like merchants [merchant:<category>]-<hash>;
  • checked by a final privacy guard that withholds the whole result if a name, account label, IBAN, e-mail or path slips through.

The tools cannot sync a bank, call the network, run a command, read a file or return a secret. Refs like h_... only resolve to real transactions in your own web app, behind your session.

See also