Build an automated IBKR trading bot with Claude Code

Set up a Python project for an Interactive Brokers PAPER-trading bot in the current directory.

PREREQ CHECK:
1. Print `python --version` (or `py -3 --version` on Windows). It must be 3.12 or newer. If not, STOP and tell me.
2. Confirm the current directory is empty apart from hidden files. If not, STOP and list what is here.

DO:
1. Create a virtual environment in .venv and install ib_async into it (pip install ib_async).
2. Create test_connect.py that connects to 127.0.0.1:7497 with clientId=10 and a 10-second timeout,
   prints the managed accounts, prints "PAPER OK" if every account ID starts with "D" (paper accounts are DU...),
   otherwise prints "NOT A PAPER ACCOUNT" and exits 1, then disconnects in a finally block.
3. Run test_connect.py with the venv's Python and show me the output.

If the connection is refused, tell me to check that TWS is running, logged in to PAPER, and that
File > Global Configuration > API > Settings has socket clients enabled on port 7497.
From now on, always run Python through .venv (on Windows: .venv\Scripts\python.exe).

Place a paper-trading BUY order for 1 share of MU on Interactive Brokers.

PREREQ CHECK:
1. Confirm ib_async imports in the venv. If not, STOP and tell me to install it.
2. Confirm TWS answers on 127.0.0.1:7497 (quick connect with clientId=10). If not, STOP.

CREATE buy_one.py:
- Connect to 127.0.0.1:7497 with clientId=10.
- Account guard: if any managed account does not start with "D", print the accounts and exit 1. Never trade a live account.
- Qualify Stock("MU", "SMART", "USD").
- MarketOrder BUY 1 share. Set order.tif = "DAY" explicitly (without it TWS applies its preset TIF and can cancel the
  order with error 10349). Set order.account to the paper account.
- Wait up to 10 seconds for a terminal status (Filled, Cancelled, ApiCancelled, Inactive). PendingSubmit and
  PreSubmitted are not final.
- Print order ID, fill price (or "pending"), final status. If the order died, print trade.log entries (status,
  message, errorCode).
- Disconnect in a finally block. On a connection error print it and exit nonzero.

RUN buy_one.py with the venv's Python. Print its output and: "ORDERED: 1 share MU. Check TWS positions."
Do NOT close the position. That is the next step.

Create a safe manual close script for the paper account.

PREREQ CHECK:
1. Confirm buy_one.py exists. 2. Confirm TWS answers on 127.0.0.1:7497.

CREATE close_one.py (usage: python close_one.py --symbol MU; --symbol is REQUIRED):
- Connect with clientId=11. Same paper-account guard as buy_one.py.
- Find the position for --symbol via ib.positions(). If none, print "NO POSITION TO CLOSE" and exit 0.
  If the position is short (negative), refuse and exit 1. This script only closes longs.
- FIRST cancel every working SELL order for that symbol (stops included), from ib.reqAllOpenOrders().
  IBKR only lets the placing client cancel an order, so cancel each one from a short-lived connection that uses
  that order's clientId (order.clientId), then confirm none remain working. If any remain, STOP without selling.
- Then MarketOrder SELL the full position with tif="DAY" and the account set. Wait up to 10 s for a terminal status.
- Print sold quantity, fill price, status. Append the SELL to trades.csv if that file exists
  (columns: timestamp_iso (UTC), symbol, side, size, fill_price, order_id, status, stop_price).
- Disconnect cleanly in finally blocks.

Also update buy_one.py if needed so both scripts set tif="DAY" on every order.
RUN: python close_one.py --symbol MU. Print the output and "CLOSED: position flat. Verify in TWS." 

Create the strategy file for the paper-trading bot. It is the ONLY place strategy and risk parameters live.

PREREQ CHECK: Confirm rules.json does not exist yet. If it does, STOP.

CREATE rules.json with exactly this content, then validate it parses as JSON:

