Skip to content

Config Reference

Jump to bottom
brookie edited this page Nov 6, 2026 · 3 revisions

Config Reference

Every section and field of a plan's config. All amounts are per month unless noted. Fields with a default can be left out. Unknown fields are reported as errors. See Plan Folder for how the files are organized.

Contents

Sections at a glance

Section Usually in What
plan config.yaml Titles and time window
household config.yaml Partners and children
other_income_monthly config.yaml Other take-home income
savings config.yaml Monthly savings transfers
investments config.yaml Brokerage / stock accounts
assumptions config.yaml Retirement and college assumptions
sources sources.yaml CSV layouts
categories categories.yaml Categories
rules rules.yaml Categorization rules
default_category, default_credit_category config.yaml Fallback categories

plan

Field Default Meaning
title Household Budget Page title.
subtitle generated Line under the title. Empty: generated from your data, e.g. "Built from Visa card and Checking (1,204 transactions, Jan 25 – Dec 25). Take-home pay: Partner A (pay stub)."
months 12 Average over N months of transactions (1–120).
last_month month of the newest transaction Last month of the averaging window, YYYY-MM. Set it to leave out a partial month at the end of an export.
today month after the window The plan's "now", YYYY-MM. Drives ages, graduation timing and projections.
currency_symbol $ Shown before amounts.

household.partners

One or more. The first is the primary partner: the retirement slider is their age, and everyone retires in the same calendar year.

Field Default Meaning
name (required) Display name. Prefer generic (Partner A).
id slug of name Stable key used by saved state; set it if you'll rename people.
age (required) Age today.
take_home_monthly 0 Net pay per month.
take_home_note '' Shown next to the planner input.
raise_pct 0 Yearly raise above inflation, until retirement.
social_security See below.
pensions [] See below.
accounts [] See below.

social_security

Field Default Meaning
at_67 0 Monthly benefit at full retirement age, today's dollars.
claim_age none 62–70. Empty = claim when retiring, not before 62.

pensions

Field Default Meaning
name Pension Label.
estimates {} Monthly benefit by retirement age, e.g. {55: 900, 60: 2800, 65: 5800}.
monthly none A flat monthly amount instead of estimates.
service_years_now none Years of service today; after the last estimate age the benefit grows in proportion to service. Without it, it stays flat.
grows_with_raises true Scale with the partner's real raises (final-pay formulas).

accounts

Field Default Meaning
name Retirement account Label.
balance 0 Balance today.
monthly 0 Added each month until retirement. 
household:
  partners:
    - name: Partner A
      age: 46
      take_home_monthly: 7200
      take_home_note: pay stub
      social_security: {at_67: 3100}
      pensions:
        - {name: Pension, estimates: {55: 800, 60: 1900, 65: 3400}, service_years_now: 9}
      accounts:
        - {name: Old 401(k), balance: 148000}
    - name: Partner B
      age: 44
      take_home_monthly: 4100
      social_security: {at_67: 2400, claim_age: 67}
      accounts:
        - {name: 403(b), balance: 61000, monthly: 600}

household.children

Field Default Meaning
name (required) Prefer generic (Child 1).
id slug of name Stable key.
age (required) Age today.
hs_graduation estimated High-school graduation YYYY-MM. If empty: June of the year they reach graduation_age (counting from plan.today).
college_529 {balance: 0, monthly: 0} Balance today and contribution per month.
school public A key in assumptions.college.schools.
note '' Extra text on the 529 card. 
  children:
    - {name: Child 1, age: 12, college_529: {balance: 38500, monthly: 500}, school: public}

other_income_monthly

A number (default 0): other take-home income per month.

savings

Field Default Meaning
name (required) Label in the planner.
id slug of name Stable key.
monthly 0 Per month.
stops_at_retirement true Stop contributions at retirement.

investments

Field Default Meaning
name Investments Label.
id slug of name Stable key.
balance 0 Balance today.
return_pct 0 Its own yearly return; 0 = off until you choose one.
monthly 0 Added each month until retirement (shown in the planner's Savings).

assumptions.retirement

Field Default Meaning
return_pct 5.5 Yearly investment return.
inflation_pct 3 Yearly inflation.
withdrawal_pct 4 Yearly withdrawal rate in retirement.
tax_pct 12 Overall income tax rate in retirement.
health_insurance_monthly 0 Health insurance after retiring.
default_age 65 Starting retirement age of the primary partner (40–80).
presets see below Named return / inflation pairs.

Default presets:

presets:
  pessimistic: {name: Pessimistic, return_pct: 4.5, inflation_pct: 3.5}
  mid: {name: Mid, return_pct: 5.5, inflation_pct: 3}
  optimistic: {name: Optimistic, return_pct: 7, inflation_pct: 2.5}

assumptions.college

Field Default Meaning
schools see below School types and yearly cost of attendance today.
presets see below Return / college-cost-growth pairs.
default_preset mid Preset each child starts on.
graduation_age 18 Used when hs_graduation is empty.
years 4 Years of college (1–8). 
schools:
  public: {name: Public in-state, cost: 30000}
  flagship: {name: Flagship in-state, cost: 45000}
  private: {name: Private, cost: 65000}
presets:
  pessimistic: {name: Pessimistic, return_pct: 4, inflation_pct: 5}
  mid: {name: Mid, return_pct: 6, inflation_pct: 4}
  optimistic: {name: Optimistic, return_pct: 8, inflation_pct: 3}

For college presets, inflation_pct means college-cost growth.

sources

Field Default Meaning
name (required) Label.
files (required) File name(s) or glob(s), relative to the plan folder. String or list.
date.column (required) Date column.
date.format detected strptime format, e.g. '%m/%d/%Y'.
description (required) Column or list of columns (joined with a space).
amount.column A single signed amount column…
amount.outflow negative …where money out is negative or positive.
amount.debit / amount.credit …or separate money-out / money-in columns.
category_column none The bank's own category column.
category_map {} Bank category → plan category, used when no rule matches.
skip_rows 0 Lines before the header row.
encoding utf-8-sig File encoding.
delimiter , Field separator.

Details and examples: Data Sources.

categories

Field Default Meaning
name (required) Unique.
kind spending spending, one_time, credit or ignore.
group Other Planner heading.
flexible false Trimmed by "Try 10% less".
kids_gone_pct 0 % change once all children are out.
retired_pct 0 % change after retiring.
default_on false One-time / credit: counted by default.
in_retirement false One-time / credit: continues after retiring.
tax false One-time: part of the tax set-aside.
offsets none Credit only: a spending or one-time category it reduces.
label none Toggle text.
note none Small print.

Details: Categories.

rules

Exactly one of:

Field Meaning
row A transaction id: "this transaction is X".
equals Field equals the text.
contains Field contains the text.
matches Field matches the regular expression.
similar_to Field is similar to the text.

Plus:

Field Default Meaning
category (required) Category to assign.
field description description, category, source, date, amount, any CSV column, or *.
threshold 0.85 For similar_to (0–1).
case_sensitive false
source none Only rows from this source.
direction none debit (money out) or credit (money in).
min_amount / max_amount none Absolute amount limits.
note none Free text.

Details: Categorizing and Rules.

default_category and default_credit_category

Field Default Meaning
default_category Other Category for money out that nothing matched.
default_credit_category Other credits Category for money in that nothing matched (a credit).

Complete example

The demo plan in the repository is a complete, working example: examples/demo/config.

🏠 Home

Getting started

Using the app

Setting up your plan

Reference

Clone this wiki locally