My-Algo-Trading-Code: Instructions file for Claude Code

CLAUDE.md — My-Algo-Trading-Code

Before doing any work in this repo, invoke the anthropic-skills:using-superpowers skill (it surfaces any other relevant skills) and the anthropic-skills:karpathy-guidelines skill, then follow them: simplicity first, surgical changes, surface tradeoffs, and verify before claiming done. This is live-money trading code — bias toward caution.

What this project is

A NIFTY index-options, multi-strategy trading system. The flow is: fetch 1-minute OHLC history from the DhanHQ API → backtest strategies on it → run a multithreaded "front test" whose approximately 27-strategy core roster and independently opt-in agents execute together — on paper by default, and live through a real broker when explicitly enabled. Running live since May 2026; daily per-strategy results are tracked in a Google Sheet.

Architecture (runtime)

One process, cooperating threads:

• CentralMarketDataFetcher (one thread) polls DhanHQ and writes into a lock-guarded SharedMarketDataStore (1-min OHLC + LTPs). Setting MARKET_DATA_SOURCE=WEBSOCKET (fails closed to REST on any other value; needs the paid Dhan Data API subscription) swaps in WebSocketMarketDataFetcher: Dhan marketfeed ticks build the bars/LTPs (pure helpers in Dependencies/tick_bar_builder.py), with REST kept for warmup and a once-per-minute true-up against official candles.
• Approximately 27 core strategy worker threads read that store and decide trades: the AtmSingleLegStrategyWorker family (Renko / EMA / Heikin-Ashi / Profit-Shooter / Goldmine / Money-Machine / CPR / CPR Algo 3 (multi-instrument: spot + ITM CE + ITM PE) / Opening-Strike + 13 ported TradingBot strategies + the Regime Adaptive router), two hedged-puts workers, one Delta-0.2 hedged-spread worker, and one long-strangle worker (time-based dual-leg BUY of OTM1 CE+PE, with momentum re-entry). Regime Adaptive (ported from the MIT-licensed workratananmol-hub/nifty-options-paper-trading-bot) is one worker that switches RULE on ADX: opening-range breakout when trending, VWAP fade when ranging, no trade when ADX is missing. Its two candidate rules live in Signal Generators/Regime Adaptive Strategy/regime_candidates.py as library code with NO worker of their own — deliberately, so the router and a candidate can never take the same signal twice. Read that folder's REGIME_PORTING_NOTES.md before enabling it live: the feed carries no volume so its VWAP is an equal-weight proxy. It is also the first user of the shared bid/ask spread gate (<PREFIX>_MAX_SPREAD_PCT, default 0 = off for every other strategy): _spread_gate_allows_entry reads top_bid_price/top_ask_price off the /optionchain response and refuses an entry wider than the cap in paper AND live, while an unreadable quote refuses LIVE only. The source's VIX and breadth vetoes remain unimplemented — absent by choice, not for want of data (the source runs on Dhan too). An optional, opt-in CPR Codex AI Agent is an independent five-minute SRSI/VWAP worker. It freezes completed-bar context behind four frozen no-argument MCP tools; Codex judges regime, setup, and premise exits, while the host owns deterministic entry/risk gates and execution. It is disabled by default, live-disabled by default, and uses the normal global-plus-strategy double gate. Accepted SIDEWAYS setups sell naked current-expiry ATM premium (bullish PE, bearish CE); TRENDING setups retain the existing option buys and expiry. Spot stops trigger exits but cannot guarantee fills. Ordinary CPR, CPR Algo 3, Regime Adaptive, and CPR AI may coexist with independent positions and P&L. Another optional, opt-in worker is LLM-driven: the SL Hunting AI Agent (a Claude agent via claude-agent-sdk) — off by default (SL_HUNTING_ENABLED), it decides once per completed 1-min bar (with BankNIFTY cross-confirmation, fetched per bar like CPR Algo 3, and dynamic ~₹2500 risk-based sizing) and acts through the same ATM enter_position/exit_position; its deps are lazily imported so a missing dep just disables it. Every NIFTY entry is mechanically MIRRORED with an equal-lot BankNIFTY ATM leg (SL_HUNTING_BNF_MIRROR, default true) — NOTE: the mirror roughly DOUBLES the basket's rupee risk beyond SL_HUNTING_RISK_BUDGET (operator-accepted; the daily max-loss kill-switch still caps the day): the legs are TIED for hard risk (stop/target, max-loss, 15:15 square-off close both) but the agent evaluates each leg's premise INDEPENDENTLY and can cut one alone via the EXIT exit_leg selector (NIFTY|BNF|BOTH). Entry stays NIFTY-only (the mirror copies it). It stops opening NEW positions after 10:30 (SL_HUNTING_NO_NEW_ENTRY_HOUR/_MINUTE, default 10:30) — not a square-off (exits + the 15:15 square-off still run; when flat past the cutoff it skips the LLM call entirely). After a target, stop, or premise-invalidating exit, SL_HUNTING_POST_EXIT_COOLDOWN_MINUTES blocks re-entry from the moment the WHOLE NIFTY/BankNIFTY basket is confirmed flat; a lone or partly closed leg does not run the timer down, exits never wait for it, and corrupt guard state rejects new LIVE entries. It can also learn from its own trades (v3): a per-trade journal feeds an off-loop reflection coach (sl_hunting_coach.py) that proposes lessons; the operator promotes approved ones into lessons.json, injected into the prompt only when SL_HUNTING_LESSONS_ENABLED (human-gated, paper-first, off by default). Its knowledge also carries a curated BankNIFTY live-trading layer (v3a, knowledge-only): a BNF_SPECIFIC section (triple-index BNF+NIFTY+Sensex read, BankNIFTY as the "major index", expiry-day priority, round-number magnets) that is advisory context for the cross-index read — execution stays NIFTY-only — plus general lessons merged into the existing sections (distilled from Intraday Hunter videos; provenance in sl_hunting_doc.md). With both optional agents enabled, the configured roster can reach approximately 29 workers, but enable and virtual-trading gates keep the running roster configuration-dependent.
• Each entry/exit is published to a queue.Queue consumed by a single TelegramMessageWorker (best-effort alerts; never blocks trading). That same publish_trade_event choke point also mirrors every event into the crash-durable session state (Dependencies/session_state.py, SESSION_STATE_*, on by default): an atomically-written JSON file holding each closed trade's P&L immediately, plus every OPEN position — entry fill price, stop, target, quantity, contract ids and last cached LTP — snapshotted every 30s from the supervisor thread. Before a replacement run writes anything, it archives the exact prior file and carries same-day realized P&L into every matching worker so a restart cannot reset a daily max-loss budget. It exists because the Sheet is written ONCE at a clean end-of-day, so a mid-session crash (2026-08-10's machine hang) otherwise loses the whole day's books. Resuming OPEN exposure remains opt-in (SESSION_STATE_RESUME_ENABLED, default false) and deliberately narrow — today's date, an unclean shutdown, PAPER, single-leg only; live positions are never restored because the broker account is the authority there. See docs/adr/0012.
• Real orders go through ONE shared, lock-guarded broker session via a broker-agnostic execution_client (see Broker layer). On a clean end-of-day, per-strategy P&L is written to a Google Sheet with separate PAPER/LIVE/MIXED row labels. All behaviour is driven by a single .env — nothing is hard-coded per run.