{
  "schema_version": 1,
  "strategy_name": "Trend Join Long",
  "direction": "long_only",
  "trade_timeframe": "5m",
  "timezone": "America/New_York",
  "account_guard": {"mode": "paper", "required_account_prefix": "D", "port": 7497},
  "universe_filters": {"index": "S&P 500", "min_price_usd": 3.0, "exclude_if_halted": true},
  "daily_filters": {
    "D1_above_prior_day_high": true, "D1_price_source": "last_trade_at_evaluation",
    "D2_prior_close_above_sma200": true, "D2_sma_length_days": 200,
    "D3_min_gap_pct_from_prior_close": 3.0, "D3_gap_direction": "up_only",
    "D3_gap_measured_at": "regular_session_open", "D3_max_gap_pct_from_prior_close": null
  },
  "intraday_filters": {
    "I1_above_premarket_high": true, "I1_premarket_window_et": ["04:00", "09:30"],
    "I2_above_today_hod": true, "I2_trigger": "5m_bar_close_above_prior_hod",
    "I3_rvol_min": 2.0, "I3_rvol_lookback_days": 14,
    "I3_rvol_method": "cumulative_volume_vs_same_time_of_day_avg"
  },
  "time_filter": {"earliest_entry_et": "10:05", "latest_entry_et": "15:30", "force_close_et": "15:51"},
  "entry": {
    "order_type": "marketable_limit", "limit_offset_pct_above_ask": 0.2, "unfilled_cancel_after_sec": 30,
    "tif": "DAY", "max_entries_per_symbol_per_day": 1, "candidate_ranking": "rvol_desc"
  },
  "exit": {
    "initial_stop_rule": "lod_minus_1pct", "lod_reference": "regular_session_low_at_entry",
    "R_definition": "entry_price_minus_initial_stop",
    "partial_profit_trigger_R": 0.75, "partial_profit_fraction": 0.3333, "breakeven_trigger_R": 1.0,
    "post_breakeven_trail": "swing_low_5m_2_2", "trail_pivot_left_bars": 2, "trail_pivot_right_bars": 2,
    "trail_only_ratchets_up": true, "stop_order_resides_at_broker": true, "tif": "DAY"
  },
  "risk": {
    "max_risk_per_trade_pct": 1.0, "max_position_size_pct_of_portfolio": 10, "max_concurrent_positions": 5,
    "max_daily_loss_pct": 3.0, "max_new_entries_per_day": 5,
    "sizing_rule": "min(risk_based_shares, position_cap_shares)", "skip_if_sized_shares_below": 1
  }
}

Print the file back. Do not create other files.

Create the configuration files.

PREREQ CHECK: rules.json exists; .env, .gitignore and requirements.txt do not. Otherwise STOP.

CREATE:
1. .env  (connection, account size and secrets ONLY; strategy and risk limits live in rules.json)
   # Environment and secrets only. Strategy and risk parameters live in rules.json.
   IBKR_HOST=127.0.0.1
   IBKR_PORT=7497
   IBKR_CLIENT_ID=2
   IBKR_EXEC_CLIENT_ID=3
   PAPER_TRADING=true
   PORTFOLIO_VALUE_USD=25000
   TELEGRAM_BOT_TOKEN=
   TELEGRAM_CHAT_ID=
2. .env.example  (same keys, empty secret values, safe to share)
3. .gitignore: .env  .venv/  __pycache__/  *.pyc  trades.csv  logs/  open_positions.json
   safety-check-log.json  watchlist.txt  dashboard/
4. requirements.txt (unpinned): ib_async python-dotenv pandas numpy yfinance requests

Install requirements.txt into .venv, then write requirements.lock with `pip freeze` so the exact tested versions
can be reinstalled later. Print the file tree. Never print the contents of .env after secrets are added.

Create the core files of the IBKR paper-trading bot. Read rules.json and .env first; strategy and risk numbers
come ONLY from rules.json. Use ib_async (not ib_insync), pathlib, zoneinfo, and anchor every path to the project
folder (Task Scheduler starts scripts in C:\Windows\System32).

PREREQ CHECK: rules.json, .env, requirements.txt exist; Python >= 3.12; ib_async, dotenv, pandas import;
src/ibkr_client.py, strategy.py, trade.py, bot.py do not exist.

