A powerful retirement planning tool that implements sophisticated tax-efficient withdrawal strategies to help you keep more of your money in retirement.
Features • Demo • Installation • Usage • Tech Stack • Contributing • License
FiscalSunset is a comprehensive retirement planning calculator that helps you optimize your withdrawal strategy across multiple account types. It implements the "FiscalSunset Approach" to minimize taxes by analyzing your assets, and spending needs to generate an optimal withdrawal strategy.
The tool prioritizes tax-efficient withdrawals by:
- Leveraging 0% capital gains tax brackets
- Strategic Roth conversions based on tax bracket headroom
- Social Security benefit taxation optimization
- IRMAA (Medicare premium) cliff avoidance
- Senior deduction phase-out considerations
- Traditional IRA/401(k) - Pre-tax retirement accounts with RMD tracking
- Roth IRA - Tax-free growth and qualified withdrawals
- Taxable Brokerage - Capital gains optimization with qualified dividend tracking
- Health Savings Account (HSA) - Triple tax-advantaged healthcare savings
| Module | Description |
|---|---|
| Accumulation | Pre-retirement savings strategy and growth projections |
| Withdrawal | Tax-optimized withdrawal sequence recommendations |
| Longevity | Asset depletion analysis with projections |
| Reference | Comprehensive guide: how-to, tax strategies, 2026 tax brackets, and disclaimers |
- Two-Layer Cake Method - Optimal stacking of ordinary income and capital gains
- Social Security "Torpedo" Detection - Avoid 50-85% benefit taxation zones
- IRMAA Cliff Awareness - Medicare premium surcharge avoidance
- RMD Calculations - Automatic Required Minimum Distribution tracking (age 73+)
- Roth Conversion Optimizer - "Fill Strategy" algorithm for optimal conversions
- Integrated Google Gemini AI for personalized financial advice
- Contextual recommendations based on your specific situation
- Withdrawal rate analysis against the 4-5% rule of thumb
- Responsive design works on desktop and mobile
- Dark/Light mode toggle
- Interactive charts powered by Recharts
- Real-time calculation updates
- Local Persistence - Auto-saves your data to your device (IndexedDB)
- Privacy First - Zero-data collection; everything runs client-side
The application is live and free to use at fiscalsunset.com.
It runs entirely in the browser as a static site hosted on S3. Your financial data never leaves your device (unless you use the optional AI advisor feature), thanks to local IndexedDB persistence.
Before you begin, ensure you have the following installed:
- Node.js (v18.0.0 or higher) - Download here
- npm (v9.0.0 or higher) - Comes with Node.js
- Git - Download here
# Clone the repository
git clone https://github.com/meva/retiresmart-tax-efficient-withdrawal-strategist.git
# Navigate to the project directory
cd retiresmart-tax-efficient-withdrawal-strategist
# Install dependencies
npm installThe application uses Google Gemini for optional AI insights.
- You do not need an environment variable.
- Simply click the Settings (Gear Icon) in the top right of the application to enter your key locally.
- Your key is stored securely on your own device.
To obtain a Gemini API key:
- Visit Google AI Studio
- Sign in with your Google account
- Navigate to API Keys section
- Create a new API key
You can run the application in two modes:
1. Web Mode (Browser) Runs as a standard web application in your default browser.
npm run dev -- --mode web2. Desktop Mode (Electron) Runs as a native desktop application window.
npm run devThe application will be available at http://localhost:5173 if running in web mode.
The application will be available at http://localhost:5173 (or the next available port).
# Create an optimized production build
npm run build
# Preview the production build locally
npm run preview
### Deployment
#### Option 1: Static Web Hosting (AWS S3, GCS, Netlify, etc.)
You can generate a static distribution folder to host the web version anywhere.
```bash
# Generate the 'dist' folder
./prepare-dist.shThis will create a dist folder containing:
index.html(Entry point)assets/(Compiled JavaScript and CSS)
Upload the contents of this folder to your static file host.
fiscal-sunset/
├── src/ # Source code encapsulation
│ ├── assets/ # Centralized assets (images, logos)
│ ├── components/ # React components
│ │ ├── features/ # Feature-specific modules (Accumulation, Withdrawal, etc.)
│ │ └── layout/ # Global layout (Footer, Header)
│ ├── constants/ # Tax tables, RMD factors, thresholds
│ ├── services/ # Pure business logic & algorithm engines
│ ├── types/ # Centralized TypeScript definitions
│ ├── hooks/ # Custom React hooks (Persistence, Theme)
│ ├── utils/ # Generic helpers (Formatting, Math)
│ ├── App.tsx # Main application container
│ └── index.tsx # Application entry point
├── public/ # Static assets (images served at root)
├── electron/ # Desktop app main/preload scripts
├── index.html # Entry HTML file
├── vite.config.ts # Vite configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Scripts & dependencies
└── README.md # This file
| Technology | Purpose |
|---|---|
| React 19 | UI Framework with latest features |
| TypeScript 5.8 | Type-safe JavaScript |
| Vite 6 | Next-generation frontend tooling |
| Recharts | Interactive charting library |
| Lucide React | Beautiful icon library |
| Dexie.js | Wrapper for IndexedDB (Local Database) |
| Google Gemini AI | Optional AI-powered insights |
FiscalSunset uses a deterministic projection model with high-fidelity tax calculations. Unlike simple calculators that use effective tax rates, this engine simulates the actual IRS Form 1040 logic for every year of the projection using 2026 estimates.
The application calculates federal taxes using the standard IRS method where Ordinary Income sits at the bottom and Capital Gains/Dividends sit on top.
- Ordinary Income: Wages, Interest, Pension, Traditional IRA withdrawals, and Taxable Social Security.
- Capital Gains: Qualified Dividends and Long-Term Capital Gains from brokerage sales.
- Deductions:
- Standard Deduction (2026): ~$16,100 (Single) / $32,200 (Married).
- Age 65+ Catch-up: Adds ~$2,050 (Single) / $1,650 (Married).
- OBBBA Senior Deduction: Modeled 2025-2028 deduction of up to $12,000 for seniors, including phase-out logic ($1 reduction per $0.06 over thresholds).
To minimize lifetime tax liability, the engine withdraws assets in a specific order to fill the spending gap:
- Required Minimum Distributions (RMDs): Mandatory withdrawals from Traditional IRAs starting at age 73 (using Uniform Lifetime Table).
- Taxable Brokerage: Sold first to take advantage of 0% Capital Gains brackets.
- Roth IRA (Basis): Contributions are withdrawn tax/penalty-free.
- Traditional IRA: Withdrawn up to top of low tax brackets or to fill standard deduction.
- Roth IRA (Earnings): Accessed last to maximize tax-free growth.
- HSA: Treated as long-term care/medical reserve (last resort).
Early Retirement (FIRE) Logic: If the user is under 59.5, the engine automatically simulates:
- SEPP / 72(t) Payments: Calculates substantially equal periodic payments to access Traditional IRA funds penalty-free.
- Rule of 55: Simulates penalty-free access if applicable.
- Penalty Withdrawals: Only triggers 10% penalty if no other liquidity sources exist.
The "Strategy" tab runs an optimization loop to recommend Roth Conversions. It identifies "Headroom" in your current tax situation and recommends converting Traditional IRA funds to fill that space, up to the nearest "Cliff."
Constraints Checked:
- Tax Bracket: Fills up to the top of the 10%, 12%, or 22% bracket.
- IRMAA Cliffs: Prevents conversion from triggering higher Medicare Part B/D premiums (e.g., crossing $212k MAGI).
- Social Security "Torpedo": Detects the effective marginal rate spike (up to 49.95%) caused by the taxation of Social Security benefits and advises restricting conversions in this zone.
The Longevity tab projects assets up to age 100.
- Inflation: Spending needs are inflated annually by the
Inflation Rate(default 2.5-3.0%). - Growth: Remaining assets grow by the
Rate of Return(distinct rates for Accumulation vs. Retirement phases). - Depletion Order: For the longevity visualizer, assets are burned down sequentially: Brokerage → Traditional IRA → Roth IRA → HSA.
- Income Composition: Tracks the shifting mix of fixed income (SS, Pension) vs. Portfolio Withdrawals over time to show how the "Paycheck" is constructed.
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow TypeScript best practices
- Maintain consistent code formatting
- Add comments for complex tax calculations
- Update tests if applicable
- Update documentation as needed
Found a bug or have a feature request? Please open an issue with:
- Clear description of the problem/feature
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Screenshots if applicable
This tool is for educational purposes only.
FiscalSunset does not provide professional financial, tax, legal, or investment advice. The calculations and strategies presented are based on general tax rules and may not account for your complete financial situation.
Always consult with a qualified financial advisor, tax professional, or fiduciary before making any financial decisions. Tax laws change frequently, and individual circumstances vary significantly. USE AT YOUR OWN RISK! By using this code, you agree that the author is not liable for any financial loss, IRS penalties, or "tax torpedoes" you may encounter.
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 FiscalSunset
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Tax strategy concepts inspired by various retirement planning resources
- Built with React and Vite
- Icons by Lucide
- Charts by Recharts
- Built with Google Gemini and using AntiGravity
Made with ❤️ for a better retirement
⭐ Star this repo if you find it helpful!