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

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:

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

"What's my portfolio looking like?"

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

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

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

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