SkillHub

claw-screener

v1.0.3

Stock screener combining Williams %R oversold signals with Warren Buffett-style fundamental analysis. Supports US (S&P 500) and Thai (SET) markets.

Sourced from ClawHub, Authored by Richard Soutar

Installation

Please help me install the skill `claw-screener` from SkillHub official store. npx skills add rsoutar/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:

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
iwr https://bun.sh/install -outfile "install.ps1"; ./install.ps1

Install Dependencies

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

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