Open source · Go

Canary

Portfolio, risk and order tools for Interactive Brokers.

Canary connects to your broker, reads your book and the market, checks your risk rules every minute and drafts the protection they call for. Your shell, AI assistant and phone all read the same figures.

Latest release and release notes →

Read-only MCP tools · Signed releases · No telemetry · MIT licence

Canary CLI is the broker engine. Canary Desk adds the schedule, the AI analyst and the console on top. Works with Interactive Brokers through IB Gateway or TWS.

Output of canary brief on a synthetic account: market state, portfolio summary and what needs attention
canary brief, the morning read.Synthetic account

Your book, with its evidence

Positions, exposure and reconciliation against broker statements. Stale or missing data stays labelled, never filled in.

The market around it

Regime, breadth, stress, calendars and market events, each with its source and its age.

Rules that draft protection

A rulebook checks the book every minute. When a rule trips, Canary drafts the stop, exit or budget cut it calls for.

Orders within your limits

The opt-in trading edition sends the orders you confirm or pre-authorise by rule, and shrinks or cancels its own stops when you hold fewer shares. Standard downloads are read-only.

Get started

Install Canary

Run IB Gateway 10.37+ or TWS on the same machine. You need an IBKR Pro account with TWS API access; IBKR Lite does not include it.

Every release ships signed checksums, and the installer checks them against a pinned key. Canary sends no telemetry.

Claude Desktop install
The command line, Cursor, Continue, Zed and other MCP hosts
curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary status    # which gateway and account it reached
canary brief     # what needs attention today

# Claude Desktop
canary setup claude-desktop

# Claude Code plugin
/plugin marketplace add osauer/canary
/plugin install canary@canary

# then ask:
# "How does my IBKR account look today?"

Before you start

Common questions

Which brokers does Canary support?

Canary works with Interactive Brokers through a local TWS or IB Gateway session. Market data depends on your IBKR subscriptions.

Can Canary submit orders?

Yes, through the optional trading build and its approval checks. Standard downloads and all MCP tools are read-only. See the order guide.

Does Canary work with TWS and IB Gateway 10.50?

Version 3.21.0 includes 10.50 compatibility fixes. Live checks passed on TWS; Gateway 10.50 still needs end-to-end validation. See the compatibility details.

Build on it

Your agent,
on your book.

A broker API hands an agent raw prices and an order ticket. Canary adds the source and age of each figure and holds every order to your rules. Connect Claude Code with two commands, or build your own agent. Canary Desk is built on it, with agents for briefs and analysis.

MIT-licensed, with every line on GitHub. There is no sign-up and no telemetry.

The read-only boundary

Evidence

Missing
stays missing.

A figure Canary cannot confirm is never shown as clean. Sources, age and coverage stay beside the figures, so you and your assistant know what to trust.

Fresh
A current reading, with its source and time.
Delayed
An older reading, clearly labelled.
Incomplete
The available evidence and its gaps, side by side.
Unavailable
No invented zero. Decisions that need it wait.
See the command-line viewsPositions and risk rules, on synthetic accounts

From the command line

What you
read each day.

Each figure names its source and its age. Every command also speaks JSON, for your scripts.

Output of canary positions on a synthetic account: holdings with value, day change and exposure
canary positionsSynthetic account
Output of canary rules on a synthetic account: each risk rule with its reading, band and state
canary rulesSynthetic account

Canary Edge

What your trades
delivered.

Edge compares every open, add, trim and exit with leaving the position alone over 1, 5 and 20 sessions. It works from broker records.

It reports what happened. It does not forecast or recommend.

Check that your limits add upEvery limit in force, and order limits that follow the account · v3.18

Policy check

Limits that fit
the account.

Canary acts on numbers you set, from rule thresholds to order sizes and cash reserves. It now prints every one in force with its source and meaning, and reads them against each other and against your account. Each value that does not fit gets a reason and, where one applies, a suggested fix.

Order limits follow the account. The cap on a single order’s value moves with the account’s worth (its net liquidation value), between a floor and a ceiling you set. A temporary larger cap takes one override, which Canary records in its journal.

In trading builds, a protective stop is no longer refused by that cap or by the short-sale check, as long as it sells no more than the stock or ETF you hold, counting your other working sell orders. When you hold fewer shares than one of Canary’s own stops would sell, Canary shrinks or cancels that stop on its own.

The check only reads; you change a limit by editing your files. Stops you placed by hand are never changed, and standard downloads stay read-only.

How the policy check works
  1. 01 · ShowEvery limit in force

    canary policy show --explain lists each limit, policy and setting with its value, unit and source. Add a section name to print one part.

  2. 02 · CheckWhat does not add up

    canary policy check reads your config, policy files and account against each other, explains each implausible value and suggests a fix where one applies.

  3. 03 · AskThe same report for your assistant

    canary_policy_check gives MCP clients the same check. It reads and cannot change a limit.

