| 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 50npm 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
npm run screening
npm run technical
npm run analyze
npm run compounder
npm run watchlist:add
npm run watchlist:remove
npm run watchlist:update
npm run watchlist:list
npm run watchlist:status
npm run watchlist:check
npm run test
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.
