Check-in workflow
A check-in is one periodic pass over your finances: an immutable record of the facts on a date, a diff against last time, and a short note you write about what it means.
Four slash commands cover it — one to lay down the workspace, one to run a period, and two for the snapshot files themselves.
Where to run it
Section titled “Where to run it”Run every check-in command from the directory that holds your state file (*_finplan_state.json), so the snapshots/ workspace sits beside it:
my-finances/├── household_finplan_state.json└── snapshots/ ├── README.md ├── index.md ├── checkin.template.md ├── 2026-01-15/ │ ├── snapshot.json │ └── checkin.md └── 2026-04-15/ ├── snapshot.json └── checkin.md1. Scaffold the workspace, once
Section titled “1. Scaffold the workspace, once”/finplan:checkin-init
Section titled “/finplan:checkin-init”Creates the snapshots/ directory and three files: a README.md with the procedure, a regenerable index.md of your check-ins, and checkin.template.md, a reference copy of the note template.
It is scaffold-only — it never builds or saves a snapshot. It also refuses to run twice: if a workspace already exists, pass --force to re-lay those three files. A --force re-run never touches an existing snapshots/<date>/ directory; saved history is safe.
2. Run a check-in, each period
Section titled “2. Run a check-in, each period”/finplan:checkin
Section titled “/finplan:checkin”/finplan:checkin # today/finplan:checkin 2026-04-15 # a backdated check-in/finplan:checkin --force # overwrite an already-saved dateIn order, it:
- Warns if your plan is stale. It reads
last_updatedfrom your state file and reports how many days old it is. Past roughly 90 days, it suggests running/finplan:checkupfirst, since a snapshot inherits the staleness of the state it captures. The warning does not block the run. - Builds the snapshot — net worth, allocation, account and category rollups, income, and goal funding, as of the check-in date.
- Saves it to
snapshots/<as_of>/snapshot.json, and refuses to overwrite an existing one without--force. - Diffs it against your previous check-in — the net-worth change, allocation drift, notable account and category moves, and any goals or account types added or removed. On a first check-in there is nothing to diff against, and it says so.
- Seeds the note at
snapshots/<as_of>/checkin.md, filling in the numbers and leaving every narrative section blank. - Adds a row to
snapshots/index.md— date, net worth, allocation, the state’s ownlast_updated, and the snapshot path — kept oldest-first.
Then open snapshots/<as_of>/checkin.md and write the narrative sections.
3. Read and write snapshots directly
Section titled “3. Read and write snapshots directly”/finplan:save-snapshot
Section titled “/finplan:save-snapshot”Writes the snapshot built earlier in the conversation to snapshots/<as_of>/snapshot.json, taking the date from the snapshot itself. /finplan:checkin calls this for you; run it by hand when you built a snapshot separately. It refuses to overwrite a saved date without --force.
/finplan:read-snapshot
Section titled “/finplan:read-snapshot”Reads a saved snapshot back with a targeted query, so a whole record never has to enter the conversation:
/finplan:read-snapshot # summary of the latest/finplan:read-snapshot latest derived.net_worth # one subtree of the latest/finplan:read-snapshot 2026-01-15 # summary of a specific date/finplan:read-snapshot 2026-01-15 provenance # one subtree of that datelatest resolves against each snapshot’s own as_of field, so the record you get back cannot disagree with the date written inside it.
Snapshots vs. state
Section titled “Snapshots vs. state”Your state file is mutable — the current picture, rewritten every time something changes. A snapshot is immutable — what was true on one date, written once and never edited unless you deliberately overwrite that date with --force.
That split is what makes a diff meaningful: two snapshots are two fixed records, so the delta between them is history rather than an artifact of editing. Keep the snapshots/ directory in version control if you want the notes to travel with the numbers.
The tools behind it
Section titled “The tools behind it”The commands are thin clients over four MCP tools, documented under Snapshots: build_snapshot, diff_snapshots, get_checkin_template, and fill_checkin_template. The template lives on the server and is fetched fresh on every run, so the note can’t drift from the snapshot schema as it evolves.