Watch your listVolume turns, the exact call’s quote and entry timing · v3.17

Watchlist and setups

Twenty names,
read bar by bar.

Keep up to 20 US stocks on one watchlist. Canary compares each completed five-minute bar with comparable earlier sessions and reports when unusual volume is followed by a price that holds or rises.

For a setup you want to pursue, it lists the standard calls and reads one dated quote for the exact call you choose. After a fill Canary placed, it checks the entry against later quotes at two points.

Setups are observations, not validated signals. Markouts leave out commissions and never replace account P&L. Watchlist edits change local preferences only, and there are no MCP setup tools.

  1. 01 · WatchOne list you own

    canary watchlist add NVDA keeps a durable list of up to 20 names. Nothing else changes.

  2. 02 · ObserveWhat was watched

    canary setups coverage shows each session’s completed bars, evaluation states and missing data.

  3. 03 · ReviewHow the entry held up

    canary setups markouts reads the later quotes, and says why any checkpoint was missed.

Research borrowing and short interestDated fees, liquidity and FINRA reports · v3.17

Borrowing research

The cost of borrowing,
with its date.

Compare borrowing fees, price and liquidity for the stocks you name. Screen IBKR’s US borrowing feed for names that stay expensive, and rank FINRA’s reported short positions by size and days to cover.

Your assistant reads the same results through read-only MCP tools. Filters apply before the result limit, and each row keeps its source date.

Borrowing fees are a cost to borrowers, not a lender’s yield. Short interest comes from a twice-monthly report and does not track live positions. Percentage of free float is not available.

  1. 01 · NameYour stocks first

    canary lending rates and canary lending market for the symbols you list.

  2. 02 · ScreenBeyond your book

    canary lending screen finds borrowing that stays expensive across source dates.

  3. 03 · ReportReported short interest

    canary short-interest screen with listed-only, price, liquidity and days-to-cover filters.

Plan surplus cashA reserve that follows the account, and no bill buys while you borrow · v3.18

Cash sweep

Idle cash,
under your rules.

Canary plans short-dated government bills for surplus cash in the currency you hold. It keeps commitments and a cash reserve ahead of new purchases, and the reserve now follows the account’s net liquidation value and planned needs.

Before any purchase, the plan shows the bill’s order minimum, the fee bounds and the estimated gain after spread, fees and the cash interest you give up. Each purchase stays between a minimum and a maximum size, so none is too small to earn back its commission. You choose which currency comes first.

Desk shows the plan; Canary checks the cash, bill, price, fees and authority. Each order needs your confirmation or an explicitly pre-authorised sweep with limits and a veto window.

Off by default. Commissioning needs a calibrated policy and current settlement evidence. Bills can lose value if sold before maturity.

Read the sweep controls
  1. 01 · EvidenceWhat cash is usable?

    Settled cash per currency, current enough to include confirmed trades, after commitments and reserves. While any currency is borrowed, bill buys wait, since a bill would earn less than the margin interest on that loan.

  2. 02 · ReviewWhich bill, and is it worth it?

    A same-currency bill and its maturity. The broker previews price and fees, and the plan shows the net gain over holding cash.

  3. 03 · AuthorityWithin your policy

    Confirm the order or use the scoped authority you have granted. Missing evidence holds it.

Understand currency effectsStatement-backed attribution · v3.16.0

Statement-backed FX

Count the
currency effect.

FX contribution measures how currency moves affect your P&L in the account’s base currency. It covers the day, week, month and year to date, from completed broker statements.

FX contributionCurrency effectOther P&LPrices, income and feesPortfolio changeAfter external cash flows

Available in Canary v3.16.0 and in Desk’s private runtime. canary reporting fx --json and canary_reporting_fx return the same result. Missing days stay visible, and an incomplete period shows no total. This is valuation attribution, kept apart from realised Forex lot P&L.

How FX is measured
Read lending incomeDated loans and earned fees · v3.16.0

Lending observations

Your shares on loan.
The fees they earned.

Canary reads managed stock loans and customer net fees from retained IBKR statements. Positions on loan carry a dated annotation, and the fee history expands when you need it.

canary lending fees --json and canary_lending_fees return the same bounded, read-only history. Missing sections, partial periods and a complete record of zero earnings stay distinct.

Available in Canary v3.16.0. Fees stay separate from account P&L, and their link to payouts and P&L is not yet proved. Commissioning an account still needs a populated report.

