{"id":37229639,"url":"https://github.com/atomantic/escapemint","last_synced_at":"2026-02-27T21:14:25.852Z","repository":{"id":331666306,"uuid":"1124355597","full_name":"atomantic/EscapeMint","owner":"atomantic","description":"EscapeMint is a locally run, open-source capital allocation engine for long-term investing. It uses deterministic, rules-based logic to incrementally allocate capital in and out of positions over time, prioritizing consistency, risk discipline, and transparency over prediction or market timing.","archived":false,"fork":false,"pushed_at":"2026-01-15T06:05:48.000Z","size":8905,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T08:05:36.674Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://adameivy.com/EscapeMint/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atomantic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T21:47:43.000Z","updated_at":"2026-01-14T16:42:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/atomantic/EscapeMint","commit_stats":null,"previous_names":["atomantic/escapemint"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/atomantic/EscapeMint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomantic%2FEscapeMint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomantic%2FEscapeMint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomantic%2FEscapeMint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomantic%2FEscapeMint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomantic","download_url":"https://codeload.github.com/atomantic/EscapeMint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomantic%2FEscapeMint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28590676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T23:59:00.777Z","status":"ssl_error","status_checked_at":"2026-01-19T23:58:54.030Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-15T03:33:54.386Z","updated_at":"2026-02-06T18:15:23.292Z","avatar_url":"https://github.com/atomantic.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EscapeMint\n\nA local-first, open-source capital allocation engine for rules-based fund management.\n\n\u003e **Disclaimer**: This software is provided \"as is\" without warranty of any kind. This is **not investment advice**. I built this tool for myself and made it public so friends and family can use it too. This strategy relies on systematic DCA through market downturns — it expects you to be comfortable holding paper losses without panic selling. If you tend to sell at a loss when markets drop, this approach will likely result in poor performance. You should thoroughly review and test the code for your own needs, and the authors are not responsible for any financial losses that may result from using this software.\n\n## Overview\n\nEscapeMint is a **retirement system**, not a trading platform. The name says it all: **Escape** the rat race and **Mint** your financial freedom.\n\nIt helps you manage investments across multiple accounts (Robinhood, Coinbase, M1, etc.) using deterministic, rules-based DCA (Dollar Cost Averaging) logic. It advises buy/sell actions based on your target growth expectations, automatically adjusting DCA amounts based on asset performance.\n\n**Key principles:**\n- **Long only** - We never short; we only bet on assets going up over time\n- **Forever assets** - Only hold what survives economic catastrophe (indexes, BTC)\n- **Systematic DCA** - Remove emotion, follow the rules\n- **10+ year horizon** - This is a retirement system, not day trading\n\nRead the full [Philosophy Guide](./docs/philosophy.md) to understand why this approach works.\n\n![Dashboard](docs/screenshots/dashboard.png)\n\n## Features\n\n- **Multi-Account Support**: Track multiple sub-funds with individual configurations\n- **Tiered DCA**: Automatically buy more when assets are down, less when on-target\n- **Accumulate/Harvest Modes**: Choose to reinvest profits or harvest gains when above target\n- **Cash Interest Tracking**: Track interest earned on idle cash\n- **Transparent \u0026 Auditable**: All data stored as plain TSV files you can inspect\n- **Local-First**: Runs entirely on your machine, no cloud dependencies\n- **No External Data**: Manual equity snapshots, no brokerage API required\n\n## Supported Platforms\n\nEscapeMint has specific fund import handling for the following brokerages:\n\n| Platform | Fund Types | Features |\n|----------|-----------|----------|\n| **[Robinhood](https://join.robinhood.com/adame110/)** | Stock, Crypto | DCA, cash interest, margin tracking |\n| **[M1 Finance](https://m1.finance/OGMwOZn__m2e)** | Stock | DCA, dividend reinvestment |\n| **[Coinbase](https://advanced.coinbase.com/join/XWJ3U4F)** | Crypto, Derivatives | Spot trading, perpetual futures |\n| **[Crypto.com](https://crypto.com/app/iwmcxzu8n5)** | Crypto | Spot trading |\n\n*The referral links above support the project. You can also use EscapeMint with any brokerage - just create a custom platform name.*\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/atomantic/escapemint.git\ncd escapemint\n\n# Run setup (checks dependencies, installs packages, starts servers)\n./setup.sh\n```\n\nThat's it. The setup script will:\n- Verify Node.js 20+ is installed\n- Install all dependencies\n- Build the packages\n- Start the development servers\n\nThe app will be available at:\n- **Frontend**: http://localhost:5550\n- **API**: http://localhost:5551\n\nPress `Ctrl+C` to exit the logs view. The servers will continue running in the background with pm2.\n\nThis is also a [PortOS](https://github.com/atomantic/PortOS) compatible app.\n\n## How It Works\n\n### The Fund Model\n\nEach sub-fund tracks:\n1. **Fund Size**: Total capital allocated (cash + invested)\n2. **Cash Available**: Uninvested cash earning interest\n3. **Start Input**: Total amount invested (sum of buys - sells)\n4. **Actual Value**: Current market value of investments\n\n### The DCA Strategy\n\nEscapeMint uses a tiered DCA strategy based on performance:\n\n| Performance | DCA Amount |\n|-------------|------------|\n| On-track or gaining | `input_min_usd` (smallest amount) |\n| Below target | `input_mid_usd` (medium amount) |\n| Significant loss (\u003c `max_at_pct`) | `input_max_usd` (largest amount) |\n\nWhen your investment is performing well above target (by `min_profit_usd`):\n- **Accumulate mode (true)**: Sell the DCA amount to take profits\n- **Harvest mode (false)**: Harvest entire position back to cash\n\n### Example Workflow\n\n```\nDay 0:  Create fund \"Robinhood:TQQQ\" - $10,000 fund size\n        Config: min=$100, mid=$150, max=$200, target=30% APY\n        Cash: $10,000 | Invested: $0\n\nDay 1:  Initial BUY $100\n        Cash: $9,900 | Invested: $100 | Value: $100\n\nDay 8:  Enter snapshot - TQQQ value is $95 (-5% loss)\n        Since loss is small, use mid amount\n        Recommendation: BUY $150\n\nDay 8:  Execute BUY $149.99 (actual execution)\n        Cash: $9,750 | Invested: $250 | Value: $245\n\nDay 15: Enter snapshot - TQQQ value is $180 (-26% loss)\n        Loss exceeds -25% threshold, use max amount\n        Recommendation: BUY $200\n```\n\n## Configuration\n\nEach sub-fund is configured with:\n\n| Parameter | Description | Example |\n|-----------|-------------|---------|\n| `fund_size_usd` | Total capital in the fund | `10000` |\n| `target_apy` | Target annual growth rate | `0.30` (30%) |\n| `interval_days` | Days between actions | `7` (weekly) |\n| `input_min_usd` | DCA when on-target | `100` |\n| `input_mid_usd` | DCA when below target | `150` |\n| `input_max_usd` | DCA when significant loss | `200` |\n| `max_at_pct` | Loss threshold for max DCA | `-0.25` (-25%) |\n| `min_profit_usd` | Profit threshold to sell | `100` |\n| `cash_apy` | Interest on idle cash | `0.044` (4.4%) |\n| `margin_apr` | Margin interest rate | `0.0725` (7.25%) |\n| `accumulate` | Reinvest (true) or harvest (false) profits | `true` |\n| `start_date` | When tracking begins | `2024-01-01` |\n\n## Data Storage\n\nEach fund is stored as a single TSV file in `./data/funds/`:\n\n```\ndata/\n└── funds/\n    ├── robinhood-tqqq.tsv\n    ├── coinbase-btc.tsv\n    └── m1-vti.tsv\n```\n\nEach file contains:\n- **Line 1**: Config header (fund size, target APY, DCA amounts, etc.)\n- **Line 2**: Column headers\n- **Line 3+**: Time-series entries (date, value, action, amount, notes)\n\nExample file:\n```\n#fund_size:10000\ttarget_apy:0.30\tinterval_days:7\tinput_min:100\t...\ndate\tvalue\taction\tamount\tdividend\texpense\tfund_size\tnotes\n2024-01-01\t100\tBUY\t100\t\t\t\tInitial DCA\n2024-01-08\t205\tBUY\t100\t\t\t\tWeek 1 - TQQQ up\n```\n\n## Calculation Method\n\n**Expected Target Value** uses periodic compounding on each purchase:\n\n```\nExpectedGain = Σ(Trade_i × ((1 + APY)^(Days_i / 365) - 1))\nExpectedTarget = StartInput + ExpectedGain\n```\n\n**Actual Gain**:\n```\nGainUSD = ActualValue - StartInput\nGainPct = (ActualValue / StartInput) - 1\n```\n\n**Target Difference** (determines if above/below target):\n```\nTargetDiff = ActualValue - ExpectedTarget\n```\n\n## Security \u0026 Privacy\n\n- **Local-only**: No network calls except localhost\n- **No telemetry**: Zero analytics or tracking\n- **You own your data**: Plain-text TSV files, fully portable\n\n## Backup \u0026 Restore\n\nThe Settings page provides built-in backup and restore options:\n\n- **iCloud Backup/Restore** - Automatically sync your data to iCloud (macOS)\n- **JSON Export/Import** - Manual backup to a portable JSON file\n\nYour fund data is stored as plain TSV and JSON files in `data/funds/`, so you can also backup manually via command line if preferred.\n\n## Screenshots\n\n### Dashboard\nThe main dashboard shows all platforms with aggregate metrics, allocation charts, APY/gain tracking, fund size history, and cash vs asset breakdown.\n\n![Dashboard](docs/screenshots/dashboard.png)\n\n### Dashboard - Platform Filter\nFilter the dashboard to view metrics for a single platform with platform-specific allocation and performance charts.\n\n![Dashboard Platform Filter](docs/screenshots/dashboard-platform.png)\n\n### Platform View\nView all funds within a platform with P\u0026L summary, dividends, expenses, and detailed fund table.\n\n![Platform View](docs/screenshots/platform.png)\n\n### Fund - Accumulate Mode\nTrack funds in accumulate mode with profit extraction. Shows value \u0026 allocation over time and captured profit chart.\n\n![Fund Accumulate](docs/screenshots/fund-accumulate.png)\n\n### Fund - Harvest Mode\nTrack funds in harvest mode with dividend tracking and extracted profits visualization.\n\n![Fund Harvest](docs/screenshots/fund-harvest.png)\n\n### Fund - Cash Tracking\nTrack cash funds with interest earned, expenses, and balance over time with APY calculation.\n\n![Fund Cash](docs/screenshots/fund-cash.png)\n\n## Documentation\n\nFor detailed documentation, see the [docs/](./docs/) folder:\n\n- **[Philosophy](./docs/philosophy.md)** - Why this system exists (start here)\n- [Investment Strategy](./docs/investment-strategy.md) - DCA methodology and tiered buying\n- [Fund Management](./docs/fund-management.md) - Position and cash tracking\n- [Configuration Guide](./docs/configuration.md) - All configuration options\n- [Data Format](./docs/data-format.md) - TSV file structure reference\n- [System Architecture](./docs/architecture.md) - Package structure and data flow\n- [Derivatives](./docs/derivatives.md) - Perpetual futures data model\n\n## Running Tests\n\n```bash\n# Unit tests\nnpm run test              # Run all unit tests (engine + storage)\nnpm run test:engine       # Engine package only\nnpm run test:storage      # Storage package only\n\n# End-to-end tests (Playwright)\nnpm run test:e2e          # Run E2E tests headless\nnpm run test:e2e:headed   # Run with visible browser\nnpm run test:e2e:ui       # Run with Playwright UI\n\n# Code coverage\nnpm run test:coverage     # Generate coverage report\n\n# Code quality\nnpm run lint              # ESLint check\nnpm run typecheck         # TypeScript check\n```\n\nTest coverage reports and feature coverage status are viewable in the app's Settings page.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue first to discuss proposed changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomantic%2Fescapemint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomantic%2Fescapemint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomantic%2Fescapemint/lists"}