https://github.com/furic/richfolio
A zero-maintenance morning email digest for your investment portfolio. Set your target allocations once — get daily buy signals, P/E analysis, allocation gaps, and AI-summarised news via GitHub Actions. Free to run. Fork and configure in minutes.
https://github.com/furic/richfolio
buy-signals cron email-digest etf gemini-ai github-actions investing morning-brief personal-finance portfolio rebalancing resend stocks typescript wealth-management yahoo-finance
Last synced: 3 months ago
JSON representation
A zero-maintenance morning email digest for your investment portfolio. Set your target allocations once — get daily buy signals, P/E analysis, allocation gaps, and AI-summarised news via GitHub Actions. Free to run. Fork and configure in minutes.
- Host: GitHub
- URL: https://github.com/furic/richfolio
- Owner: furic
- Created: 2026-02-24T13:11:54.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T11:45:33.000Z (3 months ago)
- Last Synced: 2026-03-05T15:37:45.345Z (3 months ago)
- Topics: buy-signals, cron, email-digest, etf, gemini-ai, github-actions, investing, morning-brief, personal-finance, portfolio, rebalancing, resend, stocks, typescript, wealth-management, yahoo-finance
- Language: TypeScript
- Homepage: https://furic.github.io/richfolio/
- Size: 3.08 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Richfolio
[](https://github.com/furic/richfolio/actions/workflows/portfolio-monitor.yml)
[](https://furic.github.io/richfolio/)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://ai.google.dev/)
[](https://www.npmjs.com/package/richfolio)
[](https://opensource.org/licenses/ISC)
[](https://furic.github.io/richfolio/features)
A zero-maintenance portfolio monitoring system. Set your target allocations once, get daily briefings with allocation gaps, AI-powered buy signals, and relevant news — delivered via email and Telegram, automatically via GitHub Actions.
## Who Should Use This
Richfolio **does not pick stocks for you**. You should already have your own research and investment thesis — your own portfolio of stocks, ETFs, or crypto that you believe in.
What Richfolio does is **monitor your portfolio daily** and help you decide **when** to buy. It tracks prices, technicals, news sentiment, and allocation gaps, then uses AI to surface the best timing opportunities across your holdings.
- **You bring the portfolio** — set your target allocations once in a simple JSON config
- **Richfolio brings the signals** — buy recommendations, limit order prices, and detailed analysis
- **You make the final call** — every purchase decision is yours; the tool only suggests
**No coding skill required.** Fork the repo, spend ~10 minutes registering free API accounts (Resend, NewsAPI, Gemini), paste your keys into GitHub Settings, and you're done. Everything runs automatically via GitHub Actions at $0/month.
## Features
- **AI Buy Recommendations** — Gemini-powered analysis considering valuation, allocation gap, news sentiment, technicals, and risk (with gap-based fallback). STRONG BUY tickers get a **"More Details"** link to a dedicated analysis page with interactive chart, buy thesis, risk analysis, and full metrics
- **Value Investing Framework** — AI rates individual stocks A–D based on ROE, debt/equity, FCF, earnings growth, and analyst targets (data from Yahoo Finance, zero extra API calls)
- **Bottom-Fishing Model** — AI detects oversold/accumulation zones for all tickers using RSI, volume contraction, 200MA position, and death cross signals
- **Technical Momentum Signals** — SMA50, SMA200, RSI(14), golden/death cross, and momentum classification (bullish/bearish/neutral) for each ticker
- **Limit Order Prices** — AI-suggested limit order prices based on nearby support levels (moving averages, recent lows, round numbers)
- **Allocation Gap Analysis** — current vs target %, flagged by priority with suggested buy amounts
- **Dynamic P/E Signals** — trailing P/E compared against historical averages fetched from Yahoo Finance (no manual benchmarks needed)
- **ETF Overlap Detection** — reduces buy priority for ETFs where you already hold overlapping stocks (e.g., holding AAPL reduces VOO's priority)
- **52-Week Range Signals** — highlights tickers near their 52-week low (opportunity) or high (caution)
- **News Digest** — top headlines per ticker from NewsAPI
- **Portfolio Health** — weighted beta, estimated annual dividend income
- **Intraday Alerts** — periodic checks that alert only when buy signals strengthen vs the morning brief (configurable thresholds)
- **Weekly Rebalancing Report** — focused drift analysis with BUY/TRIM/OK actions
- **Dual Delivery** — dark-themed HTML email via Resend + condensed Telegram message
## Quick Start
1. **Fork** this repo on GitHub
2. **Add config** — go to Settings → Secrets and variables → Actions:
- **Variables** tab: `CONFIG_JSON` (portfolio config) + `RECIPIENT_EMAIL` (your email)
- **Secrets** tab: `RESEND_API_KEY` — for email delivery
- Optionally: `NEWS_API_KEY`, `GEMINI_API_KEY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
3. **Run** — trigger manually from Actions → Portfolio Monitor → Run workflow, or wait for the daily cron (8am AEST)
That's it — no local setup required. See the [full setup guide](https://furic.github.io/richfolio/getting-started) for detailed instructions on each API key.
Local development
```bash
git clone https://github.com/furic/richfolio.git
cd richfolio
npm install
cp config.example.json config.json
cp .env.example .env
```
Edit `config.json` and `.env`, then:
```bash
npm run dev # Daily brief (email + Telegram)
npm run intraday # Intraday alert check (compares vs morning)
npm run weekly # Weekly rebalancing report
npm run refresh -- SMH # Re-analyze single ticker with after-hours price
```
## Stack
| Component | Service | Cost |
|-----------|---------|------|
| Runtime | Node.js + TypeScript (tsx) | Free |
| Prices & Fundamentals | Yahoo Finance (yahoo-finance2) | Free |
| News | NewsAPI.org | Free (100 req/day) |
| AI Analysis | Google Gemini 2.5 Flash | Free (250 req/day) |
| Email | Resend.com | Free (3,000/month) |
| Telegram | Telegram Bot API | Free |
| Scheduler | GitHub Actions | Free (cron) |
## Project Structure
```
richfolio/
├── src/
│ ├── config.ts # Typed loader for config.json + .env
│ ├── index.ts # Entry point (daily/intraday/weekly mode)
│ ├── fetchPrices.ts # Yahoo Finance: price, P/E, 52w, beta, dividends, ETF holdings, fundamentals
│ ├── fetchTechnicals.ts # Yahoo Finance chart: SMA50, SMA200, RSI, momentum, volume change
│ ├── fetchNews.ts # NewsAPI: headlines per ticker
│ ├── analyze.ts # Allocation gaps, P/E signals, overlap discounts
│ ├── aiAnalysis.ts # Gemini AI: buy recs, limit prices, value ratings, bottom signals
│ ├── detailedAnalysis.ts# Gemini 2.5 Flash: detailed buy thesis + risk analysis for STRONG BUY
│ ├── analysisUrl.ts # Compress analysis data into URL hash for GitHub Pages
│ ├── email.ts # Daily HTML email template + Resend
│ ├── intradayEmail.ts # Intraday alert email template
│ ├── intradayCompare.ts # Compare current vs morning baseline
│ ├── state.ts # Morning baseline persistence
│ ├── weeklyEmail.ts # Weekly rebalancing email template
│ └── telegram.ts # Telegram bot delivery (daily/intraday/weekly)
├── docs/
│ ├── analysis/ # Static analysis page (decodes URL hash, renders with TradingView)
│ └── *.md # GitHub Pages documentation site
├── .github/workflows/
│ └── portfolio-monitor.yml # Daily + intraday + weekly cron jobs
├── config.example.json # Template portfolio config
├── .env.example # Template environment variables
├── package.json
└── tsconfig.json
```
## How It Works
```
config.json + .env
→ fetchPrices (Yahoo Finance: prices, P/E, 52w range, beta, dividends, ETF holdings, fundamentals)
→ fetchTechnicals (Yahoo Finance chart: SMA50, SMA200, RSI, momentum, volume change)
→ fetchNews (NewsAPI: top headlines per ticker)
→ analyze (allocation gaps, P/E signals, overlap discounts, portfolio metrics)
→ aiAnalyze (Gemini: buy recs + confidence + limit prices + value ratings + bottom signals)
→ email + telegram (deliver daily brief with value ratings, bottom signals, technicals)
```
Weekly mode (`--weekly`) skips news and AI, producing a focused rebalancing report.
Intraday mode (`--intraday`) re-fetches prices, technicals, and AI (skipping news), compares against the morning baseline, and alerts only for STRONG BUY-related changes: upgrades to STRONG BUY, downgrades from STRONG BUY, or confidence shifts ≥10 while at STRONG BUY.
Refresh mode (`--refresh TICKER`) re-analyzes a single ticker using the latest available price (including after-hours/pre-market from Yahoo Finance). Outputs updated analysis to terminal and sends email + Telegram with a new analysis URL. Useful when you see an alert after market close and want an updated limit order based on after-hours price movement.
## Updating Your Portfolio
Edit `config.json` and push (or update the `CONFIG_JSON` GitHub Actions variable). The next run will reflect the changes.
## References
See [docs/references.md](docs/references.md) for repos and resources referenced during design and build.
## License
ISC