claw-screener

# Claw-Screener A stock screener that combines technical analysis (Williams %R oversold signals) with Warren Buffett-style fundamental analysis using SEC data. Supports US (S&P 500) and Thai (SET) markets. ## When to Use This Skill Use this skill when you need to: - Find oversold stocks with strong fundamentals - Screen for quality stocks using Buffett's 10 formulas - Screen for long-term compounders using Carlson filters (ROIC, growth, buybacks) - Analyze individual stocks for investment decisions - Get daily stock screening results in text, JSON, or Telegram format ## Tools This skill provides the following capabilities: ### 1. Combined Screening Finds stocks that are both technically oversold (Williams %R < -80) and fundamentally strong (Buffett score >= threshold). **Command:** ``` bun run src/screening.ts [options] ``` **Options:** | Flag | Description | Default | |------|-------------|---------| | `--market` | Market: `us` or `bk` | `us` | | `--min-score` | Minimum Buffett score (0-10) | `5` | | `--top-n` | Number of results to show | `10` | | `--format` | Output: `text`, `json`, `telegram` | `text` | **Examples:** ``` bun run src/screening.ts bun run src/screening.ts --market us --min-score 7 --top-n 5 bun run src/screening.ts --market bk bun run src/screening.ts --format json bun run src/screening.ts --format telegram ``` ### 2. Technical Only Scan Fast oversold scan using Williams %R indicator only. No SEC data required. Works for both US and Thai markets. **Command:** ``` bun run src/technicalOnly.ts [options] ``` **Options:** | Flag | Description | Default | |------|-------------|---------| | `--market` | Market: `us` or `bk` | `us` | | `--threshold` | Williams %R threshold | `-80` | | `--top-n` | Number of results to show | `20` | | `--format` | Output: `text`, `json`, `telegram` | `text` | **Examples:** ``` bun run src/technicalOnly.ts bun run src/technicalOnly.ts --threshold -70 --top-n 50 bun run src/technicalOnly.ts --market bk ``` ### 3. Analyze Stock Deep analysis of a single stock using Buffett's 10 formulas. **Command:** ``` bun run src/analyze.ts <ticker> [options] ``` **Options:** | Flag | Description | Default | |------|-------------|---------| | `--format` | Output: `text`, `json`, `telegram` | `text` | **Examples:** ``` bun run src/analyze.ts AAPL bun run src/analyze.ts MSFT --format telegram bun run src/analyze.ts GOOGL --format json bun run src/analyze.ts PTT.BK ``` ### 4. Compounding Machine Screens for "compounders" using Carlson-style filters: - Revenue and net income YoY trend strength - ROIC threshold (default >15%) - Share count reduction over 3 years (buyback signal) - Operating margin threshold (default >20%) - Includes current yield vs 5-year average and a simple 10-year DCF context **Command:** ``` bun run src/compoundingMachine.ts [options] ``` **Options:** | Flag | Description | Default | |------|-------------|---------| | `--market` | Market universe: `us` or `bk` | `us` | | `--tickers` | Comma-separated tickers (overrides market universe) | - | | `--max-tickers` | Limit universe size | all | | `--top-n` | Number of passing stocks to show | `25` | | `--concurrency` | Parallel fetch workers | `4` | | `--format` | Output: `text` or `json` | `text` | | `--db-path` | SQLite cache path | `sec_cache.db` | | `--ttl-days` | Cache TTL in days | `7` | | `--min-roic` | ROIC threshold (%) | `15` | | `--min-op-margin` | Operating margin threshold (%) | `20` | | `--min-buyback` | Required 3Y share reduction (%) | `2` | | `--show-rejected` | Include failed tickers with reasons in output | off | **Examples:** ``` bun run src/compoundingMachine.ts bun run src/compoundingMachine.ts --tickers AAPL,MSFT,NVDA --top-n 10 bun run src/compoundingMachine.ts --format json --max-tickers 100 bun run src/compoundingMachine.ts --tickers PLTR --show-rejected ``` **Runtime / Caching Notes:** - First uncached run on full US universe can take ~20-30+ minutes. - This is expected: each ticker requires multiple Yahoo fundamentals/quote requests and retry backoff for rate-limit resilience. - Subsequent runs are much faster due to SQLite caching (`sec_cache.db`, TTL default 7 days). - For quick checks, run smaller scans first (for example `--max-tickers 50` or specific `--tickers`). **Agent Guidance for User Messaging:** - If user runs full-universe Compounding Machine scan, explicitly warn that initial run may take ~20-30 minutes. - Suggest quick-test alternatives while waiting: - `bun run src/compoundingMachine.ts --max-tickers 50` - `bun run src/compoundingMachine.ts --tickers AAPL,MSFT,NVDA` ### 5. Watchlist Management Track stocks you're interested in and get alerts when they become oversold or overbought. **Command:** ``` bun run src/watchList.ts <command> [options] ``` **Commands:** | Command | Description | |---------|-------------| | `add <ticker>` | Add a stock to your watchlist | | `remove <ticker>` | Remove a stock from your watchlist | | `list` | Show all watched stocks | **Options:** | Flag | Description | Default | |------|-------------|---------| | `--market us\|th` | Market: `us` (US) or `th` (Thai) | `us` | | `--notes '...'` | Optional notes for the stock | - | | `--alert-threshold` | Williams %R threshold for alerts | - | **Examples:** ``` bun run src/watchList.ts add AAPL bun run src/watchList.ts add AAPL --market us --notes 'Big tech' bun run src/watchList.ts add PTT.BK --market th bun run src/watchList.ts remove AAPL bun run src/watchList.ts list bun run src/watchList.ts list --market us ``` **Storage:** Watchlist is saved to `~/.claw-screener-watchlist.json` ## Buffett's 10 Formulas The fundamental analysis evaluates stocks against Warren Buffett's criteria: | # | Formula | Target | Description | |---|---------|--------|-------------| | 1 | Cash Test | > Total Debt | Cash covers all debt | | 2 | Debt-to-Equity | < 0.5 | Low leverage | | 3 | Return on Equity | > 15% | Efficient use of capital | | 4 | Current Ratio | > 1.5 | Short-term liquidity | | 5 | Operating Margin | > 12% | Operational efficiency | | 6 | Asset Turnover | > 0.5 | Asset efficiency | | 7 | Interest Coverage | > 3x | Ability to pay interest | | 8 | Earnings Stability | Positive | Consistent profitability | | 9 | Free Cash Flow | > 0 | Cash generation | | 10 | Capital Allocation | > 15% ROE | Management effectiveness | **Scoring:** Each passing formula earns 1 point. Maximum score: 10/10. ## Technical Indicator **Williams %R (Williams Percent Range)** - Range: -100 to 0 - Oversold: < -80 (potential buy signal) - Overbought: > -20 (potential sell signal) ## Combined Score Formula Combined score = (Technical Score × 0.3) + (Fundamental Score × 0.7) - Technical Score: (Williams %R + 100) / 100 - Fundamental Score: (Buffett Score / 10) × 100 ## Data Sources - **US Stocks**: SEC EDGAR for fundamentals, Yahoo Finance for prices - **Thai Stocks**: Yahoo Finance only (no SEC data available) ## Installation ### Runtime Requirements - **Bun** (>=1.3.1) - Required runtime for executing TypeScript scripts - Node.js is NOT required as Bun provides all necessary runtime functionality ### Install Bun If you don't have Bun installed, run: ```bash # macOS/Linux curl -fsSL https://bun.sh/install | bash # Windows (PowerShell) iwr https://bun.sh/install -outfile "install.ps1"; ./install.ps1 ``` ### Install Dependencies ```bash bun install ``` ## File Persistence This skill creates and manages the following files: | File | Location | Purpose | TTL | |------|----------|---------|-----| | Watchlist | `~/.claw-screener-watchlist.json` | User's stock watchlist | Permanent | | SEC Cache | `sec_cache.db` | Cached SEC EDGAR financial data | 7 days (default) | | Price Cache | `price_cache.db` | Cached stock price data | 1 day (default) | ### Cache Management - Cache files are automatically created on first run - Use `--ttl-days` flag with compounding machine to adjust cache TTL - Cache files can be deleted to force fresh data fetch - Cache improves performance significantly on subsequent runs ### Notes - First run on full US universe can take ~20-30+ minutes (expected behavior) - Subsequent runs are much faster due to caching - For quick tests, use `--max-tickers 50` or specific `--tickers` ## Bun Scripts ```bash bun run dev # Run screening (alias for bun run src/screening.ts) bun run screening # Run combined screening bun run technical # Run technical-only scan bun run analyze # Analyze a stock (requires ticker argument) bun run compounder # Run Compounding Machine screener bun run watchlist:add # Add stock to watchlist bun run watchlist:remove # Remove stock from watchlist bun run watchlist:list # List watched stocks ``` ## Output Format Examples ### Text (Default) ``` 📊 Combined Quality Screening (US (S&P 500)) Technical: Oversold signals (Williams %R < -80) Fundamental: Warren Buffett's 10 formulas on SEC data Minimum Buffett Score: 5/10 Results: Total Scanned: 503 Oversold Found: 42 Quality Stocks: 8 (Buffett ≥5/10) Top 10 Opportunities: 1. AAPL — Combined: 85.2% | Buffett: 8/10 | WR: -82.3 2. MSFT — Combined: 79.1% | Buffett: 7/10 | WR: -85.1 ``` ### Telegram ``` 📊 Combined Quality Screening (US (S&P 500)) Scanned: 503 stocks Oversold: 42 Quality (Buffett ≥5/10): 8 🌟 Top 10 Quality Opportunities: 1. **AAPL** — Combined: 85% | Buffett: 8/10 | WR: -82.3 2. **MSFT** — Combined: 79% | Buffett: 7/10 | WR: -85.1 ```