claw-screener

name	claw-screener
description	Stock screener combining Williams %R oversold signals with Warren Buffett-style fundamental analysis. Supports US (S&P 500) and Thai (SET) markets. Use when screening stocks, finding oversold quality picks, running Buffett formula analysis, Carlson compounder scans, or managing a stock watchlist.
homepage	https://github.com/rsoutar/claw-screener
version	1.0.0
platforms	["macos","linux"]
compatibility	Requires Node.js >=20, npm, and network access for SEC EDGAR and Yahoo Finance data.
metadata	{"openclaw":{"emoji":"📊","requires":{"bins":["node"]}},"clawdbot":{"emoji":"📊","requires":{"env":[],"files":["~/.claw-screener-watchlist.json","sec_cache.db","price_cache.db"],"runtime":"node >=20","config_paths":"~/.claw-screener-watchlist.json"}},"hermes":{"emoji":"📊","tags":["stocks","finance","screening","buffett","technical-analysis"],"category":"finance","requires_toolsets":["terminal"],"config":[{"key":"repo_path","description":"Path to the claw-screener repository root (directory containing package.json)","default":"~/.hermes/skills/finance/claw-screener","prompt":"Where is the claw-screener repository cloned?"}]}}

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

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

Installation

This skill ships the full repository — scripts, dependencies, and caches live in the repo root. Run all commands from that directory.

OpenClaw / Clawdbot

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

Hermes Agent

Option A — clone into the Hermes skills directory (recommended):

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

Option B — point Hermes at an existing clone via ~/.hermes/config.yaml:

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

Then run npm install in that directory. Invoke with /claw-screener or ask Hermes to screen stocks.

If the repo lives elsewhere, set skills.config.claw-screener.repo_path in config.yaml (or run hermes skills config claw-screener).

Working Directory

Before running any command below, cd to the repository root:

• OpenClaw: cd {baseDir}
• Hermes: cd to skills.config.claw-screener.repo_path (default ~/.hermes/skills/finance/claw-screener)

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:

npm run screening [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
--add-top	Add top N screening picks to the watchlist	off

Examples:

npm run screening
npm run screening -- --market us --min-score 7 --top-n 5
npm run screening -- --market bk
npm run screening -- --format json
npm run screening -- --format telegram
npm run screening -- --add-top 5

2. Technical Only Scan

Fast oversold scan using Williams %R indicator only. No SEC data required. Works for both US and Thai markets.

Command:

npm run technical [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:

npm run technical
npm run technical -- --threshold -70 --top-n 50
npm run technical -- --market bk

3. Analyze Stock

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

Command:

npm run analyze -- <ticker> [options]

Options:

Flag	Description	Default
--format	Output: text, json, telegram	text

Examples:

npm run analyze -- AAPL
npm run analyze -- MSFT --format telegram
npm run analyze -- GOOGL --format json
npm run analyze -- 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:

npm run compounder [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:

npm run compounder
npm run compounder -- --tickers AAPL,MSFT,NVDA --top-n 10
npm run compounder -- --format json --max-tickers 100
npm run compounder -- --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:
  • npm run compounder -- --max-tickers 50
  • npm run compounder -- --tickers AAPL,MSFT,NVDA

5. Watchlist Management

Track stocks you're interested in, monitor live status, and get deduplicated alerts when they become oversold, overbought, or hit quality thresholds.

Command:

npm run watchlist:<command> -- [options]

Commands:

Command	Description
add <ticker>	Add one or more comma-separated stocks
remove <ticker>	Remove one or more comma-separated stocks
update <ticker>	Update notes, alert thresholds, or quality settings
list	Show all watched stocks
status	Fetch live price, Williams %R, combined score, and status
check	Check for oversold, quality, overbought, and custom-threshold alerts

Options:

Flag	Description	Default
--market us|th	Market filter: us (US) or th (Thai)	all markets
--notes '...'	Optional notes	-
--alert-threshold	Williams %R threshold for alerts	-
--min-buffett-score	Buffett score threshold for quality alerts	-
--fundamentals	Include Buffett score in status (US stocks only, slower)	off
--format text|json|telegram	Output format (list, status, check)	text
--repeat-alerts	Re-emit alerts even if unchanged since last check	off

Exit codes (check):

Code	Meaning
0	No new alerts
1	Fetch/check errors
2	New alerts fired

Examples:

npm run watchlist:add -- AAPL,MSFT,NVDA
npm run watchlist:add -- AAPL --market us --notes 'Big tech' --min-buffett-score 6
npm run watchlist:add -- PTT.BK --market th
npm run watchlist:update -- AAPL --notes 'Core holding' --alert-threshold -85
npm run watchlist:remove -- AAPL
npm run watchlist:list
npm run watchlist:list -- --market us
npm run watchlist:status
npm run watchlist:status -- --fundamentals
npm run watchlist:status -- --market us --format telegram
npm run watchlist:check
npm run watchlist:check -- --min-buffett-score 5 --format telegram
npm run screening -- --add-top 5

Scheduled monitoring example:

npm run watchlist:check -- --format telegram

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)

Runtime Requirements

• Node.js (>=20) and npm — required to run TypeScript scripts via tsx

Install Dependencies

From the repository root:

npm 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

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 watchlist:add    # Add stock(s) to watchlist
npm run watchlist:remove # Remove stock(s) from watchlist
npm run watchlist:update # Update watchlist settings
npm run watchlist:list   # List watched stocks
npm run watchlist:status # Live status for watched stocks
npm run watchlist:check  # Check watchlist alerts
npm run test             # Run unit tests

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

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

Pitfalls

• Full US universe compounding scans take ~20–30 minutes on first uncached run; use --max-tickers or --tickers for quick tests.
• Thai market (bk) uses Yahoo Finance only — no SEC fundamental data.
• Commands fail if run outside the repo root or before npm install.
• Yahoo rate limits can slow bulk scans; SQLite caches (sec_cache.db, price_cache.db) speed up repeat runs.
• SEC EDGAR requires a real contact email in the User-Agent. Set SEC_USER_AGENT env var to avoid the placeholder warning.
• DCF discount rate defaults to live 10Y Treasury yield; if the fetch is blocked, it falls back to 10%.

Configuration

All entry points accept --config <path> to load a JSON config file. Config is resolved: CLI > env vars > ~/.claw-screener/config.json > .claw-screener.json > defaults.

Key env vars: SEC_USER_AGENT, CLAW_SCREENER_WATCHLIST_FILE, SEC_DB_PATH, PRICE_DB_PATH, YAHOO_CONCURRENCY, DCF_DISCOUNT_RATE. See README for the full list.

Verification

From the repository root:

npm run typecheck
npm run lint
npm test
npm run analyze -- AAPL --format json
npm run technical -- --market us --top-n 3

A successful run prints JSON analysis or a short list of oversold tickers.