ai-trading-kit

Connect your brokerage to your AI assistant in a few minutes, then learn to test and practice trading ideas with pretend money. Read-only by design. Nothing in this kit can place a real order.

No Python needed: download the one-file build for your system from the latest release (aitk-windows.exe, aitk-macos, aitk-linux), put it somewhere you keep programs, and run it from a terminal:

aitk-windows.exe          # Windows (rename it to aitk.exe if you like)
chmod +x aitk-macos && ./aitk-macos      # macOS: also allow it once under System Settings > Privacy & Security
chmod +x aitk-linux && ./aitk-linux

The builds are not code-signed, so Windows SmartScreen and macOS Gatekeeper warn the first time; choose "run anyway". If you would rather not trust an unsigned program, use the source install below.

From source (Python 3.11 or newer):

git clone https://github.com/Dimas-100/ai-trading-kit.git
cd ai-trading-kit
start            # Windows: double-click start.bat, or run it
./start.sh       # macOS / Linux

Either way you land on the path below. Every step is one command and one short lesson.

The path

Run aitk with no arguments any time to see where you are on the path. aitk lesson 1 prints a step's lesson; aitk check re-tests every connection and says what to fix.

Related MCP server: vibetrader-mcp

What it looks like

Ninety seconds, real commands, real SPY prices: the path, a backtest with its reality check, and a practice session that starts in the 2022 bear market.

A real run with a free Alpaca paper account, from the connection test to a question answered in Claude Desktop.

aitk check starts the connector the way the AI app will and shows what the guard removed:

Then, in Claude Desktop:

A backtest on real SPY prices, with buy-and-hold as the yardstick and the cautions spelled out:

The practice account: place an order, move time forward, see what filled:

Who this is for

• Never traded, curious what an AI can tell you about your account. Do steps 1 and 2. Stop there if you like; they are useful on their own.

• Have an idea and want to know if it would have worked. Steps 3 and 4 give you an honest backtest with buy-and-hold as the yardstick and the cautions spelled out.

• Know what overfitting is and want tooling that respects it. Step 6: your own strategy file, a settings sweep that chooses on the first part of history and judges on the last, and a practice account that fills at the next day's prices.

Not a trader? It still helps

Most people's money sits in index funds and a retirement account. Steps 1 and 2 are for them: connect, then ask retirement-check (am I on track?), fees-check (what am I paying?), monthly-checkin (a look in the mirror) and all-my-accounts (several brokers in one view). No trading required, and no advice given: numbers first, then what they mean.

Describe an idea, get a strategy

Once the lab is connected, the whole loop happens in conversation: say "buy when the price falls 5% below its 20-day high and sell after it recovers 5%", and your AI writes the strategy file, saves it into your strategies folder, backtests it on real prices and reports, reality check included. Before anything is saved the kit checks the code (a strategy may import only the engine's own pieces and nothing that touches files or the network) and test-runs it. aitk strategy show NAME prints what was written; it is an ordinary Python file you can edit.

Make it a project

aitk init my-trading creates a folder that is yours: plan.md (the rules you trade by), journal.md (why you did what you did, which your AI can write for you), strategies/, an AGENTS.md that tells any AI opened there how to behave, and a first git commit. Run aitk anywhere inside it and the kit uses it as home, so the practice account and prices live there too. It is the shape of a serious hobbyist's setup, ready on day one.

Your AI can guide the setup

Once the lab is connected (step 3), you can ask your AI "where am I on the path?", "help me connect Fidelity" or "check my connections". It knows every broker, hands you the exact command, and re-tests what you set up. It is told never to ask for a key in the chat; keys are typed only into the wizard in your own terminal.

Brokers

The kit sets up each broker's official connector and never uses tools that log in with your password (they break most brokers' terms). Where the kit starts the connector itself, its guard removes every tool that could change your account before your AI ever sees it.

aitk brokers prints the full list, aitk brokers fidelity explains what is possible for a broker. Interactive Brokers, TradeStation and tastytrade are listed with advice but not set up by the wizard yet. Fidelity, Vanguard, Schwab, E*TRADE, Merrill, SoFi and Firstrade offer no official connector; SnapTrade reads them.

AI apps