CREATE:
1. src/__init__.py (empty)
2. src/ibkr_client.py: class IBKRClient(host, port, client_id, required_account_prefix="D", timeout=10)
   - connect; ACCOUNT GUARD: if any managed account doesn't start with the prefix, disconnect and raise.
   - place_order(symbol, side, qty, limit_price=None, settle_timeout=10): qualify Stock(symbol,"SMART","USD");
     MarketOrder if no limit, else LimitOrder (outsideRth=True); ALWAYS order.tif="DAY" and order.account set;
     wait for a terminal state (Filled, Cancelled, ApiCancelled, Inactive), not PendingSubmit.
   - place_stop(symbol, qty, stop_price): SELL StopOrder, tif DAY, wait until TWS accepts or rejects it.
   - cancel_if_working(trade), disconnect().
3. strategy.py: evaluate(symbol, ib, portfolio_value_usd=None) -> dict, safety gates only (no D1-I3 filters yet):
   a) already holding the symbol, OR a BUY order for it working from ANY client (reqAllOpenOrders) -> fail
   b) weekday and inside earliest/latest entry time (ET) from rules.json
   c) IBKR session check from contract details liquidHours (catches holidays and 1 PM half-days)
   d) max concurrent positions from rules.json
   e) daily loss gate: today's P&L from ib.reqPnL (poll up to ~6 s); if silent, fall back to realized P&L from
      trades.csv + unrealized from ib.portfolio(); if neither is trustworthy, FAIL CLOSED with
      "daily PnL unavailable; cannot verify loss limit"; fail if P&L <= -max_daily_loss_pct of portfolio.
   f) live price: reqMarketDataType(3) then reqMktData; wait up to 10 s for the first tick (first ticks after a TWS login
      can take ~5 s); fall back to today's 5-minute bars; return price, ask, day_low, price_source, data_delayed
      (True when marketDataType is 3/4 or the last bar is stale).
   Cast numpy values to Python types; append every result to logs/safety_log.jsonl.
4. trade.py: the ONLY process that places or changes orders, on IBKR_EXEC_CLIENT_ID. Last stdout line is always
   `RESULT {json}`. Port guard: PAPER_TRADING=true with port 7496/4001 (or the reverse) aborts.
   Modes:
   - order: --symbol --side BUY|SELL --size N [--limit P] [--stop P]. A BUY with --limit waits
     unfilled_cancel_after_sec, cancels any unfilled remainder, keeps a partial fill. A BUY with --stop places a
     broker stop for exactly the FILLED quantity; if that stop is rejected, market-sell the fill immediately.
   - --modify-stop PERMID [--stop P] [--stop-qty N]: modify in place (same orderId), REFUSE to lower the price.
   - --place-stop --size N --stop P.
   - --flatten: cancel this client's working SELLs for the symbol; REFUSE if another client's SELL is still working;
     then market-sell the whole position.
   Append every fill to trades.csv: timestamp_iso (UTC), symbol, side, size, fill_price, order_id, status, stop_price
   (the initial stop on BUY rows). Retry once if the file is locked. Migrate an older header automatically.
5. bot.py: single-symbol tool. --symbol (required), --check-only, --allow-delayed.
   Load .env, port guard, paper-mode check from rules.json, daily entry cap from rules.json (count today's BUY rows
   comparing ET dates, not UTC strings), connect on IBKR_CLIENT_ID, strategy.evaluate, disconnect.
   Refuse to trade on delayed data unless --allow-delayed. Size = min(floor(portfolio*risk%/(price-stop)),
   floor(portfolio*cap%/price)) with stop = day_low * (1 - 1%). Limit = ask * 1.002.
   Spawn trade.py BUY with --limit and --stop; subprocess timeout = fill wait + 30 s (a 30 s timeout would kill a 30 s
   fill wait). Report from the ledger. Prefix prints with [HH:MM:SS ET].

AFTER: print the file tree and "READY: run .venv\Scripts\python.exe bot.py --symbol NVDA --check-only". Do not run it.

Create src/sp500_tickers.py with one constant SP500_TICKERS: every current S&P 500 ticker (about 503),
sorted, hard-coded (no fetching at import). Use IBKR format with a space for class shares ("BRK B", "BF B").

Get the list from the current Wikipedia "List of S&P 500 companies" page (fetch it; do not rely on memory). Add a
comment with the source and date. Print the count and the first and last 5 entries. Create no other files.

Create morning_prefilter.py, the gap scanner. Do not modify other files.

PREREQ CHECK: src/sp500_tickers.py exists; yfinance imports; morning_prefilter.py does not exist.

