RetireTui

A local-first retirement planner for the terminal and the browser.

You describe a household in one plain TOML file - people, accounts and what they hold, contributions, income, expenses, and the milestones that start and stop them - and RetireTui projects it year by year under U.S. federal and state income tax. The same plan runs through many random or historical markets to show how surely the money lasts, and searches for a better Roth conversion ladder, Social Security claim ages or withdrawal order, and for the most you could spend. A scenario is a small file stating only what differs from a base plan, so alternatives compare side by side.

Everything runs locally; no plan leaves your machine. RetireTui is a model under the assumptions you give it, not financial advice.

Requirements

• Rust 1.97.1 or newer, to build.
• A terminal. Truecolor and the kitty keyboard protocol are used where the terminal offers them.

Install

cargo install retiretui

Or download a prebuilt archive from the releases page. Each holds the retiretui command and the retiretui-desktop window:

• Linux, x86_64 or aarch64, as a tarball:

  curl -LO https://github.com/kenianbei/retiretui/releases/latest/download/retiretui-x86_64-unknown-linux-gnu.tar.gz
  tar xzf retiretui-x86_64-unknown-linux-gnu.tar.gz
  

  The binaries are inside the retiretui-x86_64-unknown-linux-gnu/ directory it unpacks to.

• Windows, x86_64, as retiretui-x86_64-pc-windows-msvc.zip: unzip it and open retiretui-desktop.exe. The executable is not signed, so the first run shows SmartScreen's warning; choose "More info", then "Run anyway".

• macOS, Apple silicon or Intel, as retiretui-universal-apple-darwin.zip: unzip it and open RetireTui.app. The app is not notarized, so the first open is refused; open System Settings, Privacy & Security, and choose "Open Anyway" beside the refusal, then open the app again.

Usage

Interactive planner

retiretui tui examples/

Opens a plan, a scenario, or a directory to pick one from. With no plan, a short form builds a first one from the household's basics. The example plans are invented households, from a first job to a retired couple, to try it on from a clone of the repository.

Settings

The planner keeps its settings in config.toml, in ~/.config/retiretui/ or under $XDG_CONFIG_HOME where that is set. It writes the file itself when theme or motion is run from the : command palette, and all of it can be written by hand:

[tui]
motion = "reduced" # or "full", or "off"

[tui.theme]
name = "gruvbox" # a theme, or a family that follows a light or dark terminal
accent = "#fabd2f" # any role of a theme, painted over it

[tui.keys]
save = "ctrl-w" # a command as the palette lists it, and the keys it answers to

A theme of your own is a file in themes/ beside config.toml, named by its file name and chosen like any other. retiretui theme list names every theme there is, and retiretui theme dump prints one to start from:

mkdir -p ~/.config/retiretui/themes
retiretui theme dump nord > ~/.config/retiretui/themes/mine.toml

The theme picker reads that directory again each time it opens, so a theme being written is tried on without leaving the planner. The changelog says how a key is spelled and what a [tui.keys] entry may state.

In a browser

The web app at https://kenianbei.github.io/retiretui/, published with each release, is the planner for a phone or a desktop browser: the overview, the year-by-year ledger, plans compared side by side, the searches, the market runs and the tax tables, and every part of a plan edited in a form. It is tested in Chromium, Firefox and WebKit, at desktop and phone sizes. After one visit every page works offline, and the browser can install it as an app. Plans are kept in the browser's own storage and never leave it unless downloaded; clearing the browser's site data deletes them. To build and serve it yourself, with wasm-pack and Node 26 installed:

cd web
npm ci
npm run dev

The whole terminal planner also runs in a browser canvas, as an experiment, at https://kenianbei.github.io/retiretui/ratzilla/: upload and download, from the : command palette, bring a plan or a Social Security statement in and take a plan back out. To build and serve it:

crates/retiretui_web/build.sh
python3 -m http.server -d crates/retiretui_web/dist

Command line

retiretui <command> --help lists each command's options. From a clone of the repository:

retiretui project examples/starter.toml
retiretui compare examples/early-retiree.toml examples/early-retiree-no-ladder.toml
retiretui monte-carlo examples/market-mix.toml

AI agents

retiretui mcp serves the same tools over the Model Context Protocol, sandboxed to one directory of plans, with a schema reference for writing them. Register it with an MCP client:

{
  "mcpServers": {
    "retiretui": {
      "command": "retiretui",
      "args": ["mcp", "--dir", "/path/to/plans"]
    }
  }
}

Status

Pre-1.0: the plan schema and the commands still change between minor versions, and CHANGELOG.md records what did. Tax law is embedded for 2026; later years are extended by inflation, and --tax-dir adds parameter files for others. ARCHITECTURE.md describes how the system fits together.

Contributing

Changes arrive as pull requests. The checks CI runs are in ci.yml; run them locally before opening one.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.