Owl - Optimal wealth lab

Open-source retirement planning optimizer powered by Actual Intelligence — connect it to your AI assistant

Roth conversion optimizer · Social Security claiming strategy · Monte Carlo retirement simulator · Python retirement calculator · AI retirement planner · MCP retirement tool · Claude Gemini Cursor Zed VS Code

TL;DR

Owl is an open-source retirement planning tool that helps US retirees answer the hardest questions in retirement income planning: when to claim Social Security, how much to convert to Roth each year, which accounts to withdraw from first, and how to minimize lifetime taxes. It uses mixed-integer linear programming to optimize withdrawal strategies rather than merely simulate them, finding the mathematically best sequence of decisions across all accounts simultaneously.

Users can stress-test their plan with historical back-testing, Monte Carlo simulation with sequence-of-returns risk, or fixed rates derived from historical averages.

Owl covers the full US tax landscape: federal income tax, state income taxes for all 50 states and DC, long-term capital gains, NIIT, Medicare IRMAA surcharges, ACA marketplace premiums, RMDs, and Roth conversion rules — all embedded directly in the optimizer so that tax-efficient retirement income planning is built into every result, not applied as an afterthought.

Optimized account balances over time (today's dollars): Owl draws down tax-deferred accounts while growing tax-free Roth balances through early-retirement conversions.

Key capabilities

• Tax optimization — federal + state income tax (all 50 states + DC), LTCG brackets, NIIT, Medicare IRMAA, and ACA premiums all embedded in the optimizer

• Account types — taxable, tax-deferred (401k/IRA), Roth, and HSA accounts with full contribution and withdrawal rules

• Roth conversions — amounts and timing co-optimized with spending and bequest goals

• Value of optimization — compare_to_baseline solves the same plan with and without the strategy (no Roth conversions, Social Security at stated ages, taxable-first withdrawal ordering) and reports the advantage in today's dollars — a mathematical lower bound from the optimizer itself, not a simulation estimate

• Explainability — explain_results reads the LP shadow prices to report what each goal and rule costs at the margin, which tax brackets the plan deliberately fills (and why), and the order in which accounts are drawn down. Every recommendation is explained using the mathematics of the optimization itself: the AI interprets and narrates quantities computed by the solver — it does not find the answer

• Social Security — own, spousal, and survivor benefits; optional MILP co-optimization of claiming age (monthly resolution, 62–70)

• Pension & SPIA — pension income with survivor fractions; IRA-funded SPIA with optional CPI indexing and joint-and-survivor benefit

• Two objectives — maximize net spending subject to a bequest floor, or maximize after-tax bequest subject to a spending floor

• Spending profile — flat or smile-curve shape with survivorship factor; optional time-preference discounting to reduce end-of-life back-loading

• Asset allocation — user-specified glide path (linear or s-curve) across four asset classes (equities, corporate bonds, T-notes, cash); per-account, per-individual, or household-wide

• Stochastic analysis — Monte Carlo with optional longevity risk (mortality tables by sex and category: SSA, VBT, RP-2014, IAM-2012, Pub-2010); spending efficiency frontier tracing the optimal spending vs. shortfall-risk trade-off

• Rate models — 14 models including historical replay, bootstrap, VAR, GARCH-DCC, HMM, GMM, and Gaussian copula

• AI assistant — MCP server lets Claude Desktop, Claude Code, Gemini CLI, Cursor, Zed, VS Code (Copilot/Cline), and other MCP-compatible AI clients run optimizations, compute probability-of-success frontiers, quantify and explain strategies, and compare scenarios through natural conversation — eighteen tools plus a guided owl_intake interview prompt, with every assumption made for omitted inputs disclosed in the response (assumed_defaults). No TOML files required:

  "I'm 65, have $800k in my IRA and $200k taxable, $2,400/month Social Security at 67 — what can I safely spend each year with 90% historical probability of success?"

  Self-hosted installs can also enable a built-in Assistant chat page that reads the case open in the app (OWL_ASSISTANT=1); the Connect your AI page in the web UI generates the client configuration either way.

Among open-source retirement planning tools, Owl stands out for the breadth and rigor of its financial modeling. While the full API rewards those willing to invest time, the Streamlit web interface provides an accessible entry point for all users.

How to run Owl

There are four ways to run Owl (from easiest to more complex):

1. Streamlit Hub: Run Owl remotely as hosted on the Streamlit Community Cloud at owlplanner.streamlit.app.

2. Docker Container: Run Owl locally on your computer using a Docker image. Follow these instructions for using this option.

3. Self-hosting: Run Owl locally on your computer using Python code and libraries. Follow these instructions to install from the source code and self-host on your own computer.

4. AI assistant (MCP): Connect Owl as a tool to an AI assistant — Claude Desktop, Claude Code, Gemini CLI, Cursor, Zed, VS Code (Copilot or Cline), or any MCP-compatible client. The AI can discover cases, run optimizations, compute probability-of-success frontiers, and compare scenarios through natural conversation — no TOML files required. Requires a local installation; see info/mcp.md for setup. The Connect your AI page (under Tools in the web UI) generates the copy-paste configuration for Claude Desktop, Claude Code, Cursor, Gemini CLI, VS Code, and Zed.

Documentation

Credits and Acknowledgements

See CREDITS.md.

Bugs and Feature Requests

Please submit bugs and feature requests through GitHub if you have a GitHub account or directly by email. Or just drop me a line to report your experience with the tool.

Privacy

This app does not store or forward any information. All data entered is lost after a session is closed. However, you can choose to download selected parts of your own data to your computer before closing the session. These data will be stored strictly on your computer and can be used to reproduce a case at a later time.

The optional self-hosted Assistant page is disabled by default and never available on the hosted app; when you explicitly enable it, your conversation — including case data you ask about — is sent to the AI provider you configure. The optimizer itself always runs locally.

Licensing

Copyright © 2024-2026 Martin-D. Lacasse and The Owl Authors.

This project is distributed under three separate licenses depending on the type of file:

• Source code (.py, .sh) is licensed under the GNU General Public License v3 (see LICENSE).
• Documentation (.md, .qmd, .ipynb, .tex) is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license, CC-BY-NC-SA-4.0 (see LICENSE-docs).
• Name, logo, and image assets — the Owl - Optimal wealth lab name and the logo/icon image files in the assets/ directory — are all rights reserved, Copyright © 2024-2026 Martin-D. Lacasse. They are not covered by the GPLv3 and may not be reproduced or modified without permission (see assets/LICENSE).

Disclaimers

Owl is for educational and research purposes only. Nothing in this session constitutes financial, tax, or investment advice—consult a qualified professional for decisions specific to your situation.

Code output has been verified with analytical solutions when applicable, and comparative approaches otherwise. Nevertheless, accuracy of results is not guaranteed.