KJ Screener

A terminal-based NSE stock screener/scanner, built by Khushal Jain, in the spirit of the open-source PKScreener project — same menu-driven flow (Scanners → Index → Criteria → Reversal Signals → Backtests), rebranded and rebuilt from scratch under a new name so it's fully yours to run, tweak, and extend.

⚠️ For learning / educational purposes only. Nothing here is investment advice. Past backtest performance never guarantees future results, and no screener or AI feature can promise a specific accuracy.

Quick start

pip install -r requirements.txt
python main.py

No internet? No problem — test everything with synthetic data first:

🖥️ App Preview & Screenshots

Here is a sneak peek of the powerful UI and features of the KJ Screener:

1. Main Dashboard & Real-Time Screener 📊

2. Advanced Technical Indicators & Charts 📈

3. Strategy Backtester & Performance Logs ⚡

4. AI-powered Market Insights & Second Opinions 🧠

5. Easy Config & AI Setup Panel ⚙️

python main.py --demo

What's inside

kjscreener/
├── main.py                  # menu navigation / entry point
├── requirements.txt
├── requirements-optional.txt # only needed for the pywhatkit WhatsApp method
├── watchlist.txt             # sample watchlist (edit with your own NSE codes)
├── kj_screener/
│   ├── banner.py              # ASCII banner ("KJ Screener")
│   ├── config.py               # scan-profile config + shared AI/WhatsApp settings
│   ├── stocklists.py            # bundled Nifty50...500, Smallcap/Midcap/F&O/IPOs
│   ├── data.py                   # yfinance live fetch (daily + intraday) + demo data
│   ├── indicators.py              # RSI (Wilder), MACD, CCI, Aroon, ADX/+DI/-DI, trend
│   ├── pivots.py                   # Camarilla / Fibonacci / Classic pivot levels
│   ├── advisory.py                  # rules-based recommendation + English narrative
│   ├── scanner.py                     # all screening criteria + 5-EMA cross signal
│   ├── ai_predictor.py                 # optional OpenAI integration (Gap/BTST/STBT)
│   ├── instruments.py                   # index/commodity dashboard instrument mapping
│   ├── backtest.py                       # historical "summary of correctness" + Growth of 10k
│   ├── alerts.py                          # WhatsApp (Twilio / pywhatkit)
│   ├── nse_api.py                          # NSE option-chain experiment (unused by default)
│   └── ui.py                                # colored tables, progress bar, prompts

Menu flow

