tradingcodex 0.1.0

Codex-native trading harness with a Django service plane and MCP execution boundary.

Quick Start | Features | Web Dashboard | Workflow | Roles | Architecture | Safety | Documentation

---

TradingCodex: Codex-Native Trading Harness

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.

Product Concept

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:

Plane	What it gives you
Codex control plane	A generated Codex workspace with one head-manager, nine specialist subagents, role prompts, repo skills, hooks, and project-scoped MCP config.
Workspace file plane	Human-readable research markdown, source snapshots, strategy skills, policy exports, and generated ./tcx wrappers inside the user's Codex workspace.
Django service plane	Local durable services for policy, orders, approvals, portfolio state, audit, workflows, MCP registry, external router review, API, Admin, and product web.
MCP execution boundary	Typed tools, role allowlists, policy checks, approval checks, idempotency, adapter submission, and ledgered results for executable actions.

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

~/.tradingcodex/state/tradingcodex.sqlite3

What TradingCodex Does

TradingCodex 0.1.0 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.
• Experimental paper/stub order lifecycle support: validate intent, create approval receipt, submit approved order, cancel approved order, and record outcomes.
• A local product web surface for browsing agents, skills, research markdown, external MCP router 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 router gate that imports discovery metadata, classifies tool risk, scopes role access, and blocks unsafe direct proxy paths by default.

Quick Start

Choose an empty target directory for the generated Codex workspace. Source checkouts of this repository are for TradingCodex development; generated TradingCodex workspaces are separate Codex projects.

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

Install TradingCodex and attach it to a user-selected workspace:

mkdir -p /path/to/target-workspace
cd /path/to/target-workspace
curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- .

Run the smoke check:

./tcx doctor

After installation, fully quit and restart Codex, then open the generated workspace and start from 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/

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 python install 3.14
uv tool install --python 3.14 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:

cd /path/to/target-workspace
curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- --update .

Local Web Dashboard

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, external MCP router metadata, 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.

How A Workflow Moves

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, limits, restricted symbols, and approval readiness.
6. If an executable paper/stub action is requested, risk-manager creates the approval receipt 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.

Role Roster

Layer	Agent	Role summary
Main agent	head-manager	Dispatches specialist roles, preserves constraints, and synthesizes completed artifacts.
Analysis subagent	fundamental-analyst	Reviews business quality, financial evidence, company fundamentals, and source claims.
Analysis subagent	technical-analyst	Reviews price action, trend structure, levels, and market behavior.
Analysis subagent	news-analyst	Tracks news, catalysts, events, and freshness-sensitive context.
Market-context subagent	macro-analyst	Covers macro, rates, FX, commodities, policy, and cross-asset context.
Market-context subagent	instrument-analyst	Supports ETF/index, options, crypto market structure, and instrument-level work.
Decision-review subagent	valuation-analyst	Reviews valuation assumptions, sensitivity, and decision-quality gaps.
Portfolio subagent	portfolio-manager	Reviews portfolio fit, sizing, exposure, and draft order readiness.
Risk subagent	risk-manager	Reviews downside, policy constraints, restricted lists, and approval readiness.
Execution subagent	execution-operator	Handles approved paper/stub execution through TradingCodex MCP only.

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

Architecture

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:

Surface	Role
Product web	Agents-first review dashboard for roles, skills, research markdown, external MCP router review, starter prompts, and local status.
Django Admin	Local/staff DB inspection for policy, orders, portfolio, MCP registry, workflows, integrations, and audit rows.
Django Ninja API	Typed local/staff REST and control endpoints.
MCP	Agent/tool boundary with typed tools, role scopes, policy checks, and audit.
CLI	Local operator commands and generated workspace wrapper behavior.

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.

Safety Boundary

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.

Supported Workflow Scope

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.

Release Status

0.1.0 is the first stable public contract 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.

Documentation

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

Contributing

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

License

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.