An AI agent that trades a real brokerage account, and is never allowed to make a trading decision.
A complete, unattended swing-trading system for one cash brokerage account. A deterministic Python core holds every rule: what to buy, how much, when to sell, and every reason to refuse. A scheduled Claude session is only the hands. It fetches broker data, hands it to the core, and places exactly the orders the plan names, at the prices the plan gives.
The result is an agent you can audit. Every decision is a pure function of stored inputs, so it can be replayed offline, tested, and measured against a rule change before that change touches money.
Fork it, point it at your own account, and make it yours: the strategies, the risk limits, the sectors and the schedule are all yours to change.
Not financial advice. This is a reference implementation of a personal trading system. It is not a product and not a recommendation to trade any security. It is built for one small brokerage account, carries no warranty of any kind (see LICENSE), and can lose money, including all of it. Use, fork, or adapt it entirely at your own risk.
- The whole system, not a demo. Strategies, sizing, risk guard, broker reconciliation, a database schema, scheduled jobs, alerting, operator controls, a backtest engine and the prompts the agent runs. Nothing is left as an exercise.
- The model cannot improvise a trade. It places only what
plan.orders,plan.protectionandplan.cancelsname. The plan is written to the run log before anything is placed. - Decisions are reproducible. The core has no network access, and a test proves it. Stored cycle inputs are replayed nightly against rule variants, so a rule change is measured before it trades.
- It fails closed. Missing data, an ambiguous broker answer, a stale universe or an implausible account read each stop new entries. Exits are still placed.
- It checks its own book. Every reconciling cycle compares the broker's positions and orders with what the system intended and classifies each disagreement. It never silently repairs one.
- It reports on itself. One status push per cycle from a fixed list of 42 alert titles, each with a written meaning and action. A watchdog in the database alerts if the queue or a cycle stalls.
- It is honest about what works. Each strategy was tested offline against random controls, and the README says which ones failed. See How strategies are judged.
- It is built to be changed. More than 80 documented settings, strategy switches that record what they would have done while off, and 3,400+ tests that tell you what your change broke. See Customization.
- It costs almost nothing to run. Everything except the Claude plan and the brokerage account fits a free tier, and nothing depends on a machine you own being awake.
No accounts, no API keys, no network. You need Python 3.11+ and uv.
git clone https://github.com/<owner>/deterministic-trader.git
cd deterministic-trader
uv sync --group dev
uv run pytest # 3,400+ tests, under a minuteThe core is a command-line program. It reads one cycle document (account, positions, quotes, indicators) on stdin and writes the plan on stdout:
uv run python -m src.cli plan-fetch < cycle.json # classify the cycle, list what to fetch
uv run python -m src.cli decide < cycle.json # the full pipeline, returns the planA plan is plain JSON, abridged here. It is the only thing the agent is allowed to act on:
{
"plan": {
"cancels": [],
"orders": [
{
"symbol": "PFE", "side": "buy", "type": "limit",
"quantity": 1, "limit_price": 25.18,
"session": "regular_hours", "play_id": "DIP"
}
],
"protection": []
},
"reason": "09:40 ET Mon: full cycle for 2026-08-03"
}The same document also carries the regime read, every candidate each strategy considered, every order the guard denied and why. tests/factories.py builds complete cycle documents, and tests/golden/ holds recorded outputs, which is the quickest way to read a real one.
When you are ready to run it for real, go to Install and run.
- Architecture
- Built with
- What is in this repo
- What it trades
- How strategies are judged
- Risk controls
- Design decisions
- Control it
- Pick your sectors
- Alerts: Telegram
- Services and APIs
- Caveats to know before you fork
- Install and run
- Customization
- Build on it
- Use it as an MCP server
- The daily schedule
- Repository map
- Documentation
- Contributing
Three parts, with a hard line between them. The brain decides and cannot reach the network. The hands reach the broker and cannot decide. The database sits between them and records everything either one does.
flowchart LR
subgraph FEEDS["Data feeds, no agent involved"]
GHA["GitHub Actions<br/>SEC 8-K, FRED, S&P 500 members"]
PRE["Pre-market job<br/>Twelve Data bars to SMA, RSI, ATR, regime"]
end
subgraph HANDS["The hands"]
RUN["Scheduled Claude routine<br/>fetch, place, report"]
RH["Robinhood MCP<br/>quotes, positions, orders"]
end
subgraph BRAIN["The brain"]
CORE["Hosted core on Vercel<br/>universe, regime, plays,<br/>sizing, guard, reconcile, report"]
end
subgraph STATE["Supabase Postgres"]
DB["control switches, lock, ledgers,<br/>step log, alert queue, schedule"]
CRON["pg_cron<br/>alert relay, watchdogs, nightly replay"]
end
subgraph OPERATOR["You"]
PUSH["Telegram<br/>push alerts"]
CTL["Manual Control<br/>GitHub Action, CLI or SQL"]
end
GHA -->|git commits| CORE
PRE --> DB
RUN <--> RH
RUN -->|raw broker data| DB
DB <-->|pg_net| CORE
DB -->|the plan| RUN
CRON --> PUSH
CTL --> DB
sequenceDiagram
autonumber
participant R as Claude routine<br/>(hands)
participant B as Robinhood MCP
participant D as Supabase Postgres
participant C as Hosted core<br/>(brain)
R->>D: Should this run? Claim the lock
D-->>R: Cycle type and what to fetch
R->>B: Account, positions, orders, quotes
B-->>R: Raw broker data
R->>D: Post the data unedited
D->>C: Decide (pg_net)
C-->>D: The plan, written to the run log
D-->>R: The plan
R->>B: Place exactly the plan
B-->>R: What the broker said
R->>D: Post the answers word for word
D->>C: Reconcile and report
C-->>D: Ledgers updated, one alert queued
D-->>R: Done, release the lock
- Should this run?
edge_should_runchecks the published schedule and a state-change gate. A quiet monitor slot ends here at the cost of one database read. - Claim the lock. One cycle at a time. A stale lock is stolen and the steal is logged.
- Fetch. The routine pulls account, positions, orders and quotes from the broker and posts them unedited. The core tells it which symbols need more data.
- Decide. The core resolves the universe, reads the regime, lets each play fire or skip, sizes from settled cash, runs every order past the guard, and returns a plan.
- Place. The routine places the plan and posts back exactly what the broker said, word for word.
- Reconcile and report. Broker truth is compared with intent, ledgers are updated, and one status alert is queued.
The cycle type (full, monitor, postclose, overnight, noop) is decided by src/cadence.py from the wall clock and the market calendar, never by prompt text. A routine that fires at the wrong time is reclassified instead of trading the wrong way.
Every cycle runs the same pipeline of pure functions. Each stage is one module under src/ with its own tests, so you can change one without reading the rest.
flowchart TB
IN["Cycle document<br/>account, positions, quotes, indicators"]
subgraph SIT["1. Read the situation"]
direction LR
CAD["cadence<br/>what kind of cycle"] --> REC["reconcile<br/>broker truth vs the book"] --> UNI["universe<br/>who is eligible"] --> REG["regime<br/>market and sector state"]
end
subgraph DEC["2. Decide"]
direction LR
EX["exits<br/>what must be sold"] --> PL["plays<br/>what each strategy wants"] --> SZ["sizing<br/>how much, from settled cash"] --> GD["guard<br/>every reason to refuse"]
end
OUT["The plan<br/>orders, protection, cancels"]
IN --> SIT --> DEC --> OUT
| Layer | Technology | Why this one |
|---|---|---|
| Decision core | Python 3.11+, standard library, one dependency (tzdata) |
Small enough to read, pure enough to replay. No pandas, no framework. |
| Agent | Claude scheduled routines | The hands: 8 short sessions a trading day, driven by the prompts in docs/routine/. |
| Broker | Robinhood Agentic Trading MCP | Account data and order placement over OAuth, with no password stored anywhere. |
| State and scheduling | Supabase Postgres with pg_cron, pg_net and Vault |
The lock, ledgers, alert relay and watchdogs live in one database, in one schema file. |
| Hosted core | Vercel Python functions | The same src/ code behind six POST-only endpoints, called only by the database. |
| Market data | Twelve Data, SEC EDGAR, FRED, SPY holdings | Daily bars and indicators, 8-K filings, macro series, index membership. |
| Data pipeline and control | GitHub Actions | Commits data/*.json on a schedule and runs the Manual Control verbs. |
| Alerts | Telegram bot | One status push per cycle, plus the events that need you. |
| Tooling | uv, pytest |
One command to install, one to test. |
Accounts, keys and free-tier limits for each are in Services and APIs.
| Area | What you get |
|---|---|
Deterministic core (src/, 24,000 lines) |
Universe, regime, plays, sizing, guard, reconcile and reporting as pure functions. JSON in, JSON out, no network. |
Hosted core (services/core/, 6,700 lines) |
The same core as six Vercel functions, so a trading session needs no Python and does no arithmetic. One acceptance test pins the hosted plan to the local plan. |
| Test suite (160+ files, 3,400+ tests) | Offline, runs in under a minute. Includes golden-file tests, contract tests against recorded broker payloads, and tests that pin policy (no network in src/, no resting stop orders). |
Database (db/schema.sql) |
Supabase Postgres in one file: kill switch, cycle lock, ledgers, alert queue and relay, step log, watchdogs, schedule, shadow and evidence ledgers. |
Agent prompts (docs/routine/) |
The exact prompts the scheduled routines run, plus the setup guide for creating them. |
Operator tooling (ops/) |
The Manual Control GitHub Action path, a control CLI, and the research scripts. |
Research harness (ops/*.py) |
A leak-audited backtest engine and placebo and control-arm studies. |
Guided installer (scripts/install.py) |
Collects your details once, writes .env, and can substitute them into the files a fork must change. |
Operating documents (docs/) |
A tuning reference for every knob, the sector code table, the design document and the alert runbook. |
The universe is the S&P 500 (from the SPY holdings file, cross-checked against Wikipedia for GICS sector and sub-industry) plus eleven sector ETFs and four broad-market ETFs. Long only, whole shares by default, settled cash only.
| Strategy | What it does | Shipped state | Switch |
|---|---|---|---|
| Core sleeve | Holds idle settled cash in one broad ETF (default SPYM) up to 50% of equity. One resting limit sell 20% above the buy price. No stop of any kind. Never sells to fund a play. |
On | core_sleeve_enabled in config/config.json |
| DIP | Oversold in an uptrend: RSI ≤ 30, price above or no more than 3% below the 200-day, clear of earnings. 6% target, 8-session time stop, exits early when RSI recovers to 50. | On | dip_entries_enabled |
| Dip Recovery sleeve | A separate deep mean-reversion strategy with its own watchlist, dip score, Bollinger and freefall tests, concentration caps and 5% profit target. | Off, opt-in | dip_recovery_enabled (dip_on/dip_off) |
| Sector rotation play | Buys an oversold sector ETF that is above its own 200-day. | Off, shadow-tested | play_sector_enabled |
| DIP pullback reshape | A shallower pullback-in-uptrend version of DIP with liquidity and spread tests. | Off, shadow-tested | play_dip_pullback_enabled |
| CATALYST | 8-K event with a 3% move on 1.5× volume. | Shelved | play_catalyst_enabled |
| MACRO | Macro release surprise mapped to sector ETFs through config/macro_map.json. |
Shelved | play_macro_enabled |
| PEAD, SURGE | Post-earnings drift; all-in momentum. | Retired in code | A code change, with a new test behind it |
| Leaders monthly | A monthly momentum pick. | Recorded in shadow only, never traded | .github/workflows/leaders.yml |
Positions the system did not open (anything you buy by hand in the same account) are adopted. They are bound to a play if one describes them, or to an ADOPTED play with its own exit terms, so nothing in the account is unmanaged.
Exits are evaluated top-down on every cycle, including overnight: hard event exit (a restatement 8-K), drawdown flatten, earnings deadline, ATR stop, time stop, target, signal exit.
Profit first. Each position rests exactly one broker order: a limit sell priced above its buy price. The stop is a check made once per cycle, not a resting order, so an intraday wick cannot sell a position that would have recovered. When a position is through its stop at a cycle, the resting target is cancelled and an ordinary limit sell is placed. tests/test_profit_first_policy.py pins this. The trade-off is gap risk between cycles, and it is a deliberate choice you can read about in docs/TUNING.md §1.4.
A live account this size cannot prove a strategy. At the measured per-trade variance, confirming a 0.3% edge needs about 1,900 trades. So the evidence is built offline and in shadow, under rules fixed before each test ran.
- Rules fixed in advance. Each hypothesis and its pass bar is stated before the trial runs.
- Honest backtest.
ops/backtest_engine.pyfills at the next open, charges costs, applies the portfolio caps, uses a walk-forward split and is audited for look-ahead. - Controls. Each signal is compared with a random name from the same sector on the same day under identical exits, and with holding SPY at matched exposure.
- Shadow ledger. Every night the stored inputs of recent cycles are replayed through the live code under named rule variants. The weekly scorecard shows what each variant would have done.
- Evidence ledger. Every candidate a play judged is snapshotted at decision time, with forward returns filled in later.
In short: PEAD and SURGE showed no edge and were retired. CATALYST and MACRO could not justify themselves and were shelved. Holding the index at matched exposure beat the stock-picking policy, which is why the core sleeve exists. DIP did not beat its random control out of sample, and it stays on by operator choice behind a one-line switch. One monthly momentum rule narrowly passed and is being recorded in shadow before any money goes to it.
Every new behaviour ships switched off, records what it would have done, and is turned on by an operator decision.
| Control | Behaviour |
|---|---|
| Kill switch | trading_enabled seeds FALSE. The master_off verb stops all placement on the next cycle. Nothing in code ever turns it on. |
| Drawdown halt | 20% below the high-water mark, measured on deposit-adjusted equity. Buys are denied, the book is flattened, and the halt lifts by itself when equity recovers. |
| Implausible account read | An equity figure that does not cover the positions, or has collapsed against yesterday, denies buys and sells nothing. A bad read cannot flatten the book. |
| Settled cash only | Every buy is funded from settled cash, so the account cannot incur a good-faith violation. |
| Concentration | Position and sector caps derived from live equity. The same code sizes a $250 account and a $10,000 one with no configuration change. |
| Event windows | No entry within 2 sessions of earnings, and a held name is flattened as the window opens. A name closed at a loss is not rebought for 31 days. |
| Order legality | Exits are limit orders; the one exception is a fractional lot in regular hours, which the broker only accepts as a market sell. Session-aware rules for extended hours, including a spread ceiling. No entries in the last 30 minutes. |
| Candidate fence | The guard refuses any order for a symbol outside the cycle's resolved candidate set. |
| Reconciliation | Six classes of broker-versus-book disagreement. A persistent one blocks entries until you clear it. |
| Scope and time budgets | Caps on how many symbols one cycle may fetch for, and a wall-clock budget per cycle type that cuts optional fetches first and never cuts exits. |
| Cycle lock and step log | One cycle at a time. Database triggers record each step, so the log does not depend on the agent remembering to write it. |
The calls that shape everything else, and why each was made.
| Decision | Reason |
|---|---|
| Rules in Python, hands in the agent | A rule that lives in prompt text can be forgotten or reinterpreted. Every rule, denial and threshold is in src/ under test; the agent holds none. Where the two seem to disagree, the core is right. |
No network in src/ |
An AST import scan (tests/test_invariant_no_network.py) fails the build if anything under src/ can reach the network. That is what makes a decision a pure function of its inputs. |
| Run log before placement | The plan is written to edge_runlog before any order is sent, and the broker's answers after. What was intended and what happened are separate records. |
| Cadence in Python, not in cron | A firing is classified by cadence.py from the clock. A per-slot prompt would be a second decider that can disagree with the first. |
| Git commits as the data channel | The routine's sandbox can reach GitHub and little else, so CI commits data/*.json and both the routine and the hosted core read the same reviewed, versioned files. |
| Alert relay in Postgres, not in CI | Scheduled GitHub Actions were measured 57 to 114 minutes late. pg_cron with pg_net delivers within about a minute at no cost. |
| Watchdog in the database | The relay, the queue and the lock are watched by pg_cron timers in the same database, so a stalled queue raises an alert the routine does not have to remember. |
| Derive, never configure, the capital ladder | Position count, slot size and caps come from live equity and broker cash each cycle, so the same code is correct as the account grows. |
| Guard denies, plays emit | A drawdown breach is an order denial rather than a global stop, so the flatten that the breach calls for can still be placed. |
| Play shapes are code, not config | A play's trigger cannot be retuned without a source change and a review. Numbers you are meant to tune live in config/config.json. |
| Reconcile never repairs silently | The broker is the truth. A disagreement is classified, reported and, if it persists, blocks entries. The only automatic action is a cancel. |
| Indicators are computed once, server-side | The pre-market job computes SMA, RSI and ATR from Twelve Data daily bars and caches them for the day. Every cycle reads the cache, so the agent never computes an indicator and rarely has to fetch one. |
| New rules ship off and in shadow | A switch that is off still records what it would have done, and the nightly replay measures it before an operator turns it on. |
| Secrets in Vault and env files, never in code | A token in a SQL function body is a token in every database dump. No secret is committed, and the hosted core returns an error rather than run when its token is unset. |
Control is a manual GitHub Action (Manual Control, .github/workflows/control.yml) or the same verbs from the ops/control.py CLI. Both read one verb table (ops/verbs.json), so they cannot drift apart, and every write is logged in the Actions run under whoever dispatched it. The same keys can also be set directly in SQL.
VIEW
status switches, account
sectors active sectors
last last cycle result
step cycle in progress
holds operator holds
SWITCHES
master on|off all trading
core on|off core entries
dip on|off Dip Recovery
block on [why] stop entries
block off allow entries
clear unblock, reset streak
kill same as master off
A write replies with one line saying what changed plus the resulting switches. The kill switch is operator-only: nothing in code ever turns it on.
You choose where new money may go, at runtime, with no deploy, through the Manual Control Action (sectors_set), the ops/control.py CLI, or SQL:
sectors_set SEMI, SOFT, DC only semiconductors, software, data-center REITs
sectors_add EN also Energy
sectors_remove DC
sectors_clear every sector again
- 11 sector codes (
EN,FIN,IT,HC,IND,CD,CS,UTL,MAT,RE,COM) - 126 GICS sub-industry codes (
CHIP,BIO,PAY,TOWR, …), one for every sub-industry in the S&P 500 - 5 baskets (
SEMI,SOFT,BANK,INS,RESI)
Full names and sector ETF tickers (XLE) are accepted too. The full table is in docs/ROTATION_CODES.md, generated from config/rotation_codes.json and checked by a test.
A rotation only limits new money. Held positions keep their exits and are never sold because of it. A name outside the rotation is not fetched for, which also makes cycles cheaper. A typo fails open and is reported; it cannot freeze entries.
Alerts are rows in a Postgres queue, drained every minute by pg_cron and pg_net to Telegram. The relay tracks delivery and retries up to five times.
- One status push per cycle:
<Routine> cycle succeeded | succeeded with warnings | partial | blocked | failed | skipped. A quiet success is sent at minimum priority, so a missing push means something. - Fixed titles for the events that matter:
Drawdown halt,Account read implausible,Order refused,Manual action required,Cycle stalled,Cycle over budget,Weekly scorecard, and more. - A title outside the canonical list is rejected at the queue, and each alert footer links to a written entry saying what it means and what to do.
- Weekly scorecard every Friday: return net of deposits against SPY and against the frozen inception book, realized P&L per play, and the shadow variants.
Telegram needs a bot token and a chat id; it is the push channel.
Everything except the Claude subscription and the brokerage account runs on a free tier.
| Service | Role | Notes |
|---|---|---|
| Robinhood via its Agentic Trading MCP | The only source of account data and the only place orders go | Cash account. Connected once by OAuth to your Claude account. There is no headless login, so order placement only happens inside a Claude routine. |
| Claude scheduled routines (paid Claude plan) | The hands: 8 short sessions a trading day | The repo ships the prompts in docs/routine/. Routines need the Robinhood and Supabase connectors attached. |
| Supabase (Postgres, free tier) | State, locking, ledgers, alert relay, cron | Needs the pg_cron, pg_net and Vault extensions. All secrets the database uses live in Vault. |
| Vercel (free tier) | Runs the hosted core | Deployed from the repository root. Called only by Supabase, server-side, with a shared token. |
| Twelve Data (free Basic key) | Daily bars for the pre-market job: SMA, RSI, ATR, market regime | 800 credits a day; the job caps itself at 560 and paces to 8 a minute. Without the key the job fails closed and writes nothing, so the plays have no fresh indicators to act on. |
| GitHub Actions | Fetches SEC 8-K filings, FRED macro series and S&P 500 membership into data/*.json |
No API keys needed for any of the three sources. About 165 minutes a month measured. |
| Service | Role | Without it |
|---|---|---|
| Telegram bot | Push channel | Without it there is no push channel; control is unaffected. |
| Alpha Vantage (free key) | Analyst estimates on the evidence ledger | The evidence job records bars as before and requests no estimates. |
| yfinance | Offline research scripts in ops/ only |
Declared inline per script (PEP 723). The trading path never imports it. |
Legacy self-contained cycle (docs/routine/cycle-prompt.md) |
A routine that runs src.cli in its own checkout instead of calling the hosted core |
Kept as the recovery path if the hosted core is unavailable. |
Broker access is tied to a Claude session. Robinhood's MCP is OAuth-only, so there is no way to place orders from a server or a cron job. That is why the hands are a Claude routine. Other brokers would need a new adapter for the routine prompts and src/broker_shapes.py; the core does not care where the data came from.
Routine crons are in UTC. Scheduled routines have no timezone field, so each trigger shifts by an hour at the two daylight-saving changes; move the routine crons yourself at each change. The server-side jobs gate on Eastern wall-clock time and need no change.
Built for one small cash account. Whole shares, settled cash, long only, no margin, no options, no shorting, US equities. Fractional lots can only be sold in regular hours, which is why whole shares are the default.
It is not a claim of profitability. The research in this repo says plainly which of its own strategies did not beat a random control.
Things you must change in a fork. scripts/install.py collects the values below and prints this checklist; --apply substitutes them into the tracked files for you (leaving the tree dirty to review). By hand:
config/inception.json: the frozen benchmark book and deposit history are a sample. Replace them with yours, and setaccount_numberto your cash account..github/workflows/universe.yml,leaders.yml,events.yml: the commit author name and email in the "commit" steps.ci/common.py: theEDGAR_CONTACTdefault address.SECURITY.mdandREADME.md: the repository URL and contact address.docs/routine/*.mdanddocs/routines.md: the clone URL and account number in the prompt files and the routine instruction..env(untracked, written by the installer from.env.example): your Supabase URL and key.
Everything runs on a free tier except the paid Claude plan and the brokerage account. Stand the dependencies up in the order below.
| Need | Why | Where |
|---|---|---|
| Python 3.11+ and uv | Runs the core and the installer | curl -LsSf https://astral.sh/uv/install.sh | sh |
| A Supabase project (free tier) | State, locking, ledgers, the alert relay, pg_cron/pg_net |
supabase.com — step 1 |
| A Vercel account (free tier) | Runs the hosted core from this repository | vercel.com — step 4 |
| A paid Claude plan | The scheduled routines are the only hands | claude.ai |
| A Robinhood cash account with Agentic Trading (MCP) | The only source of account data and the only place orders go | Robinhood |
| A Twelve Data free Basic key | Daily bars for the pre-market job; without it the plays have no indicators | twelvedata.com |
| A Telegram bot (optional) | The push channel for alerts | @BotFather |
The installer asks for two Supabase values, so create the project first.
- Sign in at supabase.com and choose New project. Pick a region near you and keep the generated database password somewhere safe.
- Open Project Settings → API and copy both of:
- Project URL —
https://<project-ref>.supabase.co - Project API keys →
service_role(the secret, revealed with Reveal) — a JWT beginningeyJ…
- Project URL —
- Leave the schema alone for now; step 3 applies it.
The
service_rolekey bypasses Row Level Security by design. The offlineops/scripts and the hosted core act as the operator, server-side. Never ship it to a browser, a public client, or a committed file.
git clone https://github.com/<owner>/deterministic-trader.git
cd deterministic-trader
uv run python scripts/install.pyThe installer is the one place you enter your details. It prompts, in order, for:
- GitHub owner/username and email — the commit identity in the workflows and the
EDGAR_CONTACTdefault. - Supabase project URL and service_role key — the two values from step 1.
- Robinhood cash account number — the account the system trades; and, optionally, your margin account number (recorded in a note in
config/inception.json; the system never trades it). - Optional, press Enter to skip:
CORE_TOKEN,SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,TWELVE_DATA_API_KEY,ALPHAVANTAGE_API_KEY, and the Telegram bot token and chat id. The first five are written to.envas a record; you still enter them in Vercel (step 4) and Supabase Vault (step 3) yourself.
It then writes a filled-in .env from .env.example (gitignored) and prints the tracked files you must still edit — the checklist in Caveats to know before you fork. It edits nothing unless you ask it to:
uv run python scripts/install.py --apply --test| Flag | Effect |
|---|---|
--apply |
Substitute the collected values into the checklist files, then leave them for you to review with git diff |
--test |
Run uv run pytest after setup |
--no-sync |
Skip uv sync --group dev |
--yes |
Non-interactive: prompt nothing and write no .env |
Review the changes, commit and push. The test suite uses fixed dummy account numbers, so it passes whatever you put in config/inception.json.
Back in the Supabase dashboard:
-
Apply the schema. Open the SQL Editor, paste the whole of
db/schema.sqland run it once. It is one transaction that creates every table, function and seed row, followed by thepg_cronjobs. It creates thepg_cronandpg_netextensions; if your project blocks that, enable both under Database → Extensions first and run it again.vaultships enabled. The file is written for an empty database.- With
psqlyou can instead runpsql "$DB_URL" -v ON_ERROR_STOP=1 -f db/schema.sqlagainst the Session pooler ("Direct connection" or port5432); the transaction pooler cannot runpg_cron.
- With
-
Set the Vault secrets in the SQL Editor. The relay and the dispatch functions read only these:
select vault.create_secret('<telegram bot token>', 'edge_telegram_bot_token'); select vault.create_secret('<telegram chat id>', 'edge_telegram_chat_id'); -- after step 4, with your Vercel URL and the CORE_TOKEN you chose: select vault.create_secret('https://<project>.vercel.app', 'edge_core_url'); select vault.create_secret('<CORE_TOKEN>', 'edge_core_token');
A channel whose secret is absent is skipped, so add the Telegram pair only if you want push.
-
Test the alert relay. In the SQL Editor:
insert into edge_alerts (title, body, priority) values ('Manual action required', 'relay test', 'default');
A Telegram push should arrive within a minute.
-
Go to vercel.com/new, Import Git Repository, and pick your fork.
-
Set Root Directory to the repository root (
./), notservices/core—api/cycle.pydoesimport srcand readsconfig/from the checkout. Framework Preset: Other. Leave Build & Output defaults;/vercel.json,/requirements.txtand the/api/*.pyshims drive the functions. -
Under Environment Variables (Production) add:
Name Value CORE_TOKENA long random string you generate, e.g. openssl rand -hex 32SUPABASE_URLYour Project URL from step 1 SUPABASE_SERVICE_ROLE_KEYYour service_rolekey from step 1TWELVE_DATA_API_KEYYour Twelve Data Basic key. Without it the pre-market job writes nothing and the plays have no indicators to act on ALPHAVANTAGE_API_KEYOptional; omit to skip analyst estimates -
Deploy, then copy the production URL (
https://<project>.vercel.app) and set the last two Vault secrets from step 3 (edge_core_url,edge_core_token).
Every endpoint is POST-only and is called only by Supabase pg_net. Details: services/core/README.md.
- In your fork, enable Actions (forks start with workflows disabled), then open Settings → Secrets and variables → Actions and add
EDGE_SUPABASE_URL(your Project URL) andEDGE_SUPABASE_KEY(the sameservice_rolekey). These are what the offline workflows use; the commit identity is the owner and email you gave the installer. - Open the Actions tab and run the Universe and Events workflows once by hand so
data/is populated.
Edit config/inception.json — replace the frozen benchmark book, the deposit history and account_number with your own — then review config/config.json, commit and push. See Customization.
Connect the Robinhood (Agentic Trading MCP) and Supabase connectors to your Claude account, then create the routines listed in docs/routines.md. That file gives each routine's name, cron (for both summer and winter time), prompt file and the short instruction to paste. Routine crons are UTC and must be moved by hand at each daylight-saving change.
Go-live is a deliberate last step: trading_enabled starts FALSE. When every step above is done, run the Manual Control Action with status, then with master_on.
Where each secret lives and how to rotate one is in SECRETS.md. No secret is ever committed.
There are three control surfaces. docs/TUNING.md documents every knob with its safe range and the trading style it pushes toward.
| Surface | Holds | Takes effect | Edited by |
|---|---|---|---|
config/config.json |
Sizing, exits, the drawdown halt, event windows, regime thresholds, cycle budgets, every strategy switch | The next cycle after you commit and push | Editing the file |
edge_control table |
The kill switch, entry block, per-name holds, active sectors | The next cycle, no deploy | The control.yml Action or SQL |
dip_recovery_config table |
The Dip Recovery sleeve's thresholds, sizing, exits and caps | The next cycle, no deploy | The control.yml Action for the on/off flag, SQL for the rest |
A selection from config/config.json:
| Knob | Shipped | Effect |
|---|---|---|
min_position_size |
200.0 |
Target position count is clamp(round(equity / this), 3, 25). Raise it for fewer, larger positions. |
max_new_positions_per_day |
3 |
Cap on fresh entries per day. |
whole_shares_only |
true |
Refuse a buy that cannot afford one full share. |
drawdown_halt_pct |
0.20 |
The account-level circuit breaker. |
atr_stop_multiple / atr_trail_multiple |
3.0 / 3.5 |
The per-cycle stop check, from entry and from the position's high. |
earnings_flatten_days |
2 |
Hands off around earnings. |
wash_sale_days |
31 |
No repurchase after a loss for this many days. |
core_symbol, core_cap_pct, core_target_pct |
SPYM, 0.50, 0.20 |
The core sleeve's ETF, its share of equity and its resting target. |
dip_entries_enabled |
true |
Set false to stop new DIP money without touching held positions. |
play_catalyst_enabled, play_macro_enabled |
false |
Bring a shelved play back. |
regime_v2_enabled, sizing_v2_enabled |
false |
Five market postures from breadth and volatility; portfolio-level sizing. Both record what they would have done while off. |
dip_survivor_cap, resolve_max_symbols |
30, 50 |
How many names one cycle may fetch for: the main cost knob. |
monitor_cadence_minutes |
30 |
How often the state-change gate looks between cycles. |
cycle_budget_min |
full: 40, … |
Wall-clock budget per cycle type. |
tests/factories.config() is derived from the shipped file, so the suite always tests exactly what runs.
Play shapes (triggers, windows, conviction scales) are constants in src/plays/ by design. Changing one is a source change and a review. Adding a strategy is a new module there plus its tests; see Build on it.
Other files you may want to edit: config/etfs.json (the ETF sleeve), config/macro_map.json (macro release to sector mapping), config/market_holidays.json, config/rotation_codes.json.
The system is split so that each kind of change has one place to go. Starting points for a fork:
| You want to | Where it goes | What keeps you safe |
|---|---|---|
| Add your own strategy | A new module in src/plays/ that emits proposals, wired into the dispatch in src/plays/entries.py |
Sizing, the guard and exits already apply to anything a play proposes. Ship it behind a switch that defaults off and the shadow ledger records what it would have done. |
| Change when positions are sold | src/plays/exits.py and the exit knobs in config/config.json |
Golden-file tests show exactly which recorded decisions your change alters. |
| Tighten or loosen risk | config/config.json for the numbers, src/guard/ for the rules |
tests/factories.config() is derived from the shipped file, so the suite tests your numbers. |
| Trade a different universe | ci/fetch_universe.py for membership, config/etfs.json for the ETF sleeve, config/rotation_codes.json for sector codes |
The guard refuses any symbol outside the cycle's resolved candidate set. |
| Use a different broker | src/broker_shapes.py for the payload shapes and the prompts in docs/routine/ for the tool calls |
The core does not care where the data came from. Contract tests pin the shapes it expects. |
| Add a data source | A fetcher in ci/ that commits to data/, or a job in services/core/ |
src/ cannot import a network library, so new data always arrives as input you can replay. |
| Send alerts somewhere else | The relay functions in db/schema.sql |
Alert titles are a fixed list, so a new channel carries the same vocabulary. |
| Test an idea before it trades | ops/backtest_engine.py and the shadow ledger |
Next-open fills, costs, portfolio caps, a walk-forward split and a random-control comparison are already built. |
Two rules will save you time. Keep src/ free of network access, because the build fails otherwise. And run uv run pytest before and after every change, because the suite is the fastest reviewer you have.
mcp_server/ exposes the core's read-only commands as MCP tools, so any MCP client can ask it for a plan. It is a thin wrapper: each tool calls src.cli in-process and returns the same JSON the command line prints.
uv run --group mcp python -m mcp_server.server # stdio
claude mcp add deterministic-trader -- uv run --group mcp python -m mcp_server.server| Tool | Returns |
|---|---|
plan_fetch |
What broker data the cycle must fetch next |
decide |
The full plan: orders, protection, cancels |
reconcile |
Broker positions and orders compared with the book |
report, candidates, settled_cash |
The matching CLI command's output |
dip_recovery_decide, manual_check_decide |
The matching strategy decisions |
Each tool takes one argument, cycle: the same cycle document the CLI reads on stdin. Its JSON Schema ships in mcp_server/cycle.schema.json and is advertised to the client. Only now (ISO 8601 UTC) is required; every other key is optional and defaults to empty, so an omitted positions means no positions, not an error. Keys that are present must have the right type (object or array), and a violation is named by path before the core runs.
- It never trades. The server holds no broker credentials, fetches nothing and places no orders. You supply the broker data and you execute the plan.
- Bad input is a refusal, not a crash. A cycle missing required keys returns
{"command": ..., "error": {"code": "BAD_INPUT", "detail": ...}}. - Your numbers, not mine. By default the server uses the repo's checked-in
config/. SetDT_CONFIG_DIRto point at your own. - Glue commands are left out.
merge-fetch,shape-*,day-context-*and the dip-recovery pool and pick steps exist for the scheduled agent's own loop.
The server lives outside src/, so the core still cannot import a network library. The same not-financial-advice notice applies as everywhere else in this repo.
All times Eastern, trading days only. Every time is a setting, not a rule: move a routine and cadence.py classifies the firing by the clock it actually ran at.
| When | What | Runs on |
|---|---|---|
| 04:30 | Publish the next ten trading days of cycle slots and budgets | Supabase pg_cron → hosted core |
| 04:30–07:15 | Pre-market data job: bars, SMA, RSI, ATR, regime, in small rate-limited steps | pg_cron → hosted core |
| 07:40 | Universe Pick: the Dip Recovery watchlist | Claude routine |
| 09:40 | Full cycle: reconcile, exits, entries | Claude routine |
| 10:00–15:30, every 30 min | State-change gate: one quote batch, wakes a monitor only if a position is near a level | pg_cron → hosted core |
| 11:47, 12:47, 18:00 | Dip monitor (only matters when the sleeve is on) | Claude routine |
| 15:07 | Monitor cycle | Claude routine |
| 18:47 | Post-close: reconcile, benchmark row, Friday scorecard | Claude routine |
| 22:47 | Overnight: exits only | Claude routine |
| Every minute | Alert relay, stalled-cycle and over-budget watchdog | pg_cron |
| Nightly | Shadow replay of stored cycles; evidence back-fill | pg_cron → hosted core |
| Half-hourly | 8-K and FRED extraction | GitHub Actions |
| Weekly / monthly | S&P 500 membership; Leaders shadow record | GitHub Actions |
Nothing depends on a machine you own being awake.
src/ the deterministic core (no network, enforced by test)
cadence.py which kind of cycle this is
universe.py membership and candidate set
regime.py market and sector regime, postures
plays/ entry plays, exits, protection, top-ups
dip_recovery/ the Dip Recovery sleeve
core_sleeve.py idle cash in one broad ETF
sizing.py the capital ladder
guard/ every reason an order is refused
reconcile.py broker truth against the book
report.py benchmark, scorecard, alerts
cli.py the command-line surface
mcp_server/ optional MCP wrapper over the read-only commands
services/core/ the core as Vercel functions, plus pre-market, watch,
schedule, shadow and evidence jobs
api/ thin Vercel entry points
ci/ GitHub Actions fetchers: 8-K, FRED, universe
config/ everything you tune by hand
data/ snapshots committed by CI
db/ schema.sql, the whole Supabase database in one file
ops/ control CLI and the research scripts
docs/ tuning reference, design, routine setup and prompts
scripts/ the guided installer
tests/ the offline suite, fixtures and golden files
| Document | Read it for |
|---|---|
docs/TUNING.md |
Every knob on all three control surfaces |
docs/ROTATION_CODES.md |
Every sector, sub-industry and basket code |
docs/DESIGN.md |
The design; the § section numbers cited in code comments refer to it |
docs/routines.md |
Every Claude routine: name, cron, prompt file and the instruction to paste |
docs/OPERATIONS.md |
What each alert title means and what to do about it |
docs/routine/runner-prompt.md |
The contract the trading routine follows |
services/core/README.md |
The hosted core and its deployment |
SECRETS.md, SECURITY.md, CONTRIBUTING.md |
Where secrets live, how to report a vulnerability, how to contribute |
Issues and pull requests are welcome. Read CONTRIBUTING.md first: it is short, and it explains the two things every change has to respect (no network in src/, and a green uv run pytest). Report anything that could move money unexpectedly through SECURITY.md, not a public issue.
If this repo saved you time, a star helps other people find it.
Released under the MIT License.