Canary

A local risk desk for your brokerage account.

It runs with Interactive Brokers today, through IB Gateway or TWS, and keeps the broker layer in its own Go package, pkg/ibkr, so other brokers can follow.

Canary turns one local IB Gateway or TWS session into a daily brief, current portfolio and market evidence, and a broker-confirmed review of what past position changes delivered. Use the same daemon from an MCP host, the shell, or a paired phone. The standard binary cannot place, change or cancel an order; it can preview one, which asks the gateway for a what-if check and creates no order. No MCP tool can preview or execute an order in any build.

Canary is for an IBKR Pro user who runs Gateway or TWS locally and wants stale, missing, or held evidence to remain visible. It is not a hosted brokerage service, a trade recommender, or a complete TWS API replacement. If you only need a Go wire-protocol client, use pkg/ibkr. To read a running Canary from your own Go program, import the module root github.com/osauer/canary/v2: it runs the same read-only tool catalogue over the daemon socket, and canarytest serves the wire types on a temporary socket for tests. The client also exposes a narrow audited cash-sweep ordering preference; its tool catalogue remains read-only and the preference cannot activate reserves or broker execution.

Documentation · Install · First session · Canary Edge · MCP tools · Safety · Privacy

Start

You need IB Gateway 10.37+ or TWS with API socket access enabled, an IBKR Pro account, and macOS or Linux on arm64 or amd64. WSL works; native Windows does not.

For one binary shared by the shell and local MCP hosts:

curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary status    # prove which gateway and account Canary reached
canary brief     # review what changed and what needs attention

The installer verifies the signed release checksum and installs to ~/.local/bin. The install guide shows how to inspect the script first and covers every other installation path. Canary can discover Gateway or TWS automatically; canary status identifies the selected connection and account. An explicit endpoint pin remains fixed. Market-data availability depends on your IBKR subscriptions: delayed values stay labeled and cannot satisfy live-only execution requirements.

For Claude Desktop only, download canary.mcpb, open it with Claude Desktop, then quit Claude completely and relaunch it. Ask:

What needs attention today, and which inputs are degraded?

The bundle carries its own macOS and Linux binaries. The Claude Desktop walkthrough covers the first connection.

Current Canary SPA rendered from synthetic data. Edge reports observed historical outcomes; it is not a forecast or a causal claim.

Reduction plans compare both index directions, loss room and quoted trading costs. An index-hedge plan sizes whole Micro E-mini contracts; a plan does not submit an order. Protection and reduction planning explains the figures and their limits.

Choose your surface

| You want to… | Start with | Boundary | | --- | --- | --- | | Ask an agent about the account | The MCP Bundle, or canary mcp from any local framework that can launch a stdio MCP server | Read-only tools; no settings writes, previews, or execution tools | | Work in a terminal or script | canary brief, canary positions --by underlying, and --json | Deterministic CLI output over the same daemon authority | | Check the desk from a phone | canary app, then canary app pair | Paired PWA; local by default, optional remote relay | | Read Canary from your own Go program | github.com/osauer/canary/v2, the daemon client, with canarytest for tests | The MCP tool catalogue over the daemon socket without an MCP process; the daemon keeps every policy and broker gate | | Build directly on the TWS protocol | github.com/osauer/canary/v2/pkg/ibkr | Lower-level transport; your application owns policy, authorization, and journaling |

Constrained broker actions are not a fifth onboarding path. They require a separate experimental trading binary and remain limited to gated CLI and paired-app flows. MCP stays read-only in every build. Read Gated orders and the trading build before using that artifact.

What Canary helps you answer

