Skip to content

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.


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.md

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.


/finplan:checkin # today
/finplan:checkin 2026-04-15 # a backdated check-in
/finplan:checkin --force # overwrite an already-saved date

In order, it:

  1. Warns if your plan is stale. It reads last_updated from your state file and reports how many days old it is. Past roughly 90 days, it suggests running /finplan:checkup first, since a snapshot inherits the staleness of the state it captures. The warning does not block the run.
  2. Builds the snapshot — net worth, allocation, account and category rollups, income, and goal funding, as of the check-in date.
  3. Saves it to snapshots/<as_of>/snapshot.json, and refuses to overwrite an existing one without --force.
  4. 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.
  5. Seeds the note at snapshots/<as_of>/checkin.md, filling in the numbers and leaving every narrative section blank.
  6. Adds a row to snapshots/index.md — date, net worth, allocation, the state’s own last_updated, and the snapshot path — kept oldest-first.

Then open snapshots/<as_of>/checkin.md and write the narrative sections.


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.

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 date

latest resolves against each snapshot’s own as_of field, so the record you get back cannot disagree with the date written inside it.


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 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.