{
  "markdown": "# Canary\n\n[![ci](https://github.com/osauer/canary/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/osauer/canary/actions/workflows/ci.yml)\n[![release](https://img.shields.io/github/v/release/osauer/canary?display_name=tag&sort=semver)](https://github.com/osauer/canary/releases/latest)\n[![license](https://img.shields.io/github/license/osauer/canary)](LICENSE)\n\n**A local risk desk for your Interactive Brokers account.**\n\nCanary turns one local IB Gateway or TWS session into a daily brief, current\nportfolio and market evidence, and a broker-confirmed review of what past\nposition changes delivered. Use the same daemon from an MCP host, the shell,\nor a paired phone. The standard binary and every MCP tool are structurally\nread-only: they contain no broker-order preview or execution surface.\n\nCanary is for an IBKR Pro user who runs Gateway or TWS locally and wants stale,\nmissing, or held evidence to remain visible. It is not a hosted brokerage\nservice, a trade recommender, or a complete TWS API replacement. If you only\nneed a Go wire-protocol client, use [`pkg/ibkr`](#go-wire-protocol-library).\n\n**[Documentation](https://osauer.dev/canary/docs/)** · [Install](docs/docs/start/install.md) · [First session](docs/docs/start/first-session.md) · [Canary Edge](docs/docs/understand/edge.md) · [MCP tools](docs/docs/reference/mcp-tools.md) · [Safety](SECURITY.md) · [Privacy](PRIVACY.md)\n\n## Start\n\nYou need IB Gateway 10.37+ or TWS with API socket access enabled, an IBKR Pro\naccount, and macOS or Linux on arm64 or amd64. WSL works; native Windows does\nnot.\n\nFor one binary shared by the shell and local MCP hosts:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh\ncanary status    # prove which gateway and account Canary reached\ncanary brief     # review what changed and what needs attention\n```\n\nThe installer verifies the signed release checksum and installs to\n`~/.local/bin`. The [install guide](docs/docs/start/install.md) shows how to\ninspect the script first and covers every other installation path.\n\nFor Claude Desktop only, download\n[`canary.mcpb`](https://github.com/osauer/canary/releases/latest/download/canary.mcpb),\nopen it with Claude Desktop, then quit Claude completely and relaunch it. Ask:\n\n> What needs attention today, and which inputs are degraded?\n\nThe bundle carries its own macOS and Linux binaries. The\n[Claude Desktop walkthrough](https://osauer.dev/canary/claude-desktop-interactive-brokers/)\ncovers the first connection.\n\n![Canary Edge showing a synthetic one-year decision review, 1/5/20-session matrix, and ranked findings](docs/social/canary-app-edge.png)\n\n_Current Canary SPA rendered from synthetic data. Edge reports observed\nhistorical outcomes; it is not a forecast or a causal claim._\n\n## Choose your surface\n\n| You want to… | Start with | Boundary |\n| --- | --- | --- |\n| 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 |\n| Work in a terminal or script | `canary brief`, `canary positions --by underlying`, and `--json` | Deterministic CLI output over the same daemon authority |\n| Check the desk from a phone | `canary app`, then `canary app pair` | Paired PWA; local by default, optional remote relay |\n| Build directly on the TWS protocol | `github.com/osauer/canary/v2/pkg/ibkr` | Lower-level transport; your application owns policy, authorization, and journaling |\n\nConstrained broker actions are not a fifth onboarding path. They require a\nseparate experimental trading binary and remain limited to gated CLI and\npaired-app flows. MCP stays read-only in every build. Read\n[Gated orders and the trading build](docs/docs/operate/orders.md) before using\nthat artifact.\n\n## What Canary helps you answer\n\n- **What needs attention now?** `canary brief`, the Rulebook, and the Action\n  Queue combine current alerts, process exceptions, protection candidates,\n  and exercise candidates without turning any row into submit authority.\n- **How is the book exposed?** Account and position reads identify one selected\n  account, group stock and option legs by underlying, and keep missing values\n  separate from real zeros. Multi-account ambiguity is refused rather than\n  blended.\n- **What did past decisions actually deliver?** Canary Edge uses retained IBKR\n  Flex records and exact-contract market history. It reviews account P/L after\n  confirmed external flows, compares adequately repeated stock and ETF\n  opens/adds/trims/exits with leaving the prior position unchanged over 1, 5,\n  and 20 sessions, and reports broker-recorded option P/L separately. It does\n  not infer intent, recommend a trade, or claim causation.\n- **Can this reading be trusted?** Quotes, calendars, breadth, gamma, regime,\n  stress, earnings, borrow, halt, and reporting sources carry their own health,\n  freshness, coverage, and last-good state. Unavailable evidence stays\n  unavailable.\n- **What work already exists?** Proposals, opportunities, and the local order\n  journal show what is blocked or ready for human review and how it changed.\n  They are evidence, not broker authority.\n\nReconciliation, statement-derived equity, and Edge require one shared IBKR\nActivity Flex Query. Run `canary setup reporting`, then follow the\n[screenshot-driven field checklist](docs/docs/start/reporting.md).\n\n## MCP and agent frameworks\n\nThe MCP Bundle is the shortest Claude Desktop path. For another local host,\ninstall the shared binary and point the host at its absolute path. Hosts that\nuse the common `mcpServers` shape accept:\n\n```json\n{\n  \"mcpServers\": {\n    \"canary\": {\n      \"command\": \"/ABSOLUTE/PATH/TO/canary\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nUse `which canary` to find the path. A browser-only agent cannot reach this\nlocal stdio process. After upgrading, fully relaunch the host so it respawns\nthe MCP server.\n\nContinuously running agents can keep this MCP child process available and\nreuse Canary's brief, calendar, regime, risk, and order evidence. Use\n`canary_calendar` for official exchange sessions and coverage bounds; it is not\nan economic-release calendar. The host owns durable wakeups, model budgets,\nand process recovery. Canary owns the observations and risk semantics. See\n[continuous hosts](docs/docs/start/hosts.md#continuously-running-agents) for\nthe lifecycle and data-quality contract.\n\nAsk in desk language rather than naming tools:\n\n> How is my portfolio exposed by underlying?\n>\n> Which repeated entries, adds, trims, or exits had the largest observed\n> 20-session price impact, and what coverage bounds that answer?\n>\n> Are any protection or exercise candidates ready for human review?\n\nThe [host guide](docs/docs/start/hosts.md) covers Claude Code, Cursor, Continue,\nZed, framework integration, logs, and connection checks. The generated\n[MCP reference](docs/docs/reference/mcp-tools.md) is the exact tool and schema\ninventory. The optional Claude Code plugin adds Canary's skill, MCP config, and\nsafety hooks; it does not ship the binary.\n\n## Shell and paired app\n\nEvery data command supports `--json`:\n\n```sh\ncanary account\ncanary positions --by underlying\ncanary brief\ncanary edge\ncanary rules\ncanary regime --explain\ncanary stress --details\ncanary technical SPY,QQQ\ncanary calendar --market us --days 14\ncanary proposals list\ncanary opportunities list\ncanary orders open\n```\n\nRun `canary status` first when anything looks wrong. `canary --help` and the\n[CLI reference](docs/docs/reference/cli.md) carry the complete command and flag\ninventory.\n\nFor the paired app, run `canary app` on the machine that owns the Gateway or\nTWS session, then run `canary app pair` and scan the QR code. The current\nworkspace is Monitor, Positions, Edge, Alerts, and Orders; Settings opens from\nthe header gear. See the [app guide](web/app/README.md) for local pairing,\nremote-relay, and Web Push boundaries.\n\n## Go wire-protocol library\n\n`pkg/ibkr` is a clean-room Go client for the TWS wire protocol:\n\n```go\nimport (\n    \"context\"\n    \"time\"\n\n    \"github.com/osauer/canary/v2/pkg/ibkr\"\n)\n\nfunc accountSummary(ctx context.Context, clientID int) (*ibkr.RawAccountSummary, error) {\n    cfg := ibkr.DefaultConfig()\n    cfg.Port = 4002 // Gateway paper\n\n    connector := ibkr.NewConnector(&ibkr.ConnectorConfig{\n        // Use an ID not already owned by Canary or another TWS client.\n        PreferredClientID: clientID,\n        BaseConfig:        cfg,\n    })\n    if err := connector.Start(ctx); err != nil {\n        return nil, err\n    }\n    defer connector.Stop()\n\n    return connector.RequestAccountSummary(ctx, 5*time.Second)\n}\n```\n\nProtocol coverage is purpose-driven, not exhaustive. The package transports\nbroker requests but does not provide Canary's application-level authority\nboundary. Direct users must supply their own policy, authorization, journaling,\nand reconciliation controls. Start with the\n[package documentation](pkg/ibkr/doc.go).\n\nThe public Go module deliberately remains on the maintained `/v2` line while\nproduct v3 ships as signed binaries. Therefore `go install\ngithub.com/osauer/canary/v2/cmd/canary@latest` installs the v2 CLI, not product\nv3.\n\n## One authority, several adapters\n\n```text\nshell, MCP host, or paired app\n              ↓ local Unix socket\n         canary daemon\n              ↓ local TCP by default\n       IB Gateway or TWS\n```\n\nThe daemon starts on demand, owns the selected account, broker connection,\nmarket evidence, policy state, and local order journal, and normally exits\nafter 15 idle minutes. Adapters render typed daemon results; they do not\nre-create risk policy. The [architecture](docs/docs/internals/architecture.md)\nand [storage guide](docs/docs/internals/storage.md) describe the boundaries and\nthe retained `ibkr` XDG paths used for upgrade continuity.\n\n## Safety and privacy\n\n- **Read-only is the normal product.** The installer, updater, and MCP Bundle\n  select the standard binary, whose broker-write handlers are not compiled in.\n- **MCP has no preview or execution tools in any build.** It cannot place,\n  modify, cancel, submit, or exercise an order.\n- **Trading is a separate decision.** The experimental trading artifact keeps\n  actions behind pinned connection authority, a fresh exact review contract,\n  broker eligibility where applicable, healthy journaling, daemon\n  revalidation, runtime freeze, and transaction-specific human authority.\n- **Missing evidence stays missing.** A stale or unavailable input never\n  becomes a clean result merely because an older value exists.\n\nCanary has no telemetry and does not send account IDs, balances, quantities, or\nP/L to the maintainer. Configured public-data refreshes, an MCP host, remote\nrelay, or push service receive only the data disclosed in the path you enable.\n[PRIVACY.md](PRIVACY.md) is the authoritative data map; [SECURITY.md](SECURITY.md)\ncovers the threat model and signed release artifacts.\n\n## Help and project information\n\n- [Install and first run](docs/docs/start/install.md)\n- [Daily desk workflow](docs/docs/operate/daily-desk.md)\n- [Troubleshooting](docs/docs/start/troubleshooting.md)\n- [Configuration](docs/docs/reference/config.md)\n- [Release and update policy](docs/docs/reference/releases.md)\n- [Contributing](CONTRIBUTING.md)\n\nCanary is an independent third-party client for Interactive Brokers' publicly\ndocumented TWS API. It is not built, endorsed, sponsored, or supported by\nInteractive Brokers Group, Inc. or its affiliates. `pkg/ibkr` redistributes no\nInteractive Brokers code, libraries, jars, or market data. Nothing here is\ninvestment advice.\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 11667,
  "sha": "b972d598b8546789f7370b6be741e6788d6666824e128860824a2f2ab0dc4d5e",
  "repo_slug": "osauer/canary",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_osauer_canary_a0b4a612/readme"
}