BEHAVIOUR:
- Args: --min-gap (default 3.0), --min-price (default 3.0), --dry-run (don't write watchlist.txt).
  If either threshold is LOOSER than the defaults and --dry-run is not set, refuse with exit 2: test thresholds must
  never overwrite the bot's real watchlist.
- Paths anchored to the script's folder. Convert "BRK B" -> "BRK-B" for Yahoo.
- yf.download(tickers, period="2d", interval="1d", group_by="ticker", threads=5, progress=False, auto_adjust=True).
  threads=5, not more: higher concurrency exhausts file handles under Task Scheduler.
- Per ticker: only use it if the last bar is dated TODAY (ET). gap_pct = (today's OPEN - prior close) / prior close.
  Keep if gap >= min-gap and price >= min-price. Count below_gap, below_price, failed (bad data, continue), no_today_bar.
- If at least half the tickers have no bar for today (pre-open, weekend, holiday): do NOT write a watchlist; print an
  error JSON and exit 1.
- Sort by gap, keep top 20. Write watchlist.txt atomically (temp file + os.replace) with a header line
  "# Auto-generated by morning_prefilter.py at YYYY-MM-DD HH:MM ZONE" (the bot checks this date), then lines like
  "AAPL  # gap +3.45%  open $185.20  prev $180.00".
- Print a JSON summary: success, as_of_date_et, total_screened, survivors_count, below_gap, below_price, failed,
  failed_tickers, no_today_bar, elapsed_seconds, top_20_survivors, watchlist_path.
- Tripwires to stderr: failed >= 95% -> "ALERT: Yahoo-wide failure suspected"; >= 30% -> "ALERT: yfinance degradation".

AFTER: print "READY: run morning_prefilter.py --dry-run". Do not run it.

Create cycle.py, the autonomous 5-minute trading cycle. It reuses bot.py sizing and strategy.evaluate.
cycle.py connects on IBKR_CLIENT_ID and is READ-ONLY at the broker: every order action (entries, stop changes,
partial sells, force-closes) runs `trade.py` as a subprocess and parses its RESULT line.

PREREQ CHECK: bot.py, trade.py, strategy.py, rules.json, morning_prefilter.py, src/ibkr_client.py exist;
cycle.py does not.

main() in order:
1. TIME GATE using only the standard library (import pandas/yfinance/ib_async lazily, after the gate, so weekend and
   off-hours runs exit in under 1 s): weekend | too_early (<10:00) | closed (>=16:00) | manage_only (10:00-10:05 and
   after latest entry) | force_close (>= force_close_et) | ok. After connecting, re-check against IBKR's real session
   close for today (SPY liquidHours): exit on holidays; on half-days shift force-close and last-entry by the same
   distance from the close.
2. LOCK file logs/cycle.lock (stale after 600 s) so runs never overlap. Write logs/heartbeat.json every run and one line
   per stage to logs/cycle_runs.jsonl.
3. CONNECT (retry once after 5 s; on failure log connect_failed, alert, exit 1).
4. RECONCILE with the broker (source of truth), state in open_positions.json (atomic writes):
   - position gone at the broker: look for a fill whose permId == the position's stop_perm_id (reqExecutions).
     Found -> stop-out: append a SELL row with status StopFilled, alert. Not found -> closed externally, alert.
     NEVER match by quantity.
   - quantity differs -> trust the broker.
   - adopt broker positions bought TODAY by the bot (BUY rows in trades.csv) that state doesn't know (crash recovery).
   - every position must have a broker stop covering exactly its quantity: fix the quantity in place, or place one at
     the current stop / day low - 1%; if impossible, log UNPROTECTED_POSITION and alert at high priority.
5. MANAGE with live IBKR prices (skip a position whose data is delayed; its broker stop still protects it):
   - state "open" and price >= entry + 0.75R: k = ceil(qty x 0.3333). FIRST shrink the stop to qty-k (modify in place),
     THEN sell k. If the sale fails, restore the stop to the full quantity. If k would be the whole position, flatten.
   - state "partial_done" and price >= entry + 1R: modify the stop to the entry price (breakeven), then state "trailing".
     Partial and breakeven may both happen in the same cycle.
   - "trailing": newest confirmed swing low among COMPLETED regular-session 5-minute bars since entry (low below the 2 bars
     before and 2 after). New stop = swing low - 0.01, only if above the current stop and below price (ratchet up only).
   - stops are always MODIFIED IN PLACE (trade.py --modify-stop), never cancelled and re-placed.
6. FORCE CLOSE window: trade.py --flatten each position; keep failures in state so the next cycle retries.
7. MANAGE ONLY window: stop here.
8. ENTRY SCAN: daily entry cap from rules.json; read watchlist.txt only if its header date is TODAY; split lines on "#"
   (class shares contain a space); skip anything held (ib.positions() FIRST) or in state.
   Pull yfinance daily (1y) and 5-minute (30d, prepost=True) data in one batch each, through a helper with a hard 60-second
   wall-clock deadline (daemon thread); on timeout log yfinance_timeout, alert, skip the step, and hard-exit at the end.
   Evaluate the six filters on COMPLETED bars only:
     D1 last completed 5m close > prior day high; D2 prior close > 200-day SMA; D3 (official daily open - prior close)
     / prior close >= 3%; I1 last close > premarket high (04:00-09:30); I2 last completed bar closes above the high of
     the earlier bars today; I3 cumulative RTH volume through that bar / average cumulative volume at the same time of
     day over the previous 14 sessions >= 2.0.
   Rank passing symbols by RVOL. For each: strategy.evaluate (live gate; skip if delayed), size with bot.size_position,
   limit = ask x 1.002, run trade.py BUY --limit --stop, save state IMMEDIATELY after a fill.
9. Save state, release the lock, disconnect, rebuild the dashboard if one exists (never let that break trading).

Log every decision as one JSON line in safety-check-log.json (cast numpy types). Unhandled exception -> traceback to
logs/cycle_errors.log, exit 1. Prefix prints with [HH:MM:SS ET].

AFTER: print "READY: run cycle.py; outside market hours it exits in under a second". Do not run it.

Add Telegram push notifications. Do NOT change any trading logic; only add notification calls.

PREREQ CHECK: cycle.py, morning_prefilter.py, src/__init__.py exist; requests imports; src/notify.py does not exist.

CREATE src/notify.py with notify(title, body, priority="default") -> None:
- Load TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID and optional NOTIFY_URL (ntfy) from .env (explicit path).
- Telegram: POST sendMessage with parse_mode="HTML" (NOT Markdown) and html-escaped title/body, "⚠️ " prefix for
  high priority, 5 s timeout, max 4096 chars. ntfy: POST body with Title and Priority headers.
- Never raise. Log failures to logs/notify_errors.log with the bot token REDACTED (also redact any bot<digits>:<key>).
- Never print the token or chat ID anywhere.

WIRE IT IN (each call wrapped so a failure can't affect trading):
- morning_prefilter.py (not on --dry-run): message only when the list is the first of the day or changed:
  "Prefilter HH:MM ET" with "N/503 survivors" and a bullet per ticker. Failures and tripwires at high priority.
- cycle.py: BUY, PARTIAL, BE, TRAIL, STOP, CLOSED (position gone, not a bot stop), EXIT, "EOD Force Close" (high),
  "Cycle CRASHED" (high), yfinance timeout; critical events (UNPROTECTED_POSITION, FORCE_CLOSE_FAILED, connect_failed,
  trade_timeout) at high priority, de-duplicated per symbol for an hour.

AFTER: print how to test: .venv\Scripts\python.exe -c "from src.notify import notify; notify('Test', 'Hello')" 

Add the daily performance summary and log rotation.

CREATE compute_perf.py (read-only on trades.csv; safe any time):
- Load trades.csv. Match BUY and SELL by SHARES, FIFO per symbol: one BUY lot is
  one trade, closed when all its shares are sold (partials roll into the same trade). Use ET dates.
- Per trade: entry, average exit, P&L $, P&L %, hold minutes, initial stop (BUY row's stop_price; else the cycle's
  decision log; else a 1% proxy flagged as estimated), R = (avg exit - entry) / (entry - initial stop), exit kind.
- Aggregates: total_trades, wins, losses, win_rate_pct, gross_pnl_usd, largest winner/loser, avg winner/loser,
  profit_factor ("inf" if no losses, "n/a" if no trades). Print JSON.
- Unless --no-notify: one Telegram message "Daily Summary YYYY-MM-DD". Options --date, --no-notify, --no-dashboard.

CREATE rotate_logs.py (exit 0 even with nothing to do):
- logs/*.log and logs/*.jsonl last modified before today (ET) -> logs/archive/<date>/ with os.replace.
- trades.csv rows older than 90 days -> logs/archive/trades_<today>.csv, but NEVER between 09:25 and 16:15 ET.
- safety-check-log.json over 5 MB -> archived with today's date.
- Skip files another process has open (Windows) and retry next run. Staged, atomic swaps only.

AFTER: print how to run both. Do not run them.

Create setup_schedule.py and cleanup_schedule.py for Windows Task Scheduler (current user, no admin).

PREREQ CHECK: cycle.py, morning_prefilter.py, compute_perf.py, rotate_logs.py and .venv\Scripts\pythonw.exe exist;
we are on Windows (`where schtasks`). Otherwise STOP.

setup_schedule.py [--dry-run]:
- Register these 5 tasks, Monday-Friday, times in ET converted to this PC's local time with zoneinfo:
  HT_LogRotate 09:15 rotate_logs.py; HT_KeepAwake 09:30 `powercfg /change standby-timeout-ac 0`;
  HT_Prefilter 09:52 repeating every 30 min until 12:52; HT_Cycle 10:01 repeating every 5 min until 15:56;
  HT_Dashboard 16:05 compute_perf.py.
- Build each as Task Scheduler XML and register with `schtasks /create /tn NAME /xml FILE /f` (XML saved as UTF-16 in
  logs/schedule/). Settings: Priority 4 (NOT the default 7, which also lowers I/O priority and made cycles ~15x slower),
  DisallowStartIfOnBatteries false, StopIfGoingOnBatteries false, WakeToRun true, StartWhenAvailable true,
  MultipleInstancesPolicy IgnoreNew, ExecutionTimeLimit PT10M, working directory = project folder,
  command = .venv\Scripts\pythonw.exe (no console windows). Use ISO dates in the XML (no locale parsing).
- Before changing power settings, save the current sleep timeout to logs/power_backup.json.
- Warn if this PC's time zone changes daylight saving time on different dates than New York.
- --dry-run: write the XML only. Print a table of HT_* tasks with next run times.

cleanup_schedule.py: delete every HT_* task and restore the saved sleep setting (or 30 min if none). Idempotent;
"Nothing to clean." when there are none. This is the emergency stop.

AFTER: print how to run both. Do NOT register anything yourself.

Create dashboard.py and call it from compute_perf.py and at the end of each working cycle (wrapped so it can
never affect trading).

dashboard.py builds dashboard/index.html, self-contained: inline CSS and inline SVG charts, NO JavaScript, NO CDN
links, <meta http-equiv="refresh" content="30">, <meta name="robots" content="noindex">. Dark theme.
Content, from trades.csv (all history), open_positions.json, logs/heartbeat.json and safety-check-log.json:
- KPI strip: today P&L, total P&L (% of PORTFOLIO_VALUE_USD), win rate, expectancy (R and $), profit factor,
  max drawdown and loss streak.
- Bot status from the heartbeat: ACTIVE (recent cycle), STALE (cycles stopped during market hours), IBKR DOWN
  (connect_failed), IDLE (outside hours), NO DATA. Show heartbeat time, entries today vs cap, risk settings.
- Equity curve (cumulative P&L per closed trade), R-multiple histogram (<=-2R ... >+3R), daily P&L bars.
- Open positions: qty, entry, current stop, last price, unrealized $ and R, and a small track from stop to +2R.
- Recent closed trades (last 20) with R colour-coded, a by-symbol table, and the latest bot decisions.
Use the FIFO/R logic from compute_perf.py. Escape all text. Axis ticks must enclose the data range.

AFTER: print "READY: run dashboard.py and open dashboard/index.html". Do not run it.

It's market hours. Walk me through the end-to-end paper test one command at a time and check each output
before the next: (1) bot.py --symbol NVDA --check-only, (2) bot.py --symbol NVDA, (3) verify in IBKR that the position
and its stop exist, (4) close_one.py --symbol NVDA, (5) verify flat with no working orders, (6) compute_perf.py
--no-notify. If anything fails, stop and diagnose; do not schedule anything. If all pass, show me
setup_schedule.py --dry-run and wait for my go-ahead before registering the tasks.