v3.9.0

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

Canary 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 v3.9.0

• Read Canary from your own Go program. The module root package github.com/osauer/canary/v2 runs the same read-only tool catalogue as canary mcp over the daemon socket, one connection per call and under the same per-tool budgets, so results and redaction match the MCP server exactly. canarytest serves the wire types on a temporary socket for tests. The daemon keeps every policy and broker gate.
• Statement performance series. canary reporting performance, the reporting.performance method and the canary_reporting_performance tool return the retained statement closes in the base currency, dated external flows (deposits, withdrawals, position transfers) and year-to-date sums of realised P&L, commissions, dividends, interest, withholding tax and fees, so a consumer can compute cash-flow-adjusted returns itself. No return is computed, a missing report date stays a gap, and the envelope names no account.
• Sector allocation under GICS with fund look-through. portfolio.snapshot classifies S&P 500 names by their GICS sector and other stocks by the broker's industry, and spreads SPY, QQQ and IWM over a dated sector-weight table whose as-of date travels in look_through. Both tables are signed market value over net liquidation, so they add up with cash. Holdings the broker no longer quotes and zero-mark rows awaiting a verdict are counted in defunct_excluded and unquoted_excluded rather than drawn. Classification is remembered per broker session and no longer stops at twelve names.
• Option hedges are listed beside the proposals. The proposal snapshot carries option_hedges: one record per held long option the exit engine holds as protection, with what it covers, the Rulebook's role and how that role was established, days to expiry, cost basis per contract unit, mark and market value. A hedge is a standing fact, so the record carries no threshold, premium return or order terms, and counts.option_hedges is separate from the proposal counts. A hedge's detail sentence now says that the whole-book check is Canary's own work and asks nothing of the owner.

Claude Desktop MCPB

Download the canonical canary.mcpb asset from the Assets section below or from:

https://github.com/osauer/canary/releases/latest/download/canary.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 read-only local server 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/canary/main/install.sh | sh
canary setup claude-desktop

The first command picks the right binary for your platform, verifies its signed SHA-256 inventory, installs it to ~/.local/bin/canary, adds the directory to your PATH if needed, and clears the Gatekeeper quarantine flag on macOS. The second command writes the 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:

canary account
canary technical AAPL
canary 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 (canary-trading-* tarballs)

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

The canary-trading-v3.9.0-* tarballs are different: that binary can place, modify, cancel, or exercise constrained orders with your broker once you configure the trading gates and satisfy the action's fresh preview or preflight contract. Only download it if you intend to trade through Canary. Before enabling anything, read SECURITY.md and the trading guide, start against a paper account, and verify with canary trading status. Release publication is hermetic and performs no broker preview or write; wire behavior is verified separately with the read-only smoke targets.

---

Paranoid? Inspect the installer before running it

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

Doing something custom?

• Go module and source-built CLI: product v3 and later ship through the signed installer and release assets above. The public Go module remains on its maintained v2 line; go install github.com/osauer/canary/v2/cmd/canary@latest installs the newest v2 release, not this product release.
• Different install dir: CANARY_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/canary then /plugin install canary@canary inside any session.

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

---

Changed

• A single-name long put follows the same rule as a long call. It is protection when it covers a long stock of its own underlying, otherwise directional. Before, its purpose stayed unconfirmed and the missing quote surfaced as blockers the owner could never clear; a leg no standing rule covers now gets no quote request and reports no quote blocker. Hedge-listed puts under the protection default are unchanged.
• Discovery tries a logged-out listener last. When IB Gateway and TWS both answer, the port that accepted a connection but never completed the handshake is tried last on the next cycle, the daemon warns once naming the port it tries first, and every failover is logged at WARN. Before, a logged-out Gateway on 4001 was tried before TWS on every cycle for the full handshake budget. Pinned ports and a sole listener are never reordered.
• The broker's "no security definition" answer is remembered. The connector, a quote's closed-market context, the allocation tables and the breadth sweep each keep the verdict for as long as it can stay true, and canary restart clears them all. Before, a delisted holding was asked about on every snapshot and the log repeated the same refusal every few minutes.
• Broker-write authority is unchanged. Hedge records and allocation tables place no order. Portfolio protection, fresh exact-contract evidence, and transaction-specific human authority remain binding.

Fixed

• Closed-market quote context no longer exhausts the history allowance. The daily bars behind a quote's close, ranges and volume are read once per contract and kept until the market's next close, so other history reads stop waiting or timing out behind them.
• Remembered chart series grow again. A refresh now reads on the background lane and waits for its turn instead of timing out behind the interactive deadline, so a long series asked for by Desk fills in past its first window.
• CME futures charts stand over the weekend. A futures series read after Friday's close is not refreshed until Sunday evening New York time, and a venue without a calendar serves its last traded day on a one-day range instead of an error.
• Quieter logs. A socket the daemon closed itself is no longer logged as a read error, and a market-data request by contract description is no longer reported as a protocol misalignment.