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 28-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 28 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) / CPR Algo 4 (deterministic Intraday SRSI VWAP) / 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). CPR Algo 4 (CPRAlgo4StrategyWorker, CPR_ALGO4_*) is the deterministic version of the SRSI/VWAP playbook CPR AI traded before its Trend-Day Rider (below): the 09:25 5-min close against [MIN(S1,PDL), MAX(R1,PDH)] fixes a SIDEWAYS day (Stochastic RSI 20/80 reversals, swing stop) or a TRENDING day (VWAP pullbacks with RSI/EMA filters that flip on LH+LL / HH+HL structure and re-enter via a reversal sequence); every signal BUYS the ATM CE/PE. Its broker-free engine (Signal Generators/CPR Strategy/cpr_algo4_signal_generator.py) is driven identically by the worker and cpr_algo4_backtest.py. It is its own worker, NOT a fourth algo inside CPRStrategyWorker (that worker has one position slot, one live gate and one Sheet row) -- see docs/adr/0018. Its R1 add and two-leg exit began as a copy of CPR AI's former mechanics; CPR AI no longer has an add, so Algo 4 now holds the only copy. An optional, opt-in CPR Codex AI Agent runs the Trend-Day Rider (docs/adr/0019, chosen from a five-year study on real weekly option premiums). On a completed 5-min bar starting 11:00-13:30 the host flags a candidate when the session range exceeds ATR5 and the close sits in the outer 15% of that range on the trend side of VWAP (bullish also needs 2 of 3 confluence factors: beyond R1, a gap up, more than 0.35 x ATR5 from VWAP). That gate lives in cpr_ai_trend_day.py and is shared with cpr_ai_trend_day_backtest.py. Codex, behind four frozen no-argument MCP tools, is consulted only on a candidate (accept or veto -- never reverse it) and, while a position is open, for premise exits; the host owns every price, gate and order. Every entry SELLS the opposite current-week ATM option (bullish PE, bearish CE) with a fixed VWAP spot stop, no target, and one entry per session. It is disabled and live-disabled by default under the normal global-plus-strategy double gate. Spot stops trigger exits but cannot guarantee fills. Ordinary CPR, CPR Algo 3, CPR Algo 4, 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). The NIFTY stop fires on a completed 1-min candle's CLOSE beyond it, plus an intrabar backstop at 1.5x its distance (SLH-027, SL_HUNTING_STOP_ON_CLOSE / _STOP_BACKSTOP_MULTIPLE). 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 30 workers, but enable and virtual-trading gates keep the running roster configuration-dependent.
• An optional, opt-in read-only monitoring dashboard (DASHBOARD_ENABLED, default false) serves a browser page on 127.0.0.1 answering "where do I stand right now": open trades with live marks and running P&L, today's closed trades grouped by strategy, per-strategy realized/open/total, and a live NIFTY candle chart. Read-only by construction — GET is the only method (anything else is 405), routes are a frozen whitelist, and nothing it calls can reach the broker. One daemon builder thread publishes an immutable JSON blob that HTTP threads hand out, so no browser tab ever touches a worker. It must never call market_data_health.snapshot() (which MUTATES the liquidation clock's state), _get_open_position_pnl/_get_option_ltp (broker fallback), or SessionStateStore.snapshot() on a tick; a test asserts all three. DASHBOARD_BIND_HOST is a module constant with deliberately NO .env knob. Stopped LAST, after the session is flat and results are published. Pure shaping in Dependencies/dashboard_snapshot.py, chart indicators in dashboard_indicators.py, transport in dashboard_server.py, the collector in the master beside _worker_session_state_snapshot; see docs/adr/0016. One opt-in exception to read-only: DASHBOARD_LIVE_TOGGLE_ENABLED (default false) adds a per-strategy LIVE/PAPER button and exactly one POST, /api/live-mode. That POST is guarded by Origin, a per-process token and a typed strategy name, and it only QUEUES a request (Dependencies/live_mode_control.py). A LiveModeController thread runs _live_promotion_refusal, the runtime twin of the startup gate. Paper -> live still needs LIVE_TRADING_ENABLED at startup, a clean _live_config_errors and a broker login, plus the flat-account audit (via the shared _live_broker_login_ok + _preload_and_audit_live_account) when nothing is live yet. The controller NEVER writes live_trading; the worker applies the request itself in _apply_pending_live_mode_if_safe (called from _run_shutdown_cycle_if_requested), and only when flat, because the order path reads that flag more than once per order. Session-only; .env is never written. Toggle alerts bypass publish_trade_event so they never touch the trade books. See docs/adr/0021. The chart carries CPR, a session VWAP and a stochastic %K/%D sub-pane, with a 1m/5m/D toggle (the two minute timeframes ride in ONE /api/chart payload, so switching between them needs no fetch). It also switches INSTRUMENT between NIFTY and, when DASHBOARD_BANKNIFTY_ENABLED is on (default false), BankNIFTY. That is why SharedMarketDataStore's OHLC pool is keyed (instrument, timeframe) -- instrument is keyword-only and defaults to PRIMARY_INSTRUMENT, so every worker's store.get("1") is unchanged. SecondaryIndexPublisher fetches BankNIFTY over REST in BOTH feed modes on its own slow cadence, strictly after the feed-health gate and in its own try/except; record_market_data_refresh reads the PRIMARY frame hard-coded and must stay that way, because it drives the 30-second liquidation clock. Nothing trades off the secondary frame and the tick path never builds bars for it. Each instrument has its own chart cache, publisher slot, CPR ladder and scroll-back. The chart also carries an indicator menu (EMA/SMA/Bollinger/ Supertrend as overlays, RSI/MACD/ATR/ADX in their own panes, with editable periods, several instances allowed, persisted in localStorage). Those are computed in the BROWSER from dashboard_assets/dashboard_indicators.js, because the history pages are immutable bytes rendered once at startup -- so a server-side indicator could not survive a scroll-back. They are CHART-ONLY and no strategy reads them; a node-backed drift test pins every one of them against misc_strategy_common's TA-Lib helpers. The operator can also DRAW support and resistance on it -- horizontal lines and shaded zones, click to place, drag to move, editable to an exact price -- kept in localStorage under their own key, per instrument and shared across timeframes. They persist in the browser because the server implements GET and nothing but GET; that is a safety property, so there is no endpoint to save them to. See docs/adr/0020. It also scrolls back through years of history: Dependencies/dashboard_history.py reads the CSV algo.py fetch-data writes and serves it from /api/history in pages of 2,000 bars, loaded once on a thread of its own (~29.5s, ~63 MB for five years) and never on the trading path. A missing CSV is not an error -- the chart shows the live session alone. CPR is drawn as one band per day, spanning that day only, from that day's predecessor; the Daily timeframe takes a monthly ladder instead, and hides VWAP, which means nothing on a daily candle. VWAP and the stochastic are the strategies' OWN objects, reached through load_module under BARE names so sys.modules returns the already-loaded instance rather than a second copy. CPR is the one deliberate divergence and is labelled CHART-ONLY everywhere: it reads the prior session 09:15-15:15 inclusive (high, low AND close) while CPR / CPR Algo 3 / CPR Algo 4 / CPR AI keep using the full session and its last intraday close -- those strategies are untouched, only the input WINDOW differs, and a test feeds an untruncated session through both to prove the algebra has not forked. See docs/adr/0017.
• 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. Every worker enumerates its open positions through _owned_open_positions(), so the marks file's owned_positions key covers the three families whose exposure never lived in worker.pos (Delta-0.2 CE/PE, the strangle legs, the SL-Hunting BankNIFTY mirror) — a class overriding _paper_positions_active without that hook fails a policy test. open_position keeps its exact prior shape because it is the only key resume reads, and NOTE update_worker_snapshot copies a FIXED key list: a new snapshot key not named there is silently dropped. 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. After a natural end of day whose Sheet write SUCCEEDED, shutdown deletes the state file, its marks and every recovery archive (_remove_published_session_state); a Ctrl+C or a Sheet outage keeps them as the only durable record. 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.