v2.2.0

The data flows out. Orders don't go in.

ibkr is a read-only interface to your Interactive Brokers account, reachable from a Go library, a shell CLI, a stdio MCP server (Claude Desktop, Cursor, Continue, Zed), and a Claude Code plugin. Hand it to an assistant, a cron job, a notebook, or your own service.

What's new in v2.2.0

• The risk constitution now nudges instead of nagging. Governance follow-ups that used to rely on the operator remembering them — reconcile coming due, a drawdown tier consuming its budget, policy drift between siblings — surface as advisory nudges in the paired app and the daily brief. Everything stays shadow/advisory: no nudge blocks an order, and the monthly governance pulse is acknowledged with one tap on the paired device. Action required: none; nudges activate only under an approved v4 risk policy and stay silent otherwise.
• The regime dashboard's gamma indicator measures the market again. A gateway quirk was silently zeroing every call leg's open interest, which forced the dealer-gamma reading permanently negative — a data artifact, not a market signal. Open-interest capture is now right-aware, and per-leg call OI in ibkr chain is correct again.
• The HYG/SPY credit row now degrades gracefully to the latest official close when a live tick is missing, instead of erroring out and destabilizing regime stage transitions.

Claude Desktop MCPB

Download ibkr.mcpb from the Assets section below or from:

https://github.com/osauer/ibkr/releases/latest/download/ibkr.mcpb

Open the .mcpb file with Claude Desktop, drag it into Claude Desktop, or use Settings -> Extensions -> Advanced settings -> Install Extension. The bundle carries the local ibkr binary for macOS and Linux. Windows is not supported outside WSL because the daemon uses Unix-only primitives.

Shell and generic MCP install

curl -fsSL https://raw.githubusercontent.com/osauer/ibkr/main/install.sh | sh
ibkr setup claude-desktop

The first command picks the right binary for your platform, verifies its SHA-256, installs it to ~/.local/bin/ibkr, and adds that directory to your PATH if needed. On macOS it also clears the Gatekeeper quarantine flag. The second command writes the legacy MCP server entry into Claude Desktop's config; fully quit Claude Desktop and reopen.

If you only want the shell tool, stop after the first command and try:

ibkr account
ibkr quote AAPL
ibkr positions --by underlying

Prerequisite: a running IB Gateway 10.37+ or TWS (paper or live) on the same machine. The daemon auto-discovers it across the four standard ports.

See the README for the full feature menu and the troubleshooting matrix. Read-only by construction; the Safety section walks through the four guards.

⚠️ Broker-write capable build (ibkr-trading-* tarballs)

Everything above — the installer, the MCPB bundle, and the plain ibkr-v2.2.0-* tarballs — is read-only by construction: order transmission is not compiled in.

The ibkr-trading-v2.2.0-* tarballs are different: that binary can place, modify, and cancel orders with your broker once you configure the trading gates ([trading] mode plus a pinned gateway endpoint and account, cross-checked against the connected session; every write still needs a submit-eligible preview token). Only download it if you intend to trade through ibkr. Before enabling anything, read SECURITY.md and the trading preview guide, start against a paper account, and verify with ibkr trading status. Each release's order pipeline is exercised by an automated paper-trading round-trip before tagging.

---

Paranoid? Inspect the installer before running it

curl -fsSL https://raw.githubusercontent.com/osauer/ibkr/main/install.sh -o install.sh
less install.sh
sh install.sh

Doing something custom?

• go install: go install github.com/osauer/ibkr/v2/cmd/ibkr@v2.2.0 (or @latest).
• Different install dir: IBKR_INSTALL_DIR=/usr/local/bin sh install.sh. The installer won't touch your shell rc when you override; manage PATH yourself.
• Manual download: pick a tarball or .mcpb from the Assets section below. Verify against SHA256SUMS.
• Cursor / Continue / Zed / other local MCP clients: see Pick your path in the README for the JSON snippet (config file path differs per client).
• Claude Code: /plugin marketplace add osauer/ibkr then /plugin install ibkr@ibkr inside any session.

Windows isn't supported. The daemon uses Unix-only primitives (setsid, flock, AF_UNIX sockets). WSL works.

---

Added

• Risk-governance nudges (advisory/shadow): the daemon derives typed nudge candidates — reconcile due, drawdown tier consumption, sibling policy drift, monthly governance pulse — strictly from active, fully approved, internally consistent v4 policy authority; any unhealthy or pre-v4 posture suppresses candidates with a disclosed typed reason rather than a clean-empty result. Shadow occurrences are timestamped at the first qualifying preview and survive restarts.
• nudges.cutover_review: a fixed-shape, paired-device-only acknowledgement for the governance cutover review. The daemon authenticates the paired session, revalidates the canonical policy report at write time, pins the reviewed coverage and report fingerprint into daemon-owned evidence, and keeps identical retries idempotent while conflicting or stale retries fail closed. It acknowledges review only — it cannot submit broker writes, change freeze or limits, or weaken policy.
• The paired app delivers nudges through alerts and the governance panel, and POST /api/governance/cutover-review accepts only an empty body: origin and evidence are fixed server-side, hostile payloads are rejected before the daemon call, and daemon errors return without private text. The daily brief (ibkr brief) renders the monthly governance aggregate.

Security

• PATCH /api/settings on the paired-app route now rejects any trading.* patch with a 400 before the daemon is called (the CLI remains the only trading-settings surface), and assigns origin server-side as paired_device, discarding whatever origin the client body claims.

Fixed

• Per-leg call open interest is no longer zeroed by the gateway's put-side companion tick. The gateway delivers a call-OI and a put-OI tick on the same option-leg subscription — the opposite-right one carrying zero — and last-write-wins left every call leg at OI 0 (observed: all 6,991 journaled SPX call contracts across five weeks, while puts stayed positive). With call legs zeroed, the dealer-GEX profile became put-only, every sweep point went negative, and the regime dashboard's gamma row was pinned to a permanent "wholly short" reading with no_crossing_in_window on 100% of computes — a measurement artifact, not a market state. ibkr chain per-leg call OI was corrupted the same way. Open-interest capture is now right-aware: a subscription commits only the tick matching its own call/put right, and the zero companion is discarded. Gamma journal rows recorded before this fix (regime gamma decisions and gamma_sign diagnostics) are artifact data — calibration windows restart at the fix.
• The regime dashboard's HYG/SPY row no longer drops to error when the HYG spot subscribe delivers no tick: the fetcher now falls through to the latest official daily close as banding input at any hour and marks the row stale (disclosed via fields_missing: hyg_spot_tick and the quality label). An errored row blanked the band, which bypassed red-exit hysteresis and the confirmation latch — a latched red de-confirmed and re-confirmed around every transient gateway blip (8,012 stage transitions in 5 weeks, median dwell 34 seconds, including 2,344 on a closed-market holiday). A stale row keeps its band, so confirmations now hold through fetch failures; a genuinely unavailable close (no spot tick and no usable history) still lands error. Off-hours behavior with a live tick is unchanged: official close, status ok.
• Market-data subscribe errors in the daemon's snapshot helpers are now logged with the symbol instead of silently discarded, so gateway farm blips and silent subscribe timeouts are distinguishable in the daemon log.