Main Menu
 ├─ X > Scanners
 │     ├─ W > Screen stocks from my own Watchlist
 │     ├─ N > Nifty Prediction using AI (Gap-Up/Gap-Down/BTST/STBT) - needs
 │     │       an OpenAI key, see "AI Setup" below. This "N" is local to the
 │     │       Scanners menu - different from the main menu's own "N >
 │     │       Notify Mode" a few levels up.
 │     ├─ E > Live Index Scan: 5 EMA for Intraday (also menu-local, distinct
 │     │       from the main menu's "E > Edit user configuration")
 │     ├─ 0 > Screen by NSE stock code
 │     ├─ 1-11,13,14 > Nifty 50 / Next 50 / 100 / 200 / 500 / Smallcap
 │     │       50/100/250 / Midcap 50/100/150 / Newly Listed (IPOs) / F&O
 │     ├─ (blank/Enter) > All Stocks (default)
 │     └─ Choose Criterion:
 │           0  Full Screening              15 52wk low breakout
 │           1  Probable Breakouts          17 52wk high breakout
 │           2  Today's Breakouts           18 Bullish Aroon Crossover
 │           3  Consolidating stocks        19 MACD Histogram below 0
 │           4  Lowest volume in N-days     20 Bullish for next day
 │           5  RSI screening               21 Most Popular Stocks
 │           6  Reversal Signals ─┐         23 Breaking out now
 │           7  Chart Patterns    │         24 Higher Highs/Lows/Close
 │           9  Volume gainers    │         25 Lower Highs/Lows
 │          10  2%-up-3-days      │         26 RSI>30 & price>EMA(proxy for PSAR)
 │          14  NR4 Daily Today   │         27 Intraday Momentum Build-up
 │                                │         28 Extremely bullish close
 │                                │         29 Rising RSI
 │                                │         30 RSI entering bullish territory
 │                                └─ 1 Buy Signal (Bullish Reversal)
 │                                   2 Sell Signal (Bearish Reversal)
 │                                   3 Momentum Gainers
 │                                   4 Reversal at Moving Average
 │                                   5 Volume Spread Analysis (VSA)
 │                                   6 Narrow Range (NRx) Reversal
 │                                   7 Lorentzian Classifier (simplified proxy)
 │
 ├─ B > Backtests (Growth of 10k) - runs the chosen criterion over each
 │       stock's full downloaded history and reports forward 1/2/3/4/5/10/
 │       15/22/30-day % returns, an overall correctness summary, and a
 │       simulated "Growth of ₹10,000" for a 30-day hold.
 │
 ├─ O > Live Dashboard - RSI/ADX/+DI/-DI on a timeframe you pick (5-Minute,
 │       15-Minute, or Daily), Camarilla + Fibonacci + Classic pivots, a
 │       support/resistance summary, a plain-English analysis paragraph,
 │       and a transparent rules-based Buy/Sell/Hold recommendation - for
 │       NIFTY 50 / NIFTY BANK / NIFTY FIN SERVICE, Crude Oil / Natural Gas
 │       (with both USD and MCX-equivalent INR prices), or any F&O stock
 │       you type in. See the section below before trusting this with
 │       real money.
 │
 ├─ I > Index & Commodity Scanner - simpler technical bias (Bullish/
 │       Bearish/Neutral) for indices + Crude Oil/Natural Gas.
 │
 ├─ N > Notify Mode - re-runs a chosen scan on a timer (e.g. every 15 min)
 │       and sends a WhatsApp message ONLY when a genuinely NEW stock
 │       appears in the results (no repeat spam for stocks already alerted).
 │       Press Ctrl+C to stop.
 │
 ├─ A > Alerts Setup (WhatsApp) - configure Twilio or pywhatkit, test-send
 ├─ G > AI Setup (OpenAI) - add your key once; powers the Scanners' "N >
 │       Nifty Prediction using AI" feature
 │
 ├─ T > Toggle Long-term / Intraday configuration
 ├─ E > Edit user configuration (min/max price, volume multiple, etc.)
 ├─ Y > View current configuration
 └─ Q > Quit

WhatsApp Alerts

After any scan or backtest with matches, KJ Screener asks: Send this result as a WhatsApp alert? (Y/N). There's also Notify Mode (N from the main menu) for hands-free monitoring: it re-scans on a timer and WhatsApps you only when a new stock shows up.

Set it up once via A > Alerts Setup:

Your WhatsApp number is pre-filled as the default in both methods below - you'll just need to add credentials (Twilio) or confirm the number (pywhatkit) and you're set.

• Twilio (recommended) - works on a headless server, no browser needed.

  1. Free account at https://www.twilio.com/try-twilio
  2. Console → Messaging → Try it out → Send a WhatsApp message → join your sandbox by messaging the given code from your own WhatsApp
  3. Copy your Account SID + Auth Token from the Twilio Console home
  4. Paste those into KJ Screener's Alerts Setup, along with your WhatsApp number as whatsapp:+91XXXXXXXXXX
  5. Note: Twilio's free sandbox needs you to re-join every ~72 hours (send the join code again); a paid WhatsApp Business number removes that.

• pywhatkit (quick & dirty) - uses your own logged-in WhatsApp Web session in a real browser on the same machine. No API account, but needs a desktop (not headless) and momentarily opens a browser tab per message. Install with pip install -r requirements-optional.txt first.

AI Setup - free options included, for the "N" Nifty Prediction feature

Set up once via G > AI Setup from the main menu. Three providers, pick whichever suits you - the first two are genuinely free:

• Gemini (Google) - free, hosted, recommended if you don't want to install anything.

  1. Get a free key (no credit card needed) at https://aistudio.google.com/app/apikey
  2. Paste it into G > AI Setup > 1
  3. Default model gemini-2.0-flash is fast and comfortably within the free tier for casual/personal use

• Ollama - completely free, runs on your own computer, no API key at all. Best if you'd rather not create any account anywhere.

  1. Install from https://ollama.com (free)
  2. In a terminal: ollama pull llama3.2 (one-time download, a few GB)
  3. Make sure Ollama is running (it usually auto-starts, or run ollama serve)
  4. In KJ Screener: G > AI Setup > 2, accept the defaults This never leaves your machine and has no usage limits/cost, but needs a reasonably capable computer (a few GB RAM free) and the model download.

• OpenAI - only if you already have a paid/billed account. This is the one that gives insufficient_quota errors on a brand-new key with no billing set up - OpenAI's API is pay-per-use with no meaningful free tier, unlike the two options above.

Once any provider is configured, X > Scanners > N > Nifty Prediction using AI becomes usable - it feeds your already-computed RSI/ADX/DI/pivot numbers to the AI and asks for a plain-English Gap-Up/Gap-Down and BTST/STBT read for Nifty/Bank Nifty/Fin Service/any stock you type in.

What this is, honestly: the AI is reading the SAME numbers already computed by this tool (RSI, ADX/DI, trend, pivots) and writing a natural-language interpretation of them - it is not a separately-trained predictive model, has no special ability to foresee market direction, and every response should be read as commentary, not a signal. This holds regardless of which of the three providers you pick. Nothing is sent anywhere unless you configure a provider yourself; without one, N says so clearly and does nothing else.

Live Dashboard (Pivots + ADX/DI + Analysis) - please read

O from the main menu combines:

• RSI(14), ADX(14), +DI, -DI - on a timeframe YOU choose: 5-Minute, 15-Minute, or Daily. This matters more than it sounds: a daily RSI/ADX will never match what your broker shows on a 5-min intraday chart, since they're measuring completely different windows of price action. Pick 5-Minute or 15-Minute to match what you see on an intraday chart.
• Camarilla, Fibonacci, and Classic pivots - always computed from the previous COMPLETED day's High/Low/Close (the standard convention for all three), regardless of which RSI/ADX timeframe you picked above.
• A support/resistance summary pulled from all three pivot sets
• A plain-English analysis paragraph describing the bias, momentum reading, and today's pivot/breakout/reversal/support levels in one readable note - built from the exact numbers shown above it, in kj_screener/advisory.py::generate_narrative()
• A transparent Buy/Sell/Hold recommendation - every rule that contributed to the score is printed right below it, in kj_screener/advisory.py::generate_recommendation()
• Crude Oil / Natural Gas: both the global USD futures price (Yahoo Finance CL=F / NG=F) AND an MCX-equivalent INR price, computed as USD price x live USD/INR rate - clearly labeled as an approximation, not the live MCX exchange-traded price (MCX has no free public data feed).

Removed on purpose: an earlier build of this tool attempted a live NSE option-chain table (strike/CE/PE premium, PCR, Max Pain) by scraping nseindia.com. It was hitting NSE's rate-limiting/blocking too often to be worth keeping, so it's gone from the Live Dashboard. The code for it is still in kj_screener/nse_api.py if you want to experiment with it later, it's just not called from the main flow - so you get a dashboard that works every time instead of one that's sometimes broken.

On accuracy - the honest answer: the Buy/Sell/Hold call and the analysis paragraph are a transparent combination of well-known technical rules, not a prediction. No screener, including this one, can promise a specific accuracy - markets are genuinely uncertain. Use it as one input, verify live prices on your broker terminal, and manage your own risk.

Index & Commodity Scanner (I)

I from the main menu gives a live technical bias (Bullish / Bearish / Neutral) for NIFTY 50, NIFTY BANK, SENSEX, NIFTY FIN SERVICE, Crude Oil, and Natural Gas, built from the same RSI/MACD/MA/Trend/Aroon indicators as the stock scanner. For indices it also shows a reference ATM strike (spot price rounded to the standard interval) - not a live option premium (see the Live Dashboard section above for why that's not available free).

Bigger bundled stock universe

stocklists.py includes Nifty 50/Next 50/100/200/500 (approximate), Smallcap 50/100/250, Midcap 50/100/150, Newly Listed (recent IPOs), and an expanded F&O-only set. These are curated/best-effort, not a live feed - the real indices' membership drifts over time. Treat them as a solid starting point; edit stocklists.py yourself, or use your own watchlist.txt / custom-codes option, whenever you notice drift. A renamed/delisted stock just fails to fetch gracefully (see "Fixed: TATAMOTORS ticker" below) rather than crashing anything.

Fixed along the way

• RSI now uses Wilder's RMA smoothing, not a plain rolling average - matches TradingView/broker values (verified to 0.0 difference over the most recent ~50 bars of a 280-day series against a textbook-exact implementation).
• 52-week High/Low uses the actual High/Low columns, not Close, AND the historical fetch uses auto_adjust=False - Yahoo's default dividend adjustment was quietly shifting historical prices away from what your broker shows.
• RSI/ADX/+DI/-DI timeframe is selectable (5-Minute/15-Minute/Daily) - a daily-candle RSI will never match an intraday chart; this was the real reason those numbers looked "wrong" before, not a bug.
• Noisy yfinance console spam is suppressed - failed/delisted lookups used to dump raw HTTP Error 404/possibly delisted text straight to your terminal even though KJ Screener was already handling the failure correctly; now you only see its own clean messages.
• AI/WhatsApp settings are shared globally across the Long-term/ Intraday config toggle (T), stored in their own config_integrations.json - configuring G/A once means it stays configured no matter which mode you're in.
• Fixed a dispatch bug: the main menu used to print a G > AI Setup option that silently did nothing when selected (missing from the dispatch logic) - found via testing, now wired up correctly.

Fixed: TATAMOTORS ticker

Tata Motors demerged in Oct–Nov 2025: the passenger-vehicle + EV + JLR business kept the listed entity and was renamed Tata Motors Passenger Vehicles Ltd, now trading under ticker TMPV; the commercial-vehicle business was spun off separately as TMCV. The old TATAMOTORS ticker no longer trades, which is why it was failing before.

This build now uses TMPV directly in the bundled Nifty 50 list, and auto-redirects any leftover TATAMOTORS references (e.g. in your own watchlist.txt) to TMPV via SYMBOL_ALIASES in kj_screener/stocklists.py.

Honest scope notes (please read)

• Data source: live mode uses yfinance (Yahoo Finance) with the SYMBOL.NS suffix for NSE stocks. It's free and needs no API key, but Yahoo can occasionally rate-limit or time out — every fetch has retries, and any stock that still fails is simply skipped (with a clear reason shown), so one bad symbol never crashes your scan. Failed symbols are cached briefly so repeated scans don't keep retrying a dead ticker.
• "Lorentzian Classifier" in the Reversal Signals sub-menu is a simplified stand-in built from RSI/CCI/Aroon, not the original TradingView indicator - labeled as a proxy in the code and output.
• I tested this repeatedly in --demo mode (synthetic data, zero internet) across every menu path, plus scripted end-to-end runs covering every scanner, backtest, dashboard, and settings flow - all with zero crashes. I could not test the live Yahoo Finance fetch or the OpenAI API call from my own build environment (no internet access to those services from there) - please run python main.py once on your own machine and let me know if you hit anything specific, so it can be fixed fast.

Configuration

Edit via the in-app E > Edit user configuration menu, or directly in config.json (created on first run) / config_intraday.json. AI/WhatsApp settings live separately in config_integrations.json so they survive toggling between the two:

Key	Meaning
period_days	Days of history downloaded per stock
timeframe_days	Recent-days window used for breakout/consolidation
min_price / max_price	Price filter for stocks to buy
volume_ratio	Volume multiple vs 20-day average to flag a "gainer"
consolidation_pct	% range to call a stock "consolidating"
shuffle	Screen stocks in random order instead of alphabetical

Adding your own scan criterion

Add a function def crit_my_scan(snap, cfg): return True/False in kj_screener/scanner.py (see existing ones for the fields available in snap), then register it in CRITERIA_MENU with a new menu number.

Disclaimer

This report/tool is for learning & analysis purposes ONLY — no responsibility is taken for any errors, omissions, or trading gains/losses arising from its use.