IBKR Trader Toolkit#

Real-time data, options analysis, and portfolio risk for Interactive Brokers — all via JSON-emitting CLI scripts.

Core rule: Scripts produce data. You (the model) produce the analysis.

---

When to trigger this skill#

User asks about...Example phrasingStock / ETF prices"What's SPY at?" "Current AAPL price"Option chains, Greeks, IV"Show me AAPL puts for next month"Strategy ideas"Should I sell a put on MU?"Position risk"Am I too long delta?"P&L, win rate, history"How are my wheel trades doing?"Earnings risk"Does ARM report before my call expires?"Alerts / monitoring"Warn me if SPY IV > 80%ile"

Fire even if the user doesn't mention IBKR — if they're asking about their positions or P&L, this skill is the source of truth.

Critical: For stock prices, always use market_quote.py. Never web-search a stock price — the web is minutes-to-hours stale.

---

Workflows#

"What's my account state right now?" / "Status update"#

For a one-glance snapshot (positions, Greeks, ITM, this-week expiries, wheel stages):

bash

status_dashboard.py --output telegram   # in chat-style channels
status_dashboard.py --output json       # parse and recompose freely
status_dashboard.py                     # rich ANSI for terminals

Add --full to also include IV environment per held symbol and recent P&L (slower — extra IBKR calls). Use --output json when you (the agent) want to organize the reply yourself instead of inheriting the script's layout.

"Should I sell a put on $SYM?"#

Run these in order, then synthesize:

StepCommandWhy1portfolio_positions.pyKnow existing exposure first2earnings_calendar.py SYM --days 60Avoid earnings inside DTE3options_analyzer.py SYM --outlook bullish --risk-profile conservative --iv-contextGet IV environment + candidate strikes4options_chain.py SYM --dte-min 25 --dte-max 45Live mid prices for chosen strikes

Your recommendation must include: strike • delta • premium • breakeven • annualized yield • earnings/IV warnings.

---

"What's my portfolio looking like?"#

StepCommand1portfolio_positions.py → positions + Greeks2options_daily.py → expiry warnings + IV summary3pnl_analytics.py --days 7 → recent realized P&L

---

"I'm thinking of adding trade X — is it safe?"#

bash

risk_simulator.py --add "SYM STRIKE EXPIRY R ACTION QTY"

Flag any of:

• Vega magnitude doubles → much more IV-exposed
• Net delta flips sign → directional bet now opposite
• One symbol > 30% of capital → concentration risk

---

"How's my wheel doing?"#

bash

wheel_tracker.py summary

Returns per-symbol: stage ( short_put / assigned / covered_call / closed), cumulative premium, days in cycle, annualized return.

---

"Should I roll position X?"#

StepCommandWhy1portfolio_positions.pyConfirm the leg's current strike, expiry, P&L, delta2options_chain.py SYM --dte-min 25 --dte-max 60Survey roll candidates further out3Consult references/wheel_strategy.md"Roll vs accept assignment" decision tree

Your recommendation must include: new strike • new DTE • net credit (new premium − close cost) • effective basis change vs current leg • roll count so far (cap at 2).

---

Script reference#

ScriptWhen to usestatus_dashboard.py [--full] [--output ansi/telegram/json]"What's the state of my account right now?" — one-glance snapshot for terminal, Telegram, or agent consumptionmarket_quote.py SYM [SYM2 ...]Any stock/ETF price questionportfolio_positions.pyWhat do I own? Portfolio Greeksoptions_chain.py SYMStrikes survey + IV by expiryoptions_analyzer.py SYM --outlook X --risk-profile Y --iv-contextStrategy ideas given outlookoptions_daily.pyMorning/EOD options report (start here)pnl_analytics.py [--days N]Realized P&L, win rate, best/worstrisk_simulator.py --add "..."Pre-trade Greeks impactearnings_calendar.py SYM ...Earnings within N daystechnical_indicators.py SYMRSI / MA / BB / ATRwheel_tracker.py summaryWheel cycle status & yieldalerts_monitor.pyThreshold rules (cron-friendly)cost_basis.py SYM [...]Premium-adjusted effective cost basis (wheel)concentration.pyHHI, sector mix, top-N portfolio concentrationflex_import.py [--flex-dir ...]Parse IBKR Flex CSV/XML history into JSONtrade.py <stock|option|combo|...>Place orders (opt-in, dual-gate). See references/trading.md

All read-only scripts:

• Output JSON to stdout (or to --output FILE)
• Read IBKR config from env vars ( IBKR_HOST, IBKR_PORT, IBKR_CLIENT_ID_BASE, IBKR_MARKET_DATA_TYPE)
• Cannot place orders — only trade.py can, and only when both IBKR_TRADING_ENABLED=1 and --confirm-trade are present

---

Pre-trade checklist (every options recommendation)#

Before suggesting any options trade, verify all three:

1. IV environment — from options_analyzer.py --iv-context. Don't sell premium in low-IV; don't buy premium in high-IV.
2. Earnings inside DTE — from earnings_calendar.py. IV crush after earnings flips the math.
3. Existing position Greeks — from portfolio_positions.py. If already +5000 delta, adding more is wrong direction-of-thesis or not.

State each check explicitly:

"IV environment: low (ratio 0.7); earnings: none in next 45 days; current net delta: +1,200."

This lets the user audit the reasoning.

---

Operating constraints#

ConstraintWhat it meansJSON in, judgement outThe script's recommendations list is candidate data, not a final answer. Re-rank against the user's situation.Smart data typeIBKR_MARKET_DATA_TYPE=3 by default — IBKR auto-upgrades to realtime when user is subscribed, falls back to delayed otherwise. If quotes look stale, check market hours + subscriptions.One clientId per scriptIf you see clientId already in use, wait a few seconds or bump IBKR_CLIENT_ID_BASE.Cache chains across callsoptions_chain.py --output /tmp/chain.json then options_analyzer.py --chain-file /tmp/chain.json saves IBKR roundtrips.

---

Deeper references#

Read on demand when the user's question warrants it:

• references/strategies.md — full McMillan/Overby strategy library + selection matrix
• references/greeks_primer.md — practical Delta/Gamma/Vega/Theta interpretation
• references/wheel_strategy.md — strike/DTE selection, roll-vs-assign decision tree
• references/options_book_summary.md — McMillan/Overby/Natenberg/Sinclair operational rules
• references/troubleshooting.md — connection errors, subscription issues