Flint is a retirement simulator that uses an approach inspired by the excellent ficalc.app.
You describe your current financial picture, including assets, spending, and income, and Flint replays every historical S&P 500 period of the same length as your retirement to show how you would have fared.
The result is a distribution of outcomes grounded in real market history rather than assumptions about future returns.
Most retirement calculators ask: "How much can I withdraw each year?" They answer with a single value or withdrawal rate, often the famous "4% rule", applied uniformly to a simplified two-bucket portfolio of stocks and bonds.
Flint takes the opposite approach. Instead of starting from a withdrawal rate, you describe your actual spending plan, broken down into categories like housing, food, healthcare, and education. Each category has its own inflation rate, because the things that cost more as you age, especially healthcare, inflate faster, while other expenses shrink or disappear entirely (a paid-off mortgage, children leaving home, no more commuting costs).
You also describe your assets with the same granularity: 401K and IRA accounts that are taxed as ordinary income when you withdraw, Roth accounts that are tax-free, a taxable brokerage with capital gains exposure, an HSA earmarked for medical costs, a 529 for education. Flint tracks the tax treatment of each account type, models Required Minimum Distributions when they kick in, and applies federal and state income tax to each year's withdrawals.
The result is a simulation that reflects your retirement rather than an idealized average. A 50-year-old with a paid-off house, grown children, and Social Security starting in fifteen years has a fundamentally different spending profile from a 60-year-old still supporting a family and carrying a mortgage. Flint lets you model both, and everything in between, including one-time events like selling a house, an inheritance, or a child starting college.
Python 3.11 or later is required. No third-party packages are needed.
python flint.py [options]
| Option | Description | Default |
|---|---|---|
--scenario NAME |
Load scenarios/<name>.toml |
First non-default scenario alphabetically; falls back to default |
--port PORT |
Port for the local web server | 8080 |
On startup Flint runs an initial simulation and launches a local web server. Open
http://localhost:8080 (or the port you chose) in a browser to see the results. Press Ctrl-C
to stop the server.
Scenario files live in scenarios/. Any .toml file placed there is automatically discovered.
The web UI has a scenario dropdown that lets you switch between them without restarting.
The results page shows:
- Starting Portfolio: Total assets at the beginning of retirement. Click this to see how assets are projected to grow between the current year and the start of retirement.
- Simulations Run: One simulation per historical S&P 500 period of matching length.
- Median Outcome: The median final portfolio value across all simulations.
- Success Rate: The fraction of simulations that ended with positive assets.
- Outcome Distribution: A histogram of final portfolio values. Click a bar to see the individual simulations in that range. Click a simulation card to see a year-by-year breakdown of asset balances.
The Retire at age / until controls at the top let you adjust the retirement window and re-simulate instantly. Use the scenario dropdown on the right to switch scenarios.
Scenarios are simple TOML text files in the scenarios/ directory. The filename
(without .toml) becomes the scenario name used in the --scenario flag and the UI dropdown.
country = "us" # Tax jurisdiction country code (currently only "us" is supported)
state = "ca" # Two-letter state code for state income tax (optional)
year = 2025 # Base year: the year that all amounts below reflect
age = 45 # Your age in the base year
retirement_age = 65 # Default retirement age shown in the UI (optional, default 65)
retirement_end = 90 # Default end age shown in the UI (optional, default 90)year and age are the anchor for everything else. All asset balances, budget amounts, and income
figures should reflect your situation as of that year. Flint projects forward from there.
The [assets] section lists your current balances by account type.
[assets]
"Cash" = 100000
"401K" = 500000
"Roth 401K" = 150000
"IRA" = 80000
"Roth IRA" = 60000
"Stocks" = 200000
"Bonds" = 50000
"529 Plan" = 80000
"HSA" = 20000
"Real Estate" = 800000All fields are optional. Omit any account type you don't have.
| Account | Default growth | Tracks S&P 500 | Tax treatment |
|---|---|---|---|
| Cash | 3% | No | No tax on withdrawal |
| 401K | 7% | Yes | Ordinary income tax |
| Roth 401K | 7% | Yes | Tax-free (Roth) |
| IRA | 8% | Yes | Ordinary income tax |
| Roth IRA | 8% | Yes | Tax-free (Roth) |
| Stocks | 8% | Yes | Capital gains tax |
| Bonds | 4% | No | No tax on withdrawal |
| 529 Plan | 7% | Yes | Reserved for education |
| HSA | 6% | Yes | Reserved for healthcare |
| Real Estate | 3% | No | Reserved (not withdrawn) |
Tracks S&P 500 means the account's annual growth rate during retirement simulations is taken directly from historical S&P 500 data. Fixed-rate accounts (Cash, Bonds, Real Estate) use their default rate regardless of market conditions.
Reserved accounts are excluded from the general withdrawal pool. The 529 is used only to cover education expenses; the HSA covers healthcare shortfalls; Real Estate is held as an asset but not liquidated. You can release reserved assets using rules (for example, selling a house).
RMD accounts: 401K and IRA accounts are subject to Required Minimum Distributions starting at age 73, computed from IRS life expectancy tables.
Early withdrawal restriction: 401K, Roth 401K, IRA, and Roth IRA accounts cannot be withdrawn before age 59 without penalty. Flint assumes that you never want to incur this penalty, and won't withdraw from these accounts until you reach the minimum penalty-free age.
Override any account's default annual growth rate with [assets.growth]. Values are percentages.
[assets.growth]
"Real Estate" = 0 # Flat (0% growth)
"Bonds" = 4.5 # 4.5% instead of the default 4%Capital Gains Percentage sets what fraction of the current Stocks balance is gains above cost
basis, i.e. what percentage would be subject to capital gains tax if you sold everything today.
The default is 50 (50%).
[assets]
"Stocks" = 500000
"Capital Gains Percentage" = 60 # 60% of Stocks is gains; 40% is cost basisDuring the simulation, future Stocks contributions (from the Stocks budget category) are counted
as new cost basis, which reduces the effective capital gains fraction over time. Market growth
does not change the cost basis; all growth accrues as gains.
The [budget] section lists annual spending by category. Amounts are in the base year's dollars.
All fields are optional.
[budget]
"Housing" = 36000 # Mortgage/rent, property tax, insurance, maintenance
"Utilities" = 6000 # Electricity, gas, water, internet, phone
"Transportation" = 8000 # Car payments, insurance, fuel, maintenance
"Food" = 18000 # Groceries and restaurants
"Health" = 6000 # Health insurance, medical, prescriptions
"School" = 0 # Tuition, room and board, supplies
"Children" = 0 # Childcare, activities, supplies
"Debt" = 0 # Credit card or other debt payments
"Business" = 0 # Self-employment or business expenses
"Other" = 12000 # Everything elseEach category inflates independently each year using its own default rate.
| Category | Default inflation |
|---|---|
| Housing | 3% |
| Utilities | 4% |
| Transportation | 4% |
| Food | 3% |
| Health | 5% |
| School | 4% |
| Children | 4% |
| Debt | 0% (fixed) |
| Business | 0% (fixed) |
| Other | 3% |
Healthcare inflates at 5% by default (significantly faster than overall inflation) to reflect the real historical trend of medical costs outpacing overall inflation.
These rates are defaults. When historical CPI data is available, Flint uses actual historical
averages per category instead (computed from the same dataset that drives the S&P 500 simulation),
and during each Monte Carlo retirement replay, expenses grow at the inflation rate that actually
prevailed during that historical period. A scenario where the market performed as it did in the
1970s also inflates your expenses at 1970s rates. The [budget.growth] overrides described below
always take precedence over both defaults and historical averages.
Override any category's rate with [budget.growth]:
[budget.growth]
"Health" = 6 # 6% instead of the default 5%
"Housing" = 0 # Fixed (mortgage payment doesn't change)Budget categories that correspond to investment accounts are treated as annual contributions rather than expenses. They reduce cash flow in the current year and add to the specified account.
| Budget category | Contributes to | Pre-tax? |
|---|---|---|
| Pre-Tax 401K | 401K | Yes (reduces taxable income) |
| After-Tax 401K | 401K | No |
| Roth 401K | Roth 401K | No |
| IRA | IRA | Yes (reduces taxable income) |
| Roth IRA | Roth IRA | No |
| 529 Plan | 529 Plan | No |
| HSA | HSA | No |
| Stocks | Stocks | No |
| Bonds | Bonds | No |
Contributions stop automatically when retirement begins.
Set Employer 401K Match to either a percentage of your pre-tax 401K contribution or a fixed
annual dollar amount:
# 50% match on employee contributions (e.g. contribute $20K, get $10K matched)
"Employer 401K Match" = "50%"
# Fixed annual match regardless of contribution amount
"Employer 401K Match" = 5000When the School budget covers college costs that qualify for 529 withdrawals, set 529 Eligible
to indicate what fraction of the School budget should be drawn from the 529 plan:
"529 Eligible" = "100%" # All school expenses paid from 529
"529 Eligible" = "75%" # 75% from 529, remainder from general assetsThis prevents the 529 from sitting idle when school expenses exist. It is typically set via a rule in the year your child starts college and cleared when they graduate.
The [income] section specifies annual income.
[income]
"Job Income" = 120000 # Primary employment income; stops at retirement
"Other Income" = 10000 # Rental income, part-time work, etc.; continues through retirementJob Income grows at 3% per year by default.
During retirement, Other Income grows at the actual historical inflation rate matched to each scenario's years; the same rate used to inflate your budget. In years where inflation is negative, Other Income does not decrease, reflecting the real-world behavior of Social Security COLA, pension adjustments, and similar payments that are protected against deflation.
Before retirement, Other Income also grows at 3% per year by default.
To use a fixed annual growth rate for Other Income instead of tracking inflation, add an
[income.growth] section:
[income.growth]
"Other Income" = 2 # 2% annual growth regardless of inflationSocial Security, pension income, or other retirement income streams that start at a specific age are best modeled as Other Income rules that set the amount in the year they begin:
[income]
"Job Income" = 150000
"Other Income" = 0
rules = [
{year = 2042, "Other Income" = "=36000"}, # Social Security begins
]Rules let you model life events that change your assets, budget, or income at specific years.
Each rule is a table entry in the rules list with a year key and one or more category keys.
rules = [
{year = 2035, "Housing" = "=24000", "Food" = "-15%"},
]Multiple events in the same year go in the same rule entry. Events in different years are separate entries.
| Format | Meaning | Example |
|---|---|---|
"=N" |
Set to an absolute value | "=500000" |
"+N" |
Add a dollar amount | "+200000" |
"-N" |
Subtract a dollar amount | "-50000" |
"+N%" |
Increase by a percentage | "+10%" |
"-N%" |
Decrease by a percentage | "-20%" |
"+N%@Category" |
Add N% of another category's current value | "+45%@Real Estate" |
"-N%@Category" |
Subtract N% of another category's current value | "-10%@Stocks" |
N |
(bare number) Set to an absolute value | 500000 |
Cross-category rules (@Category) reference another asset's value as it stands before any rules
for that year are applied. This makes it straightforward to model transactions where one asset's
proceeds flow into another: the source amount is always the pre-transaction market value, regardless
of what other rules apply to the same year. The category name must match an account type exactly
(e.g. "Real Estate", "401K").
After a rule is applied, Flint may also apply the category's default growth or inflation rate for that year. The default behavior depends on the rule type:
| Rule type | Growth applied by default? |
|---|---|
"=N" (set) |
No, the value is treated as final |
"+N" / "-N" (add/subtract) |
Yes, growth follows the adjustment |
"+N%" / "-N%" (percentage) |
Yes, growth follows the adjustment |
Override the default by appending ! (suppress growth) or + (force growth):
"Housing" = "=24000!" # Set to $24,000; no inflation applied this year
"Housing" = "=24000+" # Set to $24,000; then inflate at the Housing rate
"-50000!" # Subtract $50,000; suppress growth this yearThe year key in a rule entry is normally a calendar year integer. You can also write the year
relative to whenever retirement begins, as determined by the Retire at age control in the UI
(or the retirement_age field in the scenario file):
| Year value | What year the rule applies to |
|---|---|
"retirement" |
The first year of retirement |
"retirement+N" |
N years after retirement begins |
"retirement-N" |
N years before retirement begins |
[budget]
rules = [
# Switch to individual health insurance the year retirement begins
{year = "retirement", "Health" = "+400%"},
# Assume Medicare kicks in 5 years later and health costs drop
{year = "retirement+5", "Health" = "-60%"},
# Ramp down work-related spending the year before you stop working
{year = "retirement-1", "Transportation" = "-30%", "Other" = "-20%"},
]Retirement-relative rules work in assets, budget, and income. They can be combined with explicit calendar-year rules that happen to fall in the same year, and are always applied first.
This is useful for events that are tied to the retirement date rather than a fixed calendar year; for example, changes in spending driven by leaving the workforce, a home sale timed to coincide with retirement, or a Social Security claim a few years after retiring.
Selling outright: zero out Real Estate and add the proceeds to Cash. The +95% accounts for 5%
in sale fees; the cross-category reference ensures the correct amount is transferred even if the
Real Estate value has drifted from your original estimate:
rules = [
{year = 2038, "Real Estate" = "=0", "Cash" = "+95%@Real Estate"},
]Downsizing: reduce Real Estate by half and transfer most of the freed value to Cash:
rules = [
# Buy a home half the size; net 45% of original value after fees and purchase cost
{year = 2038, "Real Estate" = "-50%", "Cash" = "+45%@Real Estate"},
]Use School to set the annual cost, 529 Eligible to direct withdrawals from the 529, and a
later rule to zero everything out when they graduate:
[budget]
"School" = 0 # No school costs today
"529 Plan" = 12000
rules = [
{year = 2034, "School" = "=80000", "529 Eligible" = "100%"}, # College begins
{year = 2038, "School" = "=0", "529 Eligible" = "0%"}, # Graduates
]Budget items that go to zero can also reduce other categories to reflect expenses that disappear at the same time (childcare, clothing allowances, etc.):
{year = 2034, "School" = "=80000", "529 Eligible" = "100%", "Children" = "=0", "Food" = "-10%"},Set Housing to your post-payoff carrying costs (property tax, insurance, maintenance):
rules = [
{year = 2032, "Housing" = "=12000"}, # Mortgage paid off; only fixed costs remain
]Add income in the year it begins:
[income]
rules = [
{year = 2044, "Other Income" = "=36000"}, # Social Security at full retirement age
]If both partners receive Social Security at different ages, combine them into the same Other Income stream by making the second rule additive:
rules = [
{year = 2041, "Other Income" = "=24000"}, # Partner A starts
{year = 2044, "Other Income" = "+18000"}, # Partner B starts; total is $42K
]Add a lump sum to any asset category:
rules = [
{year = 2030, "Cash" = "+250000"},
][income]
rules = [
{year = 2033, "Job Income" = "=80000"}, # Downshift to part-time
{year = 2038, "Job Income" = "=0"}, # Full retirement
][budget]
rules = [
{year = 2031, "Business" = "=30000"}, # Annual business expenses begin
{year = 2040, "Business" = "=0"}, # Wind down
]Reduce contributions as retirement approaches, or increase them to model catch-up contributions:
[budget]
"Pre-Tax 401K" = 20000
rules = [
{year = 2030, "Pre-Tax 401K" = "=23000"}, # IRS limit increases (or catch-up kicks in)
]The following scenario models a 45-year-old planning to retire at 65 with a moderately complex financial picture: a mix of taxable and tax-advantaged accounts, a child heading to college in five years, and a plan to downsize their home around retirement.
country = "us"
state = "ca"
year = 2025
age = 45
retirement_age = 65
retirement_end = 90
[assets]
"Cash" = 100000
"401K" = 1000000
"Roth IRA" = 200000
"Stocks" = 700000
"Real Estate" = 1000000
rules = [
# Sell the family home and downsize; net 45% of current value after fees and replacement cost
{year = 2040, "Real Estate" = "-50%", "Cash" = "+45%@Real Estate"},
]
[assets.growth]
"Real Estate" = 0 # Conservative assumption: no real appreciation
[budget]
"Housing" = 50000
"Health" = 8000
"Food" = 40000
"Pre-Tax 401K" = 20000
rules = [
# Child leaves for a private university
{year = 2030, "School" = "=80000", "529 Eligible" = "100%", "Health" = "-20%", "Food" = "-20%"},
# Child graduates; school and associated costs drop away
{year = 2034, "School" = "=0", "529 Eligible" = "0%"},
# Downsize: mortgage is gone and lifestyle gets cheaper
{year = 2040, "Housing" = "-40%"},
]
[income]
"Job Income" = 200000
"Other Income" = 0
rules = [
{year = 2045, "Other Income" = "=30000"}, # Social Security begins; COLA applied automatically
]