Research in Codex, with a trail you can inspect.

TradingCodex is a local-first investment operating system for Codex. Ask a question in natural language, let a bounded fixed-role team gather and challenge evidence, then keep the resulting research, source posture, uncertainty, and next steps in your own workspace.

It is not an autonomous trading bot. A research response never becomes a broker action on its own.

Get started · Data sources and OpenBB · All user-facing skills · Provider to order · Documentation

Start Here

  1. Attach an empty workspace. TradingCodex creates the local contract, launcher, skills, hooks, and research folders without creating a commit or remote.
  2. Open a new native Codex task. Start with the outcome you need, not with a preselected analyst or agent.
  3. Inspect the evidence. Read saved artifacts in the read-only workspace viewer, then continue, narrow the question, or stop.

You need Git, uvx, and an installed, authenticated codex CLI. In the empty folder where you want research to live, run:

cd /path/to/your/empty-workspace
uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
./tcx service ensure

On native Windows PowerShell:

cd C:\path\to\your\empty-workspace
uvx --refresh --from tradingcodex tcx attach .
.\tcx.cmd doctor
.\tcx.cmd service ensure

Then fully restart Codex, open and trust that workspace, and start a new task. The local viewer is available at http://127.0.0.1:48267/. End users do not need Node, npm, or a separate frontend server.

[!IMPORTANT] To set up a user workspace, use tcx attach in the target folder. Do not clone this source repository into that workspace.

Choose Your Path

What you want to do Start with What happens next
Investigate a company, thesis, event, portfolio fit, or risk question $tcx-workflow Head Manager chooses the smallest useful fixed-role team and returns evidence-backed artifacts or a clear waiting, revise, or blocked state.
Make an ambiguous request concrete $tcx-plan Clarify scope, allowed actions, and stop conditions; use the resulting mandate in a new workflow task.
Review a past decision or validate a lesson $tcx-memory Replay from point-in-time evidence and distinguish decision quality from outcome quality.
Create a reusable method or reasoning framework $tcx-strategy or $tcx-brain Start directly with the matching skill in the normal Research profile; its current-turn scope cannot grant execution authority or cross into generic Build work.
Monitor work on a schedule $tcx-automate Create or update a Codex Scheduled Task that invokes the actual work skill on each run.
Open the viewer or recover a workspace The Viewer and Wiki links shown when a healthy workspace task starts, or $tcx-server Follow the read-only links directly; use the server skill for readiness checks and safe recovery guidance.
Configure optional OpenBB data access Data sources OpenBB is projected by default as a non-required direct MCP; use `tcx data-sources openbb status
Connect a provider and prepare an order Provider to order Keep provider setup, account sync, ticket creation, checks, approval, and final action as separate checkpoints.

There are 13 user-facing skills. Browse their detailed behavior, examples, and boundaries in the User Guide.

Run Your First Research Task

In a new native Codex task, use the workflow skill and state both your desired outcome and the boundaries that must remain in force:

$tcx-workflow
Analyze MSFT as a medium-term quality compounder. Separate facts, inferences,
and assumptions. Include contrary evidence and invalidation conditions. No order.

Narrow trusted questions can stay direct. Fresh research begins a lightweight, workspace-bound run; Head Manager selects only useful specialist profiles, uses bounded fallback when necessary, and reassesses from accepted evidence before answering, synthesizing, revising, or stopping on a gap.

How TradingCodex Is Organized

Layer What it does What it does not do
Native Codex task Interprets the request, takes a direct fast path when sufficient, and uses specialist profiles or a bounded generic child only when needed. It does not turn ordinary prose, a child, or a skill into policy, approval, broker, or execution authority.
Workspace Holds readable research, reports, source snapshots, skills, prompts, and lightweight run provenance. It is not the portfolio, order, account, approval, or secret ledger.
Django service Enforces artifact identity, policy, approval, broker, idempotency, execution, and audit rules through shared application services. It does not replace Codex with a semantic router, preset team, or stored workflow DAG.
Read-only viewer Lets you browse Library artifacts, Skills, System posture, and registered workspaces. It does not launch Codex, write workspace files, or mutate orders, brokers, skills, or policy.

What You Keep

TradingCodex keeps the work inspectable after the chat ends:

  • Research handoffs and evidence under trading/research/.
  • Role reports under trading/reports/.
  • Source snapshots, point-in-time posture, forecasts, and decision-memory artifacts that explain what was known and when.
  • A read-only viewer with Library, Skills, and System sections for the attached workspace.

The workspace is yours to read, back up, diff, and version. The service keeps execution-sensitive runtime state in its central local ledger instead of hiding that state in prompts or workspace files.

Safety by Design

  • Research, planning, memory, and automation do not imply broker authority.
  • Provider connection, ticket drafting, checks, risk approval, and final order action are deliberately separate steps. The built-in provider is Paper; live adapters remain blocked until every documented gate is satisfied.
  • Fixed roles have bounded tools and handoff responsibilities. A final order path is available only from an exact root-native protocol, never from the viewer, a subagent, public REST, generic CLI, or direct MCP call.
  • Relevant user-installed MCP servers and skills remain BYOR native Codex capabilities. One relevant capability can be used for evidence without becoming TradingCodex-managed. OpenBB is the one TradingCodex-supported external data integration: it is optional, projected directly to evidence roles, and still subject to upstream licenses and data terms.
  • Raw credentials do not belong in prompts, workspace files, reports, API/MCP output, or audit data.

TradingCodex provides research workflow and execution guardrails. It is not financial, investment, legal, tax, or regulatory advice, and it does not guarantee returns.

Learn More

Read this When you need
User Guide Setup, examples, concepts, all user-facing skills, and provider-to-order onboarding.
Installation Install variants, updates, runtime homes, MCP/service startup, and recovery.
User-facing skills The full skill map, entry rules, and hard stops.
Data sources and OpenBB Source routing, direct optional OpenBB projection, Snapshot/Dataset evidence, and third-party terms.
Research memory and artifacts Artifact paths, source posture, versions, quality labels, forecasts, and exports.
Decision memory Replay, postmortems, lesson validation, and reusable context.
Safety policy and execution Permissions, approvals, brokers, secrets, and execution boundaries.
Documentation index The complete product and maintainer documentation map.

Developing TradingCodex

This repository is product source, not a user workspace. Start with CONTRIBUTING.md, then follow the validation route for your change in docs/validation-and-test-plan.md.

License

TradingCodex is an Apache-2.0 open-core project. See LICENSE, NOTICE, and TRADEMARKS.md.