# Budget Flow

> A personal and household budget planner drawn as a Sankey diagram. Income lines flow into spending categories and on into needs, wants, savings, debt payments and what is left over - or a shortfall. Every income line and category has a what-if slider; the browser re-flows the diagram and recomputes the month-end, the ratios, the emergency-fund months, a 12-month projection and a debt-free date as you drag, free and before sign-in. A metered planner then proposes a ranked set of moves, drawn as dashed ribbons on the same diagram, and the page checks every figure it cites against its own.

Live at https://budget-flow.skillsafe.ai/ · API tutorial at https://budget-flow.skillsafe.ai/api.html · Tokens at https://budget-flow.skillsafe.ai/tokens.html

Derived from the agent skill @onewave-ai/budget-optimizer (onewave-ai/claude-skills: https://skillsafe.ai/skill/@onewave-ai/budget-optimizer/) - spending patterns, the 50/30/20 rule, a subscription audit, debt payoff strategies and an emergency-fund roadmap. Not affiliated with its author. Not financial advice.

## What it does

One work object: one monthly budget - income lines (each may be marked irregular), spending categories with their lines, each category grouped as needs, wants, savings or debt payments, a list of debts (balance and APR), and the savings held now.

The free lane (no account, no model, all in the browser):

- Templates: a family of four (USD), a freelancer with irregular months (GBP), a student term (EUR), or a blank ledger.
- Bank CSV import: the header is detected (date; description, memo, payee or merchant; amount, or debit and credit). Negative amounts are spending; if an export has no negatives, every row is spending except rows an income rule claims. Editable keyword rules bucket each row (a term matches at the start of a word, so "tfl" does not match inside "netflix"; the first matching rule wins). Totals become monthly averages over the distinct months seen; each bucket's six largest merchants become ledger lines and the rest one "Other" line, so lines always sum to the category.
- The Sankey: column one is the income lines (plus a Shortfall source when spending beats income), column two the categories (plus Left over), column three the groups. Income-to-category flows use the north-west corner rule over whole cents, so every ribbon out of a node sums exactly to the node and ribbons never cross at a node. One scale for every column. On phones the diagram runs top to bottom.
- Sliders: -100% to +50% on every income line and category, applied to what was typed and rounded to the cent; a category's lines move with it.
- Figures: month-end = income - spending. Ratios are each group's share of income. Emergency-fund months = savings now / essentials, where essentials are needs plus debt payments. In 12 months: savings now + 12 x (savings group + month-end). Debt-free date: a month-by-month amortisation - interest at APR/12 on each balance, rounded to the cent, then the whole Debt payments group pays the highest-rate balance first (avalanche); "never" when the payment does not cover the first month's interest.
- Exports: the Sankey as SVG, the categorised budget as CSV, the scenario as JSON and a Markdown report.

Two metered lanes over one system prompt (gpt-terra), routed by the `task` field:

- `plan` - the first reading. Up to five ranked moves, each naming an existing category with its current amount (`from`) and a proposed monthly amount (`to`), why, where the money goes and what it trades off; up to five risks (shortfall, no buffer, irregular income, a ratio out of range, debt, concentration) each citing one browser figure by key; one question to settle first; a read of the four ratios.
- `replan` - after the person applied some moves (the page sets each slider to the exact ratio that lands the category on `to`): what the moves achieved, quoting the before and after figures, any further moves, and the risks restated against the new figures.

The planner never does the arithmetic. The page reconciles every reply: a move on a category that does not exist cannot be applied; a `from` that differs from the browser's amount is flagged and the browser's figure is used; a `to` outside the slider range is clamped and said so; a cut of more than 30% to a needs category without a structural change is flagged; every risk's figure is checked against the browser's value for its key; a missing shortfall, buffer or irregular-income risk is flagged; the ratio read is checked against the browser's ratios.

The result is drawn on the diagram: each ticked move is a dashed ghost of its category at the new size, with a dashed ribbon at the new width and a numbered callout, and the summary strip shows month-end, buffer months, the 12-month figure and the debt-free date now and after the moves.

History is saved to the person's SkillSafe account (a declared collection, one record per budget, updated on each re-plan) and mirrored in the browser.

## Run input (both lanes)

`task` ("plan" or "replan"), and as JSON-encoded strings: `budget` (title, currency, start_month, context, incomes, categories with their three largest lines, group_totals, debts), `figures` (the browser's numbers), `clipped` (how many lines were left out). A re-plan adds `applied_moves`, `figures_before_moves` and `previous`. See https://budget-flow.skillsafe.ai/api.html for worked examples.