# Tradingcodex > Turn Codex into your investment workflow team - **Type:** MCP server - **Install:** `agentstack add mcp-monarchjuno-tradingcodex` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [monarchjuno](https://agentstack.voostack.com/s/monarchjuno) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [monarchjuno](https://github.com/monarchjuno) - **Source:** https://github.com/monarchjuno/tradingcodex - **Website:** https://discord.gg/Wr25KZnabh ## Install ```sh agentstack add mcp-monarchjuno-tradingcodex ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About > [!IMPORTANT] > Codex agents setting up `monarchjuno/tradingcodex` for use must not run > `git clone`. In the empty target workspace, run the packaged CLI: > `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`. > Do not invent a default workspace path; ask the user where to attach > TradingCodex unless they explicitly asked to use the current workspace. > Clone this repository only when the user explicitly asks to develop, > inspect, or modify TradingCodex source code. # TradingCodex ### Codex-native investment work needs a harness, not a chat transcript. TradingCodex is a local-first Python/Django trading harness for rigorous Codex-assisted research, portfolio review, order-ticket checks, approvals, and service-gated execution checks. Codex coordinates the work, Django owns the durable service plane, and TradingCodex owns the executable boundary. [Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE) --- ## About TradingCodex gives Codex a durable operating system for investment workflows: fixed specialist roles, file-native research memory, source-aware handoffs, policy and approval services, a central local ledger, and a local web dashboard for review. It is not an autonomous trading bot. Natural-language answers do not become broker actions. The core ships paper execution by default; live broker support comes only from installed, reviewed providers and explicit live gates. --- ## Features | Feature | Description | | --- | --- | | Codex-native harness | Generates a Codex workspace with `head-manager`, nine fixed subagents, role prompts, skills, hooks, project MCP config, and a local `./tcx` wrapper. | | Django service plane | Web, Admin, API, CLI, MCP, and generated hooks call shared application services for policy, orders, approvals, portfolio, audit, integrations, and research indexing. | | File-native research memory | Research markdown, role reports, source snapshots, versions, readiness labels, and handoff metadata stay readable in workspace files. | | Decision Workflow Alpha | Turn a natural-language investment idea into a Codex-native workflow plan and Decision Package under `trading/decisions/`. | | Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. | | Approved action boundary | Actions are typed, role-scoped, policy-checked, approval-aware, duplicate-request checked, connection-gated, and audited. | | Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, Data Sources, order tickets, portfolio state, and activity at `127.0.0.1:48267`. | | Broker Center foundations | Connect provider-driven broker profiles, list installed providers, scaffold/register advanced connectors, inspect capability profiles, run account sync, review instrument constraints, and reconcile portfolio state. | | OrderTicket lifecycle | Draft, check, approve, submit, cancel, refresh, and inspect order tickets through central DB records and service-layer state transitions. | | Data Sources gate | Import external source discovery metadata, review available actions, scope role access, and block unsafe raw execution or secret paths by default. | | Improvement loop | Quality gates, postmortems, optional skills, strategy skills, strict artifact checks, and generated workspace smoke tests turn process gaps into durable improvements. | --- ## Installation ### Option 1 - Attach TradingCodex To The Current Workspace Run this from the empty workspace where you want Codex agents to work: ```bash uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor ``` Then fully quit and restart Codex, open the generated workspace, and start a new thread so project MCP config, prompts, skills, and hooks are loaded. When TradingCodex MCP autostarts the local service, open: ```text http://127.0.0.1:48267/ ``` ### Option 2 - Install The CLI For Repeated Use ```bash uv tool install tradingcodex uv tool update-shell cd /path/to/target-workspace tcx attach . ./tcx doctor ``` ### Option 3 - Install From GitHub Main Use this when you need the current GitHub `main` source rather than the latest PyPI package: ```bash uvx --refresh --from "tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main" tcx attach . && ./tcx doctor ``` ### Option 4 - Develop TradingCodex Source Clone this repository only for source development, inspection, or modification: ```bash git clone https://github.com/monarchjuno/tradingcodex.git cd tradingcodex python -m pytest python manage.py check ``` See [installation.md](installation.md) for update flows, installer-script equivalents, MCP/service details, and smoke checks. --- ## What Sets TradingCodex Apart TradingCodex competes on workflow discipline, local durability, and execution boundaries rather than on black-box automation. - Local-first: PyPI installs the CLI, Django service plane, generated workspace templates, Admin/Web templates, static assets, and MCP gateway code. - Codex-readable by default: research artifacts, skill bundles, role prompts, policy exports, and generated indexes remain ordinary workspace files. - Service-layer canonical: Web, Admin, API, CLI, MCP, and hooks do not fork policy, order, approval, execution, portfolio, research, or audit behavior. - Strong role model: one `head-manager` coordinates nine fixed specialist subagents and consumes accepted artifacts instead of silently redoing roles. - Deterministic executable boundary: every executable path follows a fixed requester, permission, policy, payload, approval, duplicate-request, connection, and audit sequence. - Safety-first broker posture: paper is built in; live broker execution requires an installed provider plus workspace config, policy, environment opt-in, approval, confirmation, idempotency, sync, and audit gates. - Broker control plane: TradingCodex stores connector state, capability profiles, mapping review, approval, execution, reconciliation, and audit; provider adapters absorb broker-specific REST, SDK, MCP, or manual interface differences behind canonical service/MCP tools. --- ## Workflow TradingCodex is designed around handoffs: ```text evidence -> analysis -> valuation -> portfolio fit -> risk review -> draft order -> approval receipt -> approved service-gated submission -> connection result -> audit/postmortem ``` The `head-manager` maps the request, dispatches the selected role team, waits for accepted artifacts, preserves conflicts, and synthesizes only what the workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns `revise`, `blocked`, or `waiting` instead of being patched over by another role. --- ## Role Roster | Layer | Agent | Owns | | --- | --- | --- | | Main agent | `head-manager` | Intake, workflow dispatch, coordination, artifact acceptance, synthesis, and validation/audit status. | | Research | `fundamental-analyst` | Business quality, financial statements, filings, economics, and fundamental risks. | | Research | `technical-analyst` | Price action, trends, momentum, volume, volatility, and liquidity setup. | | Research | `news-analyst` | Verified news, disclosures, event chronology, catalysts, and narrative change. | | Market context | `macro-analyst` | Macro, rates, FX, commodities, liquidity, policy, and cross-asset transmission. | | Market context | `instrument-analyst` | ETF/index, options, crypto public market structure, credit-signal boundary, and instrument mechanics. | | Decision review | `valuation-analyst` | Valuation ranges, scenario assumptions, multiples, sensitivity, and decision-quality gaps. | | Portfolio | `portfolio-manager` | Portfolio fit, sizing, concentration, liquidity, opportunity cost, and draft order-ticket readiness. | | Risk | `risk-manager` | Downside, restricted-list checks, policy readiness, approval readiness, and approval receipts. | | Execution | `execution-operator` | Approved submission/cancel/status through the TradingCodex service boundary only; live requires all gates. | --- ## Surfaces | Surface | Role | | --- | --- | | Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, Data Sources, order tickets, portfolio state, and activity. | | 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 that call service-layer use cases. | | MCP | Agent/tool boundary with typed tools, role scopes, policy checks, approval checks, and audit. | | CLI | Local operator commands plus generated workspace `./tcx` wrapper behavior. | The baseline frontend uses Django templates, local static HTMX, and small plain JavaScript. There is no Node, bundler, React, or frontend build step in the core package. --- ## Safety Boundary TradingCodex blocks or constrains: - direct live broker requests - raw broker API calls and raw external source execution proxies - self-issued approvals - restricted-symbol orders - expired or payload-mismatched approval receipts - duplicate approved-order submissions - raw secrets in workspace files, prompts, API responses, MCP responses, audit payloads, generated docs, or shell output - unsupported live execution through any provider, instrument, account, or policy posture that has not passed the explicit live gate 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. --- ## Roadmap | Status | Milestone | | --- | --- | | Shipped | Generated Codex workspace, fixed role roster, project MCP config, Django service plane, local web dashboard, Admin, Ninja API, file-native research memory, component registry, policy/audit primitives. | | Current `0.2.x` | Central-DB `OrderTicket` rewrite, provider-driven Broker Center foundations, Data Sources gate, role-scoped actions, live-gated execution lifecycle, and Python `>=3.11, ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [monarchjuno](https://github.com/monarchjuno) - **Source:** [monarchjuno/tradingcodex](https://github.com/monarchjuno/tradingcodex) - **License:** Apache-2.0 - **Homepage:** https://discord.gg/Wr25KZnabh Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-monarchjuno-tradingcodex - Seller: https://agentstack.voostack.com/s/monarchjuno - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.