TradingCodex is a local-first trading harness for doing investment work with Codex. It gives Codex a durable operating system: role-separated agents, file-native research memory, a Django service plane, a central local ledger, and an MCP execution boundary that turns risky actions into explicit, auditable service-layer decisions.

It is not an autonomous trading bot. Codex coordinates and explains the work; Django owns durable state and policy; TradingCodex MCP is the only executable agent boundary; live broker adapters are not shipped in the initial core.

Codex app current-workspace one-liner: run this from the empty workspace you want to turn into TradingCodex. Do not run git clone for setup; cloning monarchjuno/tradingcodex is only for developing TradingCodex source code.

uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor

This installs/runs the TradingCodex CLI with a compatible Python (>=3.11,<3.15), attaches the harness to the current workspace, and runs the smoke check. Then fully quit and restart Codex, open the generated workspace, and start a new thread so project MCP config is reloaded. When TradingCodex MCP autostarts the local service, the dashboard is available at http://127.0.0.1:48267/.

Agents and install helpers do not invent a default workspace path. If the target path is not supplied and the user did not say "current workspace", ask before creating or attaching a workspace.

Start an orchestrated Codex workflow from the generated workspace:

$orchestrate-workflow analyze Apple with public equity research, valuation, portfolio, and risk review

For repeated workspace creation, install the CLI as a user-level tool:

uv tool install tradingcodex
uv tool update-shell
cd /path/to/target-workspace
tcx attach .
./tcx doctor

See installation.md for GitHub-main installs, direct uvx, MCP/service details, and additional smoke checks.

Update an existing generated workspace after a package release:

uvx --refresh --from tradingcodex tcx update .

TradingCodex exists because serious Codex-assisted investment work should not live only in a chat transcript. Research, source freshness, role handoffs, portfolio context, approvals, policy decisions, execution attempts, and audit records need a system of record that remains inspectable after the thread ends.

The product model is a harness:

Generated workspaces are Codex workbenches, not brokerage accounts. Canonical execution-sensitive state lives in the central local runtime DB:

~/.tradingcodex/state/tradingcodex.sqlite3

TradingCodex 0.2.1 provides:

• A generated Codex workspace with fixed role topology, project-scoped MCP, local wrappers, workspace manifest, generated policy/config files, and ./tcx doctor validation.
• An explicit workspace update path that refreshes generated files, applies central DB migrations, preserves workspace identity/profile state, and re-runs doctor checks.
• A role workflow model where head-manager dispatches work and specialists return bounded artifacts instead of every agent redoing every part of the investment question.
• File-native research memory: markdown artifacts, source snapshots, versioned handoffs, export/search flows, and source/as-of posture that agents and humans can both read.
• Strategy and skill management through workspace files, including strategy-* skills and role-local optional skills without weakening core role boundaries.
• Policy, restricted-symbol, approval, order, execution, portfolio, MCP, and audit services behind a shared Django application layer.
• Broker Center foundations: broker connections, broker accounts, read-only paper sync, external MCP broker discovery import, and reconciliation summaries behind the service layer.
• Canonical Order Ticket foundations: natural-language or structured draft tickets, schema/policy/cash-position/broker validation checks, state-machine events, exact approval-scope binding, broker order timeline, and paper fills.
• Experimental paper/stub order lifecycle support: check order tickets, request approval receipts, submit approved orders, cancel approved orders, and record outcomes.
• A local product web surface for browsing agents, skills, research markdown, external MCP Gate metadata, starter prompts, and operational state.
• Django Admin, Django Ninja API, CLI, and MCP surfaces that call the same service-layer logic instead of creating parallel execution paths.
• A managed External MCP Gate that imports discovery metadata, classifies tool risk, scopes role access, and blocks unsafe direct proxy paths by default.

TradingCodex includes a local Django web surface so users do not have to inspect everything through chat or CLI output. When Codex trusts a generated workspace, project MCP startup also starts the local service and exposes the dashboard at:

http://127.0.0.1:48267/

The dashboard is a review and control surface for the agent roster, required and optional skills, strategy skills, research markdown, Broker Center, External MCP Gate metadata, portfolio sync/reconciliation, order-ticket drafts/checks, starter prompts, policy/order/portfolio/activity status, and local workspace state. It does not spawn Codex agents, approve orders, submit executions, or provide investment recommendations.

For CLI-only sessions, start it manually:

./tcx service runserver

Django Admin is available separately at http://127.0.0.1:48267/admin/ for local/staff DB inspection.

TradingCodex is designed around handoffs rather than one giant answer:

1. The user asks Codex for an investment workflow.
2. head-manager classifies the request, maps the investment universe and workflow lane, and dispatches bounded work to specialist roles.
3. Analysts create evidence-backed artifacts with source/as-of posture.
4. Downstream roles consume accepted upstream artifacts instead of silently filling missing work outside their role.
5. Portfolio and risk roles review fit, sizing, broker sync/reconciliation, limits, restricted symbols, order-ticket checks, and approval readiness.
6. If an executable paper/stub action is requested, risk-manager creates an approval receipt bound to the exact order payload hash and execution-operator submits only through TradingCodex MCP.
7. Policy decisions, MCP calls, approvals, execution results, and audit events remain inspectable through local service surfaces.

The default generated workspace includes this one-plus-nine roster. The main agent coordinates and synthesizes; specialist agents own the actual role work.

TradingCodex is a Python/Django modular monolith packaged as a local-first tool. The important implementation rule is that every interface calls shared application services:

Canonical implementation lives in:

tradingcodex_service/application/
tradingcodex_cli/commands/
apps/
workspace_templates/modules/

The baseline frontend uses Django templates, local static HTMX, and local static Alpine. There is no Node, bundler, React, or frontend build step in the core package.

TradingCodex treats executable actions as a deterministic service-layer lifecycle:

principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit

Important boundaries:

• Product web routes do not spawn agents, generate investment analysis, create approvals, or submit executions.
• REST/Admin/CLI/MCP call shared Django service functions.
• Role MCP allowlists are narrow: head-manager cannot submit orders, risk-manager owns approvals, and execution-operator owns execution calls.
• Paper/stub execution remains experimental.
• Live broker adapters are not shipped in the initial core.
• Raw broker secrets must not be stored in this repository or generated workspaces.

TradingCodex is research, workflow, and execution-guardrail tooling. It is not financial, investment, legal, tax, or regulatory advice, and it does not provide investment recommendations or guarantee returns.

Public equity is the first deeply specified sleeve. The harness keeps explicit paths for ETF/index, public crypto market, macro/rates/FX/commodities, options, credit-signal, and cross-asset workflows when the required data source, role workflow, and policy boundary exist.

Unsupported or weakly sourced workflows should receive conservative readiness labels such as research-only, screen-grade, not-decision-ready, or blocked.

0.2.1 is a compatibility patch on the 0.2.x OrderTicket rewrite release line for the generated workspace, Python CLI, Django service plane, product web, MCP boundary, and documentation set. The package still uses an alpha development classifier because live broker adapters and hosted service modes are intentionally outside the initial core.

• Installation
• Docs index
• Product direction
• Core concepts and rules
• Harness model
• Roles, skills, and workflows
• Safety policy and execution
• Interfaces and surfaces
• Deployment

Contributions use Apache-2.0 with DCO sign-off. See CONTRIBUTING.md.

TradingCodex is an Apache-2.0 open-core project.

Source code, generated workspace templates, and project documentation are licensed under the Apache License, Version 2.0 unless marked otherwise. The TradingCodex name, future logos, and official product marks are not granted by the code license. See LICENSE, NOTICE, and TRADEMARKS.md.