How lending is reported
Lending, with the evidence attached A broker statement supplies dated shares-on-loan records and a net-fee ledger. Lending income is shown separately, without adding it again to broker profit and loss. This is a reporting diagram, not account data. LENDING / BROKER EVIDENCE The record behind the income. IBKR statement Reporting date + coverage SHARES ON LOAN The dated position Quantity · collateral · broker date NET FEE HISTORY The earned-fee ledger Value date · currency · signed net fee Visible income. Kept apart from broker P&L. REPORTING ONLY Participation stays with IBKR Lending, with the evidence attached A broker statement supplies dated shares-on-loan records and a net-fee ledger. Lending income is shown separately, without adding it again to broker profit and loss. This is a reporting diagram, not account data. LENDING / BROKER EVIDENCE The record behind the income. IBKR statement Reporting date + coverage SHARES ON LOAN The dated position Quantity · collateral · broker date NET FEE HISTORY The earned-fee ledger Value date · currency · signed net fee Visible income. Kept apart from broker P&L. Reporting only · Participation stays with IBKR

Architecture

One daemon,
four ways in.

The daemon holds the broker connection, the evidence, your rules and the order journal. Everything else is an adapter over the same typed results.

It starts when asked and stops after 15 idle minutes. Status stays responsive while the broker is slow, and after canary stop it stays down until you restart it.

Browse the full feature setMarket context, reporting, rules and integrations

Full features

What’s inside.

Market context

  • Market regimeEight readings in six groups, read into one stage: VIX term structure and VVIX, breadth, credit spreads, funding, the yen and dealer gamma computed from SPX options.
  • BreadthS&P 500 names above their 50- and 200-day averages, computed from constituent prices.
  • Stress signalAn early warning when the regime turns.
  • Market eventsReg SHO threshold lists, Nasdaq halts, borrow availability and borrow fees.
  • Borrowing research · v3.17Dated borrowing fees with price and liquidity, a wider US screen and FINRA short interest.
  • CalendarsUS stocks and options, Xetra, London, Tokyo and Hong Kong, plus official economic releases.

Your book

  • Positions and exposureStocks, options and bonds, with sector allocation.
  • Watchlist and setups · v3.17Up to 20 names, read bar by bar for volume turns, with a dated quote for the exact call you choose.
  • Entry markouts · v3.17Later quotes for fills Canary placed. Missed checkpoints stay missing; commissions and P&L stay separate.
  • PerformanceA statement-based return series, net of cash flows.
  • FX contribution · v3.16Day, WTD, MTD and YTD currency contribution, reconciled to daily statements.
  • Lending observations · v3.16Dated shares on loan and earned customer net fees, with bounded history and explicit coverage.
  • EdgeWhat your trades delivered compared with leaving the position alone.
  • ReconciliationFigures checked against broker statements. Gaps stay visible.

Rules and protection

  • Risk rulebookYour limits, checked every minute.
  • Policy check · v3.18Every limit in force with its source and meaning, and a check that names each value that does not add up.
  • Protection proposalsStops, exits, trims and budget cuts, each with its reason.
  • Cash sweepSame-currency bills for surplus cash, with a reserve that follows the account, your currency order and a reason for every plan.
  • Sweep economicsOrder minimums and maximums, fee bounds and the net gain after spread, fees and forgone cash interest, before any purchase. No bill buys while any currency is borrowed.
  • Settlement evidenceUsable cash needs current per-currency evidence. An optional authenticated broker ledger can supplement TWS; gaps hold the sweep.
  • Order limits · v3.18A cap on each order’s value that follows net liquidation value, between a floor and a ceiling you set.
  • Protective stops · v3.18In trading builds, Canary shrinks or cancels its own stops when you hold fewer shares than they would sell. Stops you placed by hand are never changed.
  • Trading editionOpt-in order execution, with your confirmation or pre-authorised rules and Canary’s checks.

Where you use it

  • Command lineOne binary for macOS and Linux. Every command speaks JSON.
  • AI assistantsRead-only MCP tools for Claude and other hosts.
  • Your phoneA paired app with live updates and opt-in notifications.
  • Go libraryThe TWS protocol, spoken natively in Go, with no vendor SDK.
Use the Go libraryNative protocol access and a code example

Go library

The protocol,
in plain Go.

pkg/ibkr speaks the TWS wire protocol itself. It needs no vendor SDK and redistributes no Interactive Brokers code.

To read a running Canary from your own program, import the module root. canarytest serves it on a temporary socket for your tests.

Go API reference
An account summary, straight from the wire
cfg := ibkr.DefaultConfig()
cfg.Port = 4002 // Gateway, paper account

conn := ibkr.NewConnector(&ibkr.ConnectorConfig{
    PreferredClientID: 17,
    BaseConfig:        cfg,
})
if err := conn.Start(ctx); err != nil {
    return err
}
defer conn.Stop()

summary, err := conn.RequestAccountSummary(ctx, 5*time.Second)
if err != nil {
    return err
}
fmt.Println(summary.AccountID)

Documentation

Handbook & reference

Open the handbook

Canary Desk is the private workspace built on this engine. See Canary Desk.