Claude Desktop, Claude Code and Cursor: the kit writes the connection for you, after a backup of the settings file, and never puts a key in it. ChatGPT keeps connections in its own settings screen, so the kit prints the exact steps; ChatGPT can use only the sign-in brokers.

How a connection works

flowchart LR
    A[your AI app] --> G[the kit's guard<br/>removes every tool that could change the account]
    G --> C[the broker's official connector]
    C --> B[your broker]
    V[(your computer's<br/>password vault)] -. keys at start-up .-> G

• Your keys live in the operating system's password vault. They are never in this folder and never in an AI app's settings file, and the kit never prints them.

• aitk check starts the connector the same way your AI app does, asks it which tools it offers and shows which ones were removed. Alpaca's connector offers 45 tools: 44 reads pass and the one that changes settings is removed. Public's offers 37: 27 pass and all 10 order tools are removed.

• Where a broker's connector cannot be held to read-only (Robinhood, Moomoo), the wizard says so before going on and asks you to confirm.

The lab

aitk connect-lab gives your AI a second connection: the kit's own practice lab. Its tools test ideas on price history and trade a pretend-money account on your computer. It has no connection to any broker.

aitk prices key                    # once: a free price-data key (Tiingo or Alpaca)
aitk prices get SPY QQQ            # ~20 years of daily prices, kept on your computer
aitk backtest rsi2 SPY --trades    # one rule, with the trade list
aitk compare SPY                   # every rule side by side
aitk sweep sma_cross SPY fast=10,20,50 slow=100,200
aitk practice start && aitk practice buy SPY 5 && aitk practice next

Until you download prices, every command runs on made-up demo prices and says so. Built-in strategies: buy_hold (the benchmark), sma_cross, rsi2, donchian. Your own go in the kit's home folder as one Python file each (aitk strategy new NAME writes a template).

Every backtest ends with a reality check: the longest stretch you would have sat below a previous peak, the worst run of losing trades, and the biggest single loss in dollars. Those end more strategies than bad returns do.

Live through a hard year. aitk practice start --scenario 2022-bear begins the practice account in January 2022 (also 2020-crash, 2023-rally, 2025-tariffs). Move a week at a time, decide each time, then aitk practice report shows how you did against simply holding, with a verdict.

What this kit refuses to do

• Place, change or cancel a real order. There is no code path for it, and the tests check that the lab's only state-changing tools are the practice ones and the price download.

• Store a key in the repository or in an AI app's settings.

• Use unofficial, password-scraping broker libraries.

• Tell you what to buy. Every result comes with the cautions a careful person would want.

Building the one-file kit yourself

pip install -e . pyinstaller
pyinstaller packaging/aitk.spec        # -> dist/aitk (dist/aitk.exe on Windows)

.github/workflows/release.yml does this for Windows, macOS and Linux on every v* tag and attaches the three files to the release.

Manual install

python -m venv .venv
.venv/Scripts/python -m pip install -e .        # Windows
.venv/bin/python -m pip install -e .            # macOS / Linux
aitk

Python 3.11 or newer. The kit's own files live in ~/.ai-trading-kit (set AITK_HOME to move them). Broker connectors that run locally need uv for uvx; the wizard tells you when.

Project layout

src/aitk/
  cli.py                 the aitk command
  connect/               step 1: recipes/*.toml (one per broker), apps.py (AI app adapters),
                         guard.py (the read-only guard), launcher.py, doctor.py, wizard.py
  engine/                bars, indicators, strategies, one fill model, practice broker, backtest
  lab.py                 backtests with plain-words verdicts; the settings sweep
  practice.py            the pretend-money account with its own calendar
  prices.py              price files, demo prices, downloads (Tiingo, Alpaca)
  mcp/                   a small MCP implementation (server + client) and the lab server
  guide/                 the seven steps, their lessons and the prompt library
tests/                   no network, a fake broker connector, every adapter against a temp home
docs/                    design, safety model, how to add a broker

Contributing

Adding a broker is adding one TOML file: see docs/adding-a-broker.md. Every recipe records the date its facts were last checked against the broker's own pages and how confident that check was.

Disclaimer

This is a personal project shared as a reference. Nothing in it is financial advice. Backtests show what would have happened, not what will. If you ever trade real money, do it at your broker, start small, and decide your exit before you enter.

MIT licensed.