Skip to content
Back to search

Owl

Retirement planner with great wisdom

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mdlacasse/Owl with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mdlacasse/Owl'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mdlacasse--owl/badge.svg)](/listings/mdlacasse--owl)

HTML

<a href="/listings/mdlacasse--owl"><img src="/api/listings/mdlacasse--owl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 157 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--
  2. Copyright (C) 2024-2026 Martin-D. Lacasse and The Owl Authors
  3. SPDX-License-Identifier: CC-BY-NC-SA-4.0
  4. This documentation is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0; see LICENSE-docs in the repository root.
  5. -->
  6. # Owl - Optimal wealth lab
  7. [![CI](https://github.com/mdlacasse/owl/actions/workflows/github-actions-runtests.yml/badge.svg?branch=main)](https://github.com/mdlacasse/owl/actions/workflows/github-actions-runtests.yml?query=branch%3Amain)
  8. [![Version](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmdlacasse%2Fowl%2Fmain%2Fsrc%2Fowlplanner%2Fversion.py&search=__version__%20%3D%20%22(%5B%5E%22%5D%2B)%22&replace=%241&label=latest)](https://github.com/mdlacasse/owl/blob/main/src/owlplanner/version.py)
  9. [![PyPI](https://img.shields.io/pypi/v/owlplanner)](https://pypi.org/project/owlplanner/)
  10. [![Python](https://img.shields.io/pypi/pyversions/owlplanner)](https://pypi.org/project/owlplanner/)
  11. [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
  12. [![Docker](https://img.shields.io/docker/v/owlplanner/owldocker?label=docker&cacheSeconds=86400)](https://hub.docker.com/r/owlplanner/owldocker)
  13. [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://owlplanner.streamlit.app)
  14. ## Open-source retirement planning optimizer powered by Actual Intelligence — connect it to your AI assistant
  15. *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*
  16. ---
  17. <img align="right" src="https://raw.githubusercontent.com/mdlacasse/Owl/main/assets/owl.png" width="350">
  18. ### TL;DR
  19. Owl is an open-source **retirement planning tool** that helps US retirees answer the hardest
  20. questions in retirement income planning: when to claim Social Security, how much to convert
  21. to Roth each year, which accounts to withdraw from first, and how to minimize lifetime taxes.
  22. It uses mixed-integer linear programming to *optimize* withdrawal strategies rather than
  23. merely simulate them, finding the mathematically best sequence of decisions across all
  24. accounts simultaneously.
  25. Users can stress-test their plan with historical back-testing, Monte Carlo simulation
  26. with sequence-of-returns risk, or fixed rates derived from historical averages.
  27. Owl covers the full US tax landscape: federal income tax, state income taxes for all
  28. 50 states and DC, long-term capital gains, NIIT, Medicare IRMAA surcharges, ACA marketplace
  29. premiums, RMDs, and Roth conversion rules — all embedded directly in the optimizer so that
  30. tax-efficient retirement income planning is built into every result, not applied as an afterthought.
  31. <p align="center">
  32. <img src="https://raw.githubusercontent.com/mdlacasse/Owl/main/info/images/chris+pat_savings.png" width="700" alt="Owl Savings Balance plot: tax-deferred accounts drawn down while Roth balances grow through optimized conversions">
  33. <br>
  34. <em>Optimized account balances over time (today's dollars): Owl draws down tax-deferred
  35. accounts while growing tax-free Roth balances through early-retirement conversions.</em>
  36. </p>
  37. -------------------------------------------------------------------------------------
  38. ## Key capabilities
  39. - **Tax optimization** — federal + state income tax (all 50 states + DC), LTCG brackets, NIIT, Medicare IRMAA, and ACA premiums all embedded in the optimizer
  40. - **Account types** — taxable, tax-deferred (401k/IRA), Roth, and HSA accounts with full contribution and withdrawal rules
  41. - **Roth conversions** — amounts and timing co-optimized with spending and bequest goals
  42. - **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
  43. - **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
  44. - **Social Security** — own, spousal, and survivor benefits; optional optimization of claiming age (monthly resolution, 62–70)
  45. - **Pension & SPIA** — pension income with survivor fractions; IRA-funded SPIA with optional CPI indexing and joint-and-survivor benefit
  46. - **Two objectives** — maximize net spending subject to a bequest floor, or maximize after-tax bequest subject to a spending floor
  47. - **Spending profile** — flat or smile-curve shape with survivorship factor; optional time-preference discounting to reduce end-of-life back-loading
  48. - **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
  49. - **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
  50. - **Rate models** — 17 models including historical replay, bootstrap, VAR, GARCH-DCC, HMM, GMM, and Gaussian copula
  51. - **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:
  52. > *"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?"*
  53. 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.
  54. 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.
  55. ## How to run Owl
  56. There are four ways to run Owl (from easiest to more complex):
  57. 1) **Streamlit Hub:** Run Owl remotely as hosted on the Streamlit Community Cloud at
  58. [owlplanner.streamlit.app](https://owlplanner.streamlit.app).
  59. 1) **Docker Container:** Run Owl locally on your computer using a Docker image.
  60. Follow these <a href="https://github.com/mdlacasse/Owl/blob/main/docker/README.md" target="_blank" rel="noopener noreferrer">instructions</a> for using this option.
  61. 1) **Self-hosting:** Run Owl locally on your computer using Python code and libraries.
  62. Follow these <a href="https://github.com/mdlacasse/Owl/blob/main/INSTALL.md" target="_blank" rel="noopener noreferrer">instructions</a> to install from the source code and self-host on your own computer.
  63. 1) **AI assistant (MCP):** Connect Owl as a tool to an AI assistant — Claude Desktop,
  64. Claude Code, Gemini CLI, Cursor, Zed, VS Code (Copilot or Cline), or any
  65. [MCP-compatible client](https://modelcontextprotocol.io).
  66. The AI can discover cases, run optimizations, compute probability-of-success frontiers,
  67. and compare scenarios through natural conversation — no TOML files required.
  68. Requires a local installation; see <a href="https://github.com/mdlacasse/Owl/blob/main/info/mcp.md" target="_blank" rel="noopener noreferrer">info/mcp.md</a> for setup.
  69. The *Connect your AI* page (under Tools in the web UI) generates the copy-paste
  70. configuration for Claude Desktop, Claude Code, Cursor, Gemini CLI, VS Code, and Zed.
  71. ## Documentation
  72. | Document | Description |
  73. |---------|-------------|
  74. | 📥 <a href="https://github.com/mdlacasse/Owl/blob/main/INSTALL.md" target="_blank" rel="noopener noreferrer">Installation Guide</a> | Installation, Python environment setup, and developer build steps |
  75. | 📋 <a href="https://github.com/mdlacasse/Owl/blob/main/CHANGELOG.md" target="_blank" rel="noopener noreferrer">Changelog</a> | Version history and changelog |
  76. | 🤝 <a href="https://github.com/mdlacasse/Owl/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">Contributing</a> | Guidelines for contributing code, issues, and pull requests |
  77. | 📊 <a href="https://github.com/mdlacasse/Owl/blob/main/info/modeling-capabilities.md" target="_blank" rel="noopener noreferrer">Modeling Capabilities</a> | Summary of modeled components, assumptions, and limitations |
  78. | 📖 <a href="https://github.com/mdlacasse/Owl/blob/main/info/USER_GUIDE.md" target="_blank" rel="noopener noreferrer">User Guide</a> | Python API usage with examples for Jupyter notebooks and scripts |
  79. | ⚙️ <a href="https://github.com/mdlacasse/Owl/blob/main/info/PARAMETERS.md" target="_blank" rel="noopener noreferrer">Parameter Reference</a> | Complete reference for TOML case file parameters |
  80. | 📈 <a href="https://github.com/mdlacasse/Owl/blob/main/info/RATE_MODELS.md" target="_blank" rel="noopener noreferrer">Rate Models</a> | Available rate models (historical, stochastic, bootstrap, etc.) |
  81. | 🤖 <a href="https://github.com/mdlacasse/Owl/blob/main/info/mcp.md" target="_blank" rel="noopener noreferrer">MCP Server</a> | MCP server setup for AI-native access via Claude, Gemini, Cursor, Zed, VS Code, and other clients |
  82. | 🖥️ <a href="https://owlplanner.streamlit.app/Documentation" target="_blank" rel="noopener noreferrer">Web App Guide</a> | Guide to the Streamlit web app user interface |
  83. | 📐 <a href="https://github.com/mdlacasse/Owl/blob/main/papers/owl.pdf" target="_blank" rel="noopener noreferrer">Mathematical Foundations</a> | The LP formulation paper (owl.pdf) |
  84. ## Credits and Acknowledgements
  85. See <a href="https://github.com/mdlacasse/Owl/blob/main/CREDITS.md" target="_blank" rel="noopener noreferrer">CREDITS.md</a>.
  86. ## Bugs and Feature Requests
  87. Please submit bugs and feature requests through
  88. [GitHub](https://github.com/mdlacasse/owl/issues) if you have a GitHub account
  89. or directly by [email](mailto:martin.d.lacasse@gmail.com).
  90. Or just drop me a line to report your experience with the tool.
  91. ## Privacy
  92. This app does not store or forward any information. All data entered is lost
  93. after a session is closed. However, you can choose to download selected parts of your
  94. own data to your computer before closing the session. These data will be stored strictly on
  95. your computer and can be used to reproduce a case at a later time.
  96. The optional self-hosted **Assistant** page is disabled by default and never available
  97. on the hosted app; when you explicitly enable it, your conversation — including case
  98. data you ask about — is sent to the AI provider you configure. The optimizer itself
  99. always runs locally.
  100. ## Licensing
  101. Copyright &copy; 2024-2026 Martin-D. Lacasse and The Owl Authors.
  102. This project is distributed under three separate licenses depending on the type of file:
  103. - **Source code** (`.py`, `.sh`) is licensed under the
  104. **GNU General Public License v3** (see [LICENSE](https://github.com/mdlacasse/Owl/blob/main/LICENSE)).
  105. - **Documentation** (`.md`, `.qmd`, `.ipynb`, `.tex`) is licensed under the
  106. **Creative Commons Attribution-NonCommercial-ShareAlike 4.0** license, CC-BY-NC-SA-4.0
  107. (see [LICENSE-docs](https://github.com/mdlacasse/Owl/blob/main/LICENSE-docs)).
  108. - **Name, logo, and image assets** — the **Owl - Optimal wealth lab** name and the
  109. logo/icon image files in the `assets/` directory — are **all rights reserved**,
  110. Copyright &copy; 2024-2026 Martin-D. Lacasse. They are **not** covered by the GPLv3 and
  111. may not be reproduced or modified without permission (see [assets/LICENSE](https://github.com/mdlacasse/Owl/blob/main/assets/LICENSE)).
  112. ## Disclaimers
  113. **Owl** is for **educational and research purposes** only. Nothing here constitutes **financial, tax, or
  114. investment advice**—consult a qualified professional for decisions specific to your situation.
  115. Code output has been verified with analytical solutions when applicable, and comparative approaches otherwise.
  116. Nevertheless, accuracy of results is not guaranteed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.