Claw-Screener

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

Installation

npm install

Agent Skills

This repo includes a Agent Skills-compatible SKILL.md for AI agents.

OpenClaw / Clawdbot

openclaw skills install git:rsoutar/claw-screener@main
cd  && npm install

Hermes Agent

Clone the full repo (the skill needs the TypeScript sources, not just SKILL.md):

git clone https://github.com/rsoutar/claw-screener.git ~/.hermes/skills/finance/claw-screener
cd ~/.hermes/skills/finance/claw-screener && npm install

Or add an existing clone to ~/.hermes/config.yaml:

skills:
  external_dirs:
    - ~/Projects/claw-screener

Then use /claw-screener in chat, or ask Hermes to screen or analyze stocks. See SKILL.md for full command reference.

Scripts

1. Combined Screening (screening.ts)

Runs both technical and fundamental analysis to find quality oversold stocks.

npm run screening [options]

Options:

Examples:

# US market, default settings
npm run screening

# US market, stricter fundamental requirements
npm run screening -- --market us --min-score 7 --top-n 5

# Thai market (technical only, no SEC data)
npm run screening -- --market bk

# JSON output for automation
npm run screening -- --format json

# Telegram format for messaging apps
npm run screening -- --format telegram

2. Technical Only (technicalOnly.ts)

Fast oversold scan using Williams %R indicator only. No SEC data required.

npm run technical [options]

Options:

Examples:

# Default scan
npm run technical

# More oversold stocks
npm run technical -- --threshold -70 --top-n 50

# Thai market
npm run technical -- --market bk

3. Analyze Stock (analyze.ts)

Deep analysis of a single stock using Buffett’s 10 formulas.

npm run analyze --  [options]

Options:

Examples:

# Analyze a US stock
npm run analyze -- AAPL

# Analyze with Telegram format
npm run analyze -- MSFT --format telegram

# JSON for programmatic use
npm run analyze -- GOOGL --format json

# Analyze a Thai stock (uses Yahoo Finance)
npm run analyze -- PTT.BK

4. Compounding Machine (compoundingMachine.ts)

Screens for high-quality compounders using Carlson filters:

• Revenue and net income YoY growth trend
• ROIC > 15%
• Shares outstanding shrinking over 3 years (buybacks)
• Operating margin > 20%
• Includes yield-vs-5y and simple 10-year DCF valuation context

npm run compounder [options]

Options:

Examples:

# Run against S&P 500 universe
npm run compounder

# Quick sample run
npm run compounder -- --tickers AAPL,MSFT,NVDA --top-n 10

# JSON output for automation
npm run compounder -- --format json --max-tickers 100

# Show filter-fail reasons
npm run compounder -- --tickers PLTR --show-rejected

Buffett’s 10 Formulas

The fundamental analysis evaluates stocks against Warren Buffett’s criteria:

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)

The screener finds stocks where:

• Williams %R < -80 (oversold)
• Combined with Buffett score >= min-score (for US market)

Output Formats

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
...

JSON

{
  "totalScanned": 503,
  "oversoldCount": 42,
  "qualityCount": 8,
  "minBuffettScore": 5,
  "market": "us",
  "topStocks": [...]
}

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

Data Sources

• US Stocks: SEC EDGAR for fundamentals, Yahoo Finance for prices
• Thai Stocks: Yahoo Finance only (no SEC data available)

Scoring Formula

Combined score = (Technical Score × 0.3) + (Fundamental Score × 0.7)

• Technical Score: (Williams %R + 100) / 100
• Fundamental Score: (Buffett Score / 10) × 100

npm Scripts

npm run dev          # Run screening (alias for npm run screening)
npm run screening    # Run combined screening
npm run technical    # Run technical-only scan
npm run analyze      # Analyze a stock (requires ticker argument)
npm run compounder   # Run Compounding Machine screener
npm run typecheck    # Type-check without emitting
npm run lint         # Run ESLint
npm run format       # Format with Prettier
npm test             # Run unit tests
npm run build        # Compile to dist/

Pass CLI flags after --, for example: npm run screening -- --market us --min-score 7

Configuration

All entry points accept --config to load a JSON config file. Configuration is resolved in priority order:

1. CLI flags (e.g. --config /path/to/config.json)
2. Environment variables
3. ~/.claw-screener/config.json (or path in CLAW_SCREENER_CONFIG)
4. .claw-screener.json in the working directory
5. Compiled defaults

Environment Variables

Config File Example

{
  "secUserAgent": "MyApp/1.0 ([email protected])",
  "buffett": {
    "roe": 20,
    "debtToEquity": 0.3
  },
  "dcf": {
    "discountRate": 0.08,
    "useLiveRiskFreeRate": false
  },
  "screening": {
    "tech": 0.4,
    "fundamental": 0.6
  }
}

SEC User-Agent

SEC EDGAR requires a descriptive User-Agent with a contact email for fair access. Set it via:

export SEC_USER_AGENT="YourName/1.0 ([email protected])"

If the placeholder is still in use, a warning is printed on each run.

DCF Discount Rate

The Compounding Machine’s DCF uses the US 10-Year Treasury yield as the risk-free rate by default (fetched daily from home.treasury.gov, no API key required). If the fetch fails, it falls back to the configured default (10%). Set DCF_DISCOUNT_RATE or dcf.useLiveRiskFreeRate: false in the config to override.