Trading OS

trading-os is a multi-agent quantitative trading research and execution system designed for Codex and Claude Code. It gives agentic coding tools a structured operating environment for data work, research, strategy ingestion, backtesting stubs, risk review, reporting, and execution preparation.

It remains a normal Python project. Tests and workflows can run directly from the terminal, while Codex or Claude Code can use the repository structure, agent roles, schemas, and policy files to operate the system with clearer boundaries.

It is not a live trading bot. The current implementation is a local, safety-first scaffold with adapter stubs for Massive, SEC EDGAR, FRED, QuantConnect, and IBKR.

Designed For Codex And Claude Code

The project is organized so agentic coding tools can inspect intent, choose the right workflow, edit safely, and leave auditable artifacts.

• AGENTS.md defines the operating rules, authority boundaries, and do-not-do list.
• system/agents/ separates responsibilities across 10 named agents.
• system/schemas/ gives structured contracts for strategies, orders, signals, reports, risk, and promotion.
• config/ keeps policy decisions explicit instead of hidden in code.
• workspace/ is temporary working state, while persistent/ is the reviewed asset library.
• RiskControlAgent and OrderSchema keep trading actions behind explicit validation gates.
• Every Codex or Claude Code session should start through LeaderAgent with make leader TASK="...".
• LeaderAgent defaults to full_team mode and creates an auditable delegation plan across the nine subagents.
• Terminal commands such as make test, make daily, and make strategy-ingestion still work without Codex or Claude Code.

What This System Does

• Coordinates 10 specialized agents through LeaderAgent.
• Routes agentic tool sessions through LeaderAgent first, then calls the full subagent team by default.
• Converts research and strategy ideas into structured candidate assets.
• Builds local quick backtest artifacts and QuantConnect-oriented code stubs.
• Keeps workflow output in workspace/ until it is reviewed.
• Promotes only approved long-term assets into persistent/.
• Enforces RiskControlAgent gates before paper or live-related workflows.
• Rejects natural language orders and accepts only structured OrderSchema payloads.
• Keeps paper mode as the default and blocks live trading unless every explicit gate is passed.

Core Agents

Agent	Responsibility
LeaderAgent	Orchestrates workflows, assigns skills, reviews candidates, and controls promotion.
DataAgent	Prepares market, news, macro, broker, and reference data packets.
ResearchAgent	Produces structured facts, interpretations, signals, risk flags, and confidence values.
StrategyAgent	Ingests external strategy ideas and manages strategy lifecycle assets.
QuantEngineeringAgent	Generates Python, schemas, local tests, and strategy implementation stubs.
QuantConnectAgent	Prepares QuantConnect project, backtest, object store, and deployment artifacts.
PortfolioCapitalAgent	Tracks capital views, liquidity, allocation, FX exposure, and sizing guidance.
RiskControlAgent	Enforces limits, approval gates, broker safety, key-leak checks, and rejection authority.
BrokerExecutionAgent	Handles paper-safe broker snapshots, structured orders, fills, and execution reports.
ReportingAgent	Produces daily, weekly, strategy, risk, capital, execution, and decision reports.

Workflows

Workflow	Output
Leader bootstrap	LeaderAgent packet, full-team delegation plan, and agent trace.
Daily workflow	Data packet, research packet, risk packet, signal file, and report candidate.
Strategy ingestion	Parsed strategy package, metadata, risk file, source, and QuantConnect stub.
Backtest workflow	Local experiment candidate with params, cost model, slippage model, results, and review.
Paper trading preparation	Paper-mode execution preparation with risk and approval gates.
Live trading preparation	Disabled by default and blocked unless risk, human, and config gates all pass.

Repository Layout

trading-os/
  system/          agents, skills, workflows, schemas, runtime
  config/          policies, risk limits, broker mode, data sources
  workspace/       temporary runs, handoff packets, scratch, promotion queue
  persistent/      promoted long-term assets, organized by asset type
  quantconnect/    QuantConnect-oriented algorithm and model stubs
  integrations/    Massive, SEC EDGAR, FRED, IBKR, QuantConnect adapters
  outputs/         generated signals, reports, orders, exports
  logs/            workflow, risk, broker, promotion, and system logs
  tests/           schema, risk, promotion, workflow, security, integration tests
  docs/            architecture, operating manual, policies, integration notes

Quick Start

python -m venv .venv
source .venv/bin/activate
pip install -e .
make test

Start a Codex or Claude Code session through LeaderAgent:

make leader TASK="describe the current request"

This writes leader_packet.json, delegation_plan.json, and agent_trace.json under workspace/active_runs/<workflow_id>. These generated runtime files are local-only and ignored by Git.

Run the local daily workflow:

make daily

Create a strategy ingestion candidate:

make strategy-ingestion

Configuration

Copy .env.example to .env.local for local-only settings:

cp .env.example .env.local

Keep real credentials out of Git. The repository ignores .env, .env.*, broker snapshots, generated orders, runtime logs, and personal capital or ledger files by default.

External API requests are disabled unless explicitly enabled:

EXTERNAL_API_REQUESTS_ENABLED=false
LIVE_TRADING_ENABLED=false
BROKER_MODE=paper

Safety Model

trading-os treats execution as a gated workflow, not a chat command.

• RiskControlAgent rejection cannot be overridden by LeaderAgent.
• Subagents cannot write directly to persistent/.
• Promotion requires schema checks, source validation, metadata, policy compliance, and audit logging.
• Live orders require risk_approved=true, human_approved=true, and explicit live configuration.
• Natural language orders are rejected.
• Real credentials and account snapshots are treated as local-only data.

Test Coverage

The current tests cover:

• schema validation
• promotion boundaries
• subagent write restrictions
• broker mode defaults
• live approval gates
• natural language order rejection
• workflow output creation
• credential redaction and committed secret checks

Run:

make test

Roadmap

• Replace adapter stubs with read-only Massive, FRED, SEC EDGAR, QuantConnect, and IBKR clients.
• Add richer experiment comparison and strategy registry review.
• Expand portfolio construction and capital allocation rules.
• Add reporting templates for daily, weekly, strategy, risk, capital, and execution review.
• Keep live trading behind explicit configuration, human approval, and RiskControlAgent gates.

Disclaimer

This project is for research, automation design, and paper-trading preparation. It does not provide financial advice and does not execute live trades by default. Use it only with credentials, broker access, and capital controls you fully understand.