Find breakouts. Chat with an AI trading agent. Explore company fundamentals. Track live option chains. All in one Streamlit app.
⭐ If KJStockScreener helps your trading workflow, please star the repo — it genuinely helps the project grow!
Quick Start · Features · AI Agent Setup · Screenshots · Contributing
KJStockScreener is a Python + Streamlit screener for NSE (India) stocks that goes beyond a typical breakout scanner. On top of a classic multi-threaded technical screening engine (breakouts, consolidation, RSI, moving-average crossovers, candlestick patterns), it adds an AI-native trading agent, a live NSE option chain viewer, an ML-based Nifty gap-up/gap-down predictor, and LedgerLens — a built-in fundamentals explorer that pulls a company's full financials, ratios, and filings straight from screener.in — all inside one self-contained web app.
Whether you want to run a classic rule-based scan in two clicks, or ask a chatbot in plain English to "find me swing setups in Nifty 500 with RSI between 50 and 65," KJStockScreener has a mode for it.
- Multi-process, multi-threaded scanning across NSE indices (Nifty 50 up to Nifty 500 / F&O universe)
- Breakout & consolidation detection with configurable lookback and volume-ratio filters
- Candlestick pattern recognition (Bullish/Bearish Engulfing, Inside Bar, Momentum Gainer, and more)
- MA/EMA crossover signals (50/200 Golden Cross, support/resistance zones)
- RSI-based reversal screening (9-SMA of RSI)
- Lorentzian Classification model for higher-accuracy setups
- Excel-style column filters on the results table, one-click export to Excel
- A conversational chat tab (OpenWebUI-style UI) backed by
openai-agents— talk to your screener instead of clicking through menus - Works with OpenAI, Anthropic, Groq, and any OpenAI-compatible endpoint — bring your own API key
- 5 built-in trading personas you can pick or extend, each with its own strategy and toolset:
SwingTrader— 3–10 day breakout setups from consolidation basesMomentumAnalyst— high-momentum Nifty 500 trend continuationsOptionBuyer— directional F&O option-buying opportunitiesValueScreener— long-term value & quality picks from Nifty 200KhushalJain— Nifty 50 technical-analysis persona
- Cron-style scheduled agent runs so a persona can scan the market for you automatically
- Optional Zerodha Kite MCP integration for live broker-connected market data inside chat
- Real-time NSE option chain for NIFTY, BANKNIFTY, and any F&O stock
- One-click "View" on every CE/PE strike to open that exact contract on TradingView
- A trained model predicts next-day Nifty gap-up/gap-down using Nifty, Gold, and Crude price action
- Ships as a pure NumPy
.npzweights file — no TensorFlow dependency, works out of the box on Python 3.13
- Pulls a company's complete fundamentals straight from screener.in: quarterly results, P&L, balance sheet, cash flow, ratios, shareholding pattern, peer comparison, pros/cons, and documents (annual reports, credit ratings, concall transcripts)
- Search by name or symbol, pick Consolidated/Standalone, choose which sections to pull
- Auto-generated Sales vs Net Profit chart per company
- Download any section as CSV, the full summary as JSON, or everything at once as a ZIP (JSON + CSV + Excel per section)
- Portfolio & watchlist tracking, position-size calculator
- Vector-similarity "Search Similar Stocks"
- Dockerized — one command to run, no local Python setup needed
- Cross-platform: Windows, Linux, macOS (including Apple Silicon), amd64/arm64
Just open kjstockscreener.streamlit.app — nothing to install.
docker pull callmejainsahab/kjstockscreener:latest
docker run -p 8501:8501 -p 8000:8000 callmejainsahab/kjstockscreener:latestThen open http://localhost:8501 in your browser.
Prefer the CLI mode instead of the web UI?
docker run -it --entrypoint /bin/bash callmejainsahab/kjstockscreener:latest -c "run_kjscreener.sh --cli"git clone https://github.com/85599/KJStockScreener.git
cd KJStockScreener
pip install -r requirements.txt
./run_kjscreener.sh --gui # Streamlit web UI
./run_kjscreener.sh --cli # Classic terminal UIRequires Python 3.13. See
pyproject.tomlfor the full dependency list.
- Open the AI Native tab inside the app.
- Add your LLM API key (OpenAI / Anthropic / Groq / any OpenAI-compatible provider) — it's kept in your browser's local storage or as a session-only key, your choice.
- Pick a persona, or just start chatting — e.g. "Screen Nifty 500 for swing setups near breakout with RSI 50–65."
Advanced configuration (LLM provider/model, Kite MCP, scheduled runs) lives in KJScreener.yaml at the repo root:
kite_mcp:
enabled: true
url: https://mcp.kite.trade/mcp
llm:
api_key_env: KJScreener_API_KEY
base_url: https://api.groq.com/openai/v1
model: openai/gpt-oss-120b
provider: openai-compatible
schedule: []
workflow:
default_mode: classicThe classic engine reads its parameters from KJScreener.ini, generated on first run:
[config]
period = 300d
daystolookback = 30
duration = 1d
minprice = 30
maxprice = 10000
volumeratio = 2
consolidationpercentage = 10
shuffle = y
cachestockdata = y
onlystagetwostocks = y
useema = nTweak these to match your trading style — e.g. set duration = 5d for weekly charts.
| Column | Meaning |
|---|---|
| Stock | NSE symbol. Ctrl+Click opens the TradingView chart directly. |
| Consolidating | Price range the stock has traded in over the last N days. |
| Breakout (N Days) | B: breakout level and R: next resistance level. |
| LTP | Last traded price on NSE. |
| Volume | Current candle's volume relative to its 20-period moving average. |
| MA-Signal | 50/200 MA/EMA crossover signal, e.g. BullCross-50MA. |
| RSI | 14-period RSI for momentum reads. |
| Trend | Computed trendline strength, e.g. Strong Up, Weak Down. |
| Pattern | Detected candlestick/chart pattern, e.g. Momentum Gainer, Bullish Engulfing. |
Python 3.13 · Streamlit · openai-agents · pandas / numpy / scipy · ta-lib · yfinance · BeautifulSoup4 · ChromaDB (vector search) · Plotly · Docker
Issues and pull requests are welcome!
- 🐛 Found a bug? Open an issue
- 💡 Have an idea? Start a discussion
- 🔧 Want to contribute code? Fork the repo, make your changes, and open a PR
KJStockScreener is a research and educational tool. It does not constitute investment advice.
- Do not use its output as the sole basis for your trading decisions.
- Always backtest and verify signals manually before trading.
- The author and this software are not liable for any trading losses incurred.
- LedgerLens is an unofficial tool that reads publicly available pages on screener.in — it's not affiliated with or endorsed by them. It scrapes politely (rate-limited, retried with backoff) and is meant for personal research; please respect screener.in's terms of use.
Released under the MIT License.
If this project saved you time, please consider giving it a ⭐ — it's the easiest way to support the project.
Made with ❤️ in India



