ibkr-options-assistant

name

ibkr-options-assistant

description

Interactive Brokers options & stock trading assistant. Provides real-time portfolio Greeks, option chain analysis, McMillan/Overby strategy recommendations, P&L statistics, Wheel strategy tracking, earnings warnings, risk simulation, and a complete toolkit for options traders. Use this skill whenever the user asks about specific options trades, position risk, buy/sell recommendations, IV environment, P&L, wheel strategy, earnings impact on options, or any IBKR account data — even if they don't explicitly mention "IBKR". For stock price queries, always use market_quote.py instead of web search.

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 phrasing
Stock / 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):

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:

Step	Command	Why
1	portfolio_positions.py	Know existing exposure first
2	earnings_calendar.py SYM --days 60	Avoid earnings inside DTE
3	options_analyzer.py SYM --outlook bullish --risk-profile conservative --iv-context	Get IV environment + candidate strikes
4	options_chain.py SYM --dte-min 25 --dte-max 45	Live mid prices for chosen strikes

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

---

"What's my portfolio looking like?"

Step	Command
1	portfolio_positions.py → positions + Greeks
2	options_daily.py → expiry warnings + IV summary
3	pnl_analytics.py --days 7 → recent realized P&L

---

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

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?"

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?"

Step	Command	Why
1	portfolio_positions.py	Confirm the leg's current strike, expiry, P&L, delta
2	options_chain.py SYM --dte-min 25 --dte-max 60	Survey roll candidates further out
3	Consult 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

Script	When to use
status_dashboard.py [--full] [--output ansi/telegram/json]	"What's the state of my account right now?" — one-glance snapshot for terminal, Telegram, or agent consumption
market_quote.py SYM [SYM2 ...]	Any stock/ETF price question
portfolio_positions.py	What do I own? Portfolio Greeks
options_chain.py SYM	Strikes survey + IV by expiry
options_analyzer.py SYM --outlook X --risk-profile Y --iv-context	Strategy ideas given outlook
options_daily.py	Morning/EOD options report (start here)
pnl_analytics.py [--days N]	Realized P&L, win rate, best/worst
risk_simulator.py --add "..."	Pre-trade Greeks impact
earnings_calendar.py SYM ...	Earnings within N days
technical_indicators.py SYM	RSI / MA / BB / ATR
wheel_tracker.py summary	Wheel cycle status & yield
alerts_monitor.py	Threshold rules (cron-friendly)
cost_basis.py SYM [...]	Premium-adjusted effective cost basis (wheel)
concentration.py	HHI, sector mix, top-N portfolio concentration
flex_import.py [--flex-dir ...]	Parse IBKR Flex CSV/XML history into JSON
trade.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

Constraint	What it means
JSON in, judgement out	The script's recommendations list is candidate data, not a final answer. Re-rank against the user's situation.
Smart data type	IBKR_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 script	If you see clientId already in use, wait a few seconds or bump IBKR_CLIENT_ID_BASE.
Cache chains across calls	options_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