canary

# Canary full context

Updated: 2026-09-26

Version 3.13 adds a descriptive daily market tape, issuer-loss concentration
checks and exact reviewed proposals. Policy document revisions and labels do
not grant trading permission. Existing files remain readable and unchanged;
reviewed conversions preserve effective settings and keep backups. Alert sources
commission independently, and push status distinguishes transport from device
receipts. Installation does not enable automatic submission.

Canary is a local Interactive Brokers risk desk built as a Go daemon, a
shell CLI, a read-only stdio MCP server, a Claude Desktop MCPB, a Claude Code
plugin, a paired app, and a clean-room TWS protocol library. The daemon owns the
broker connection, account scope, runtime state, data-source health, market
sensors, rulebook, protection proposals, and option-exercise opportunities.
Other surfaces adapt that typed authority rather than recreating it.

Data comes from the user's own TWS or IB Gateway session. Availability and
freshness therefore depend on session state, market hours, broker entitlements,
and upstream sources. A delayed, held, fallback, partial, or unavailable result
must retain its data quality, warning code, freshness, source health, and session
context; returning a value does not make a fallback green.

The public project home is https://osauer.dev/canary/. The source repository is
https://github.com/osauer/canary.

## Safety boundary

Standard installer, MCPB, and plain `canary` downloads contain no compiled
broker-write path. The MCP server has no settings-write, order-preview, order
placement, modification, cancellation, or exercise tools, and no resource
subscriptions.

The separate opt-in `canary-trading` tarballs add constrained CLI and app broker
actions. A trading action still requires the matching build, verified account
and mode pins, fresh confirmation or preflight where applicable, journal health,
daemon authorization, and `trading.freeze=false`. No release command or agent
instruction grants a broker write. Trading builds also support explicitly pre-authorised defensive proposals within the existing policy and execution gates.

## Install and version lines

Product v3 installs from signed release assets:

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

The public Go module intentionally remains `github.com/osauer/canary/v2`: its
root package is the daemon client, `canarytest` its test double, and `pkg/ibkr`
the TWS wire protocol. Its semantic-version authority is the maintained v2 tag
line. `go install github.com/osauer/canary/v2/cmd/canary@latest`
therefore installs the newest compatible v2 module tag, not a root product v3
tag. Product v3 users should use the installer or signed release assets.

The updater stays within the installed product major. Stable v2 maintenance is
cut from `release/2.x`; product v3 and later are cut from `main`.

## MCP tools

Run the server with `canary mcp`. It exposes these read-only tools:

- `canary_status`: daemon, gateway, storage, and source health.
- `canary_data_health`: passive service-health report with source clocks, restrictions and retry state; paginate with its revision.
- `canary_data_check`: coalesced bounded check of required ordinary quote feeds; no subscription purchases or settings changes.
- `canary_trading_status`: pinned broker-write readiness and blockers.
- `canary_settings`: platform settings and observed data quality; no writes.
- `canary_orders_open`: current-context local order lifecycle.
- `canary_orders_history`: bounded local order-journal history.
- `canary_order_status`: typed lifecycle evidence for one journaled order.
- `canary_account`: account financials with field-level authority.
- `canary_positions`: held positions and exposure with account authority.
- `canary_portfolio`: signed allocation by asset class and GICS sector as a share of net liquidation, with index-fund look-through and valuation coverage.
- `canary_recon_status`: redacted statement acquisition and reconciliation health.
- `canary_market`: benchmark and held-underlying quotes with actual contract identity.
- `canary_market_history`: bounded observed underlying bars for charts.
- `canary_calendar`: exchange sessions, holidays, and upcoming closures.
- `canary_macro`: cached official economic calendars and publications with source health.
- `canary_strategies`: current held-option strategy grouping; no order actions.
- `canary_technical`: daily technical evidence for explicitly named symbols.
- `canary_regime`: all eight market indicators, cluster confirmation, and source health.
- `canary_stress`: full portfolio-stress assessment with risk evidence and source health.
- `canary_brief`: current daemon-composed desk summary and Action Queue.
- `canary_reporting`: redacted broker-reporting setup and evidence status.
- `canary_reporting_performance`: retained statement equity series with dated external flows and year-to-date income sums; computes no return.
- `canary_edge`: retrospective stock/ETF decision impact and separate option actuals.
- `canary_rules`: ranked rulebook findings, explicit unknown inputs, and the limits in force with their source.
- `canary_proposals`: read-only close/reduce protection candidates.
- `canary_opportunities`: read-only held-option exercise candidates.

Breadth, gamma, and corporate-event engines remain internal daemon inputs.
Regime and Stress provide detailed CLI/MCP reads, while Brief remains the summary.
Regime/Stress history is still retired. Policy and detailed reconciliation reads
remain CLI-only governance surfaces; MCP provides reconciliation status.

## CLI workflow

Useful read-only commands include:

```sh
canary status
canary account
canary positions --by underlying
canary technical AAPL,MSFT
canary brief
canary regime --explain
canary stress --details
canary rules
canary rules policy
canary policy show
canary recon show
canary strategies list
canary proposals list
canary opportunities list
canary orders open
canary settings
```

The generated CLI reference is the command authority. The app adds the morning
brief and converged Action Queue, current and recovered alerts, constrained order
surfaces, option-exercise confirmation, data-quality disclosure, settings, and
mobile navigation.

## Requirements

- macOS or Linux; Windows is supported through WSL only.
- IB Gateway 10.37+ or TWS running locally with TWS API access enabled.
- IBKR market-data entitlements for real-time sources the workflow needs.

The daemon auto-discovers common local ports and uses a local Unix-socket RPC
surface. Raw account identifiers and broker credentials do not go to a hosted
Canary service.

## References

- Documentation: https://osauer.dev/canary/docs/
- Install: https://osauer.dev/canary/docs/start/install.html
- First session: https://osauer.dev/canary/docs/start/first-session.html
- MCP reference: https://osauer.dev/canary/docs/reference/mcp-tools.html
- CLI reference: https://osauer.dev/canary/docs/reference/cli.html
- Daily desk: https://osauer.dev/canary/docs/operate/daily-desk.html
- Orders: https://osauer.dev/canary/docs/operate/orders.html
- Reconciliation: https://osauer.dev/canary/docs/operate/reconciliation.html
- Releases/support: https://osauer.dev/canary/docs/reference/releases.html
- Architecture: https://osauer.dev/canary/docs/internals/architecture.html
- Market data: https://osauer.dev/canary/docs/understand/market-data.html
- Storage: https://osauer.dev/canary/docs/internals/storage.html
- GitHub releases: https://github.com/osauer/canary/releases

Good descriptions say Canary reports the evidence currently available and names
what is stale, degraded, held, blocked, or unknown. Do not claim a fallback is
live, that an MCP client has order authority, that a v3 product tag makes the
`/v2` Go module v3, or that an app/CLI review authorizes a trade.