• What needs attention now? canary brief, the Rulebook, and the Action Queue combine current alerts, process exceptions, protection candidates, and exercise candidates without turning any row into submit authority.
• Am I within my limits? canary rules checks the book against limits for position size, premium budget, time value, expiry, losses, net market exposure and margin headroom. They start from a compiled baseline; canary rules policy set makes them yours.
• How is the book exposed? Account and position reads identify one selected account, group stock and option legs by underlying, and keep missing values separate from real zeros. Each position carries the listing venue IBKR reports. Multi-account ambiguity is refused rather than blended.
• What did past decisions actually deliver? Canary Edge uses retained IBKR Flex records and exact-contract market history. It reviews account P/L after confirmed external flows, compares adequately repeated stock and ETF opens/adds/trims/exits with leaving the prior position unchanged over 1, 5, and 20 sessions, and reports broker-recorded option P/L separately. It does not infer intent, recommend a trade, or claim causation.
• What did stock lending earn? Dated shares-lent annotations and canary lending fees --json provide customer net fees, expandable history and explicit report coverage. IBKR controls participation. Fees explain income; they are never added again to broker account P/L. Payment linkage remains unproved. See lending reporting.
• What high-fee names are outside my list? canary lending screen --min-rate 50 --limit 25 --json and MCP canary_lending_screen rank the existing IBKR US USD bulk feed. Optional exclusions remove familiar names; coverage, source dates and truncation stay explicit. This does not establish listing quality, liquidity or lender yield.
• Which US equities have large reported short positions? canary short-interest screen --listed-only --min-average-volume 1000000 --json ranks FINRA short shares before limiting results. Sort by days_to_cover or add the shared price/liquidity filters; market coverage is explicit and free-float percentage remains unavailable. See source and freshness semantics.
• Where are borrowing fees unusually high? canary lending rates --symbols AAA,BBB --json and MCP canary_lending_rates read dated indicative borrower costs for an explicit US-stock universe. Preserve missing data, source age and numeric scale. These rates are research inputs, not your lending yield or a buy recommendation. See lending research.
• How much did exchange rates contribute? canary reporting fx --json reads completed daily valuation effects across investments, currency cash and accrued interest, with missing days retained. This differs from realised currency-lot P/L in IBKR's Forex P/L Details. See FX reporting.
• Can this reading be trusted? Quotes, calendars, breadth, gamma, regime, stress, earnings, borrow, halt, and reporting sources carry their own health, freshness, coverage, and last-good state. Unavailable evidence stays unavailable. canary data health --json reads the service report; canary data check --json requests a bounded ordinary-quote check. A healthy service does not mean every quote is live or suitable for execution.
• When is the market open, and what is scheduled? Exchange calendars cover US equities and listed options, Xetra, London, Tokyo and Hong Kong, with explicit coverage bounds and intraday breaks. canary macro separately reads cached official economic calendars and publications with their source health.
• Can I review an addition before placing it? canary add plan checks a stock addition; canary add preview reviews exact terms, including an optional stop for the added shares. canary add market discovers calls and canary add call-plan sizes an exact call against a budget. These commands place no order. See the Add command guide for request examples and the separate confirmation boundary.
• How can I reduce exposure while keeping chosen holdings? canary locks keeps every held contract of a chosen name out of bulk and automatic reductions, including contracts acquired after a roll. Portfolio reductions can target net exposure, long positions, sectors or higher-beta holdings. --plan shows a proposed reduction without creating anything that can be submitted. A direct single-holding reduction can still target a locked line. See reductions and holding locks.
• How would option exit rules have changed past trades? canary edge replay compares historical exit rules using statement trades and dated market evidence. Missing history and reconciliation limits remain explicit; this is a historical simulation, not a forecast or a live trading instruction. See the Edge guide.
• What work already exists? Proposals, opportunities, and the local order journal show what is blocked or ready for human review and how it changed. They are evidence, not broker authority. A multi-leg option position is reviewed as one unit, net premium paid against net close value at fresh leg quotes, and routed to the strategy workflow or a broker combo; the row places no order. Option purpose follows the measured book, not per-leg declarations. An opt-in cash sweep proposes putting idle cash into bills of the same currency; it never converts one currency into another.

Reconciliation, statement-derived equity, and Edge require one shared IBKR Activity Flex Query. Run canary setup reporting, then follow the screenshot-driven field checklist. A received empty section counts as zero reported activity and does not block readiness. Missing sections and missing required fields on populated rows remain distinct problems; canary reporting status --json shows the current evidence.

MCP and agent frameworks

The MCP Bundle is the shortest Claude Desktop path. For another local host, install the shared binary and point the host at its absolute path. Hosts that use the common mcpServers shape accept:

{
  "mcpServers": {
    "canary": {
      "command": "/ABSOLUTE/PATH/TO/canary",
      "args": ["mcp"]
    }
  }
}

Use `which canary