cove-fi

Cove FI (@walensis/cove-fi) is a deterministic, annual retirement / financial-independence projection engine — plan files in, a year-by-year net-worth projection out, with a CLI and an MCP server so you can run it from a terminal or just talk to it from Claude Desktop, Claude Code, or Cursor. It's the Project module of the Cove suite (Balance → Plan → Project), but works entirely standalone.

Cove for YNAB manages this month's money; Cove FI projects the next forty years. Each works alone; together they talk.

Quickstart

npm install -g @walensis/cove-fi   # or: npx @walensis/cove-fi <command>
cove-fi init my-plan.toml          # scaffold a starter plan
# edit birth_year, salary amount, and retirement_year in my-plan.toml
cove-fi run my-plan.toml           # project it
cove-fi scenario my-plan.toml --retirement-year 2048   # try a scenario

Set an income's end = "retirement" (the scaffolded salary already is) and it ends automatically the year before retirement_year — including under a --retirement-year scenario override, which moves it too.

Full walkthrough, MCP setup, and command reference: packages/cove-fi/README.md.

Related MCP server: banktivity-mcp

Onboarding

Wire up the MCP server (see docs/clients/ for Claude Desktop, Claude Code, and Cursor setup), then just say "set up my retirement plan." Clients that surface MCP prompts can run the onboard guided flow directly; everywhere else, just asking works — the tools are self-describing. Either path checks for existing plans, offers YNAB seeding, walks you through the rest by hand, and finishes with a projection, a Monte Carlo run, and a save.

Plans are discovered from ~/.cove-fi/plans (override with COVE_FI_PLANS). YNAB seeding (via @walensis/ynab-client) needs COVE_FI_YNAB_TOKEN or YNAB_TOKEN set to a YNAB Personal Access Token; without one, seed_from_ynab just says so instead of erroring. Seeding is always propose-only — it never writes to your plan on its own, it returns numbers for you to confirm before they go into create_plan or update_plan.

Docs

• docs/ASSUMPTIONS.md — every default value and its citation

• docs/SEMANTICS.md — the engine's rules: the contribution waterfall, drawdown order, sentinels, and more

• docs/VALIDATION.md — how the engine is validated against published research and primary sources

• docs/clients/ — MCP setup for Claude Desktop, Claude Code, and Cursor

Validation

The engine is validated against published research and primary sources — closed-form math, cross-plan invariants, IRS-table pins, and a Monte Carlo benchmark against the Trinity-study withdrawal-rate literature. See docs/VALIDATION.md for the full methodology, citations, and an honest accounting of current limitations.

As of 0.4, accounts can carry their own nominal return or default by tax class instead of a single global rate, and opting a cash account into either taxes its growth as ordinary income each year, like real interest. Monte Carlo gives cash sleeves the same honest treatment: they follow a historical T-bill path correlated with the same sampled market years instead of riding the equity path like every other account, so cash-heavy plans get narrower percentile bands. coast_year is now a true CoastFIRE expectations test — does each account's current balance, grown at its own rate to retirement_year, already clear fi_multiple x projected retirement spending — rather than a trailing-spend heuristic.

As of 0.6, if you ever seeded a plan's income from take-home deposits (a YNAB export, a paycheck amount, anything post-tax), that plan has been taxing already-taxed money — cove-fi plans always store GROSS income, and there is no in-engine gross-up to fix it for you. Run the new income_gross_from_net calculator (propose-only; the onboarding flow now calls it automatically) to convert take-home to gross before it goes into create_plan/update_plan. Two more trust tools land alongside it: get_engine_info (a version/capabilities handshake, callable before any plan is loaded) and audit_cash_flow (a per-year income/expense/tax table built over an opt-in engine detail, flagging duplicate line names and fund_from funding shortfalls) — see docs/SEMANTICS.md's Income is always gross and Cash-flow audit sections. Nothing about the projection engine itself changed this release; every existing plan's numbers are unaffected.

As of 0.5, unknown scenario override keys are a validation error instead of a silent no-op (a typo used to run silently as an unmodified base plan — see docs/SEMANTICS.md's Scenario overrides section if you were relying on one before this release), and contribution rungs can be named so a scenario can stop, scale, or exempt them individually — --contributions-end 2043 --contributions-keep hsa,match clamps every other rung's cutoff to 2043 while leaving the HSA and employer-match rungs untouched. Accounts can also be flagged earmarked: true (a house fund, an education fund) to pull their balance out of net_worth, FI/coast/depletion, and the retirement drawdown entirely — reported separately as earmarked_net_worth — while still being spendable for their actual purpose via an expense's fund_from.

Roadmap

• 0.2 — Monte Carlo simulation (historical block-bootstrap returns)

• 0.3 — conversational onboarding (guided interview, plan discovery, propose-only YNAB seeding). Shipped.

• 0.4 — per-account/per-tax-class return overrides, gated cash-interest taxation, correlated T-bill Monte Carlo cash sleeves, true CoastFIRE coast_year. Shipped.

• 0.5 — strict scenario override validation, named contribution rungs with stop/scale/keep overrides, earmarked assets. Shipped.

• 0.6 — the net-income trap: income_gross_from_net calculator, get_engine_info handshake, opt-in engine detail, audit_cash_flow. This release.

• Next — integrations (third-party import/export), bond series/portfolio mixes

License

MIT — see LICENSE.