guardrail-trader¶
An autonomous stock-trading agent for Interactive Brokers (IBKR), built as a learning project in agent harness design. Claude reviews the portfolio and proposes trades; plain, unit-tested code decides whether any of them may reach the broker.
Claude proposes, code decides
Every limit is enforced in code. Claude can read the limits, but it cannot change or bypass them.
Warning
Runs against an IBKR paper (simulated) account by default. This is an engineering project, not investment advice. Automated trading can lose money.
What it does¶
Twice per US trading day (shortly after the open and before the close), a scheduler starts one run:
flowchart TD
S[Scheduler<br/>launchd or supercronic] --> R[run_bot.py]
R --> REC{Reconcile<br/>journal vs IBKR}
REC -- mismatch --> STOP1[Stop: needs a human]
REC -- ok --> P[Price universe + FX]
P --> KS{Kill switch?}
KS -- drawdown ≥ limit --> LIQ[Sell all, halt]
KS -- ok --> MO{Market open?}
MO -- no --> SKIP[Skip: no LLM call]
MO -- yes --> AG[Claude agent loop<br/>read-only tools + submit_orders]
AG --> G[Risk gate<br/>pure code]
G -- approved --> EX[Executor → IBKR]
G -- blocked --> J
EX --> J[(Journal<br/>SQLite)]
J --> D[Local dashboard]Two ways to run it¶
| Native | Docker | |
|---|---|---|
| IB Gateway | desktop app, logged in by you | container with IBC auto-login |
| Scheduler | launchd LaunchAgent | supercronic in the bot container |
| Dashboard | LaunchAgent | dashboard container |
| Keep the Mac awake | LaunchAgent | LaunchAgent (containers can't stop the Mac sleeping) |
| Guide | Native setup | Docker setup |
Both modes share the same code, config and journal (data/journal.sqlite), so you can switch
between them without losing history. See Architecture for what runs where.
Where to go next¶
- Harness and agent loop: how Claude is wrapped, and why that matters more than the prompt.
- How to use: set your own rules, ticker universe and spend caps.
- Dashboard: what each part of the dashboard shows.
- Operations: launchd as code, logs, the journal CLI and troubleshooting.