mdx-code 0.2.0

The AI Engineering Manager for your codebase.

MDx Code

The AI Engineering Manager for your codebase.

Orchestrates multiple AI coding CLIs with governance, adversarial review, audit trails, and cost tracking.

The Hook

Run the same task through two models. Get findings neither would catch alone:

$ mdx review src/auth/

  Adversarial Review: src/auth/
  ──────────────────────────────

  Claude found 4 issues    Codex found 3 issues

  Cross-validated: 2 agreed    Unique: 3

  Neither model alone found all 5 real issues.

Quick Install

curl -fsSL https://raw.githubusercontent.com/dhotherm/mdx-code/main/install.sh | bash

First-run wizard guides you through setup automatically.

Manual Install

pip install -e .
mdx setup

Why MDx Code Exists

Every AI coding CLI is a silo. Claude Code is incredible at deep reasoning. Codex is fast and cheap. Gemini handles massive context. But none of them talk to each other...none of them track what they cost you...and none of them give your security team the audit trail they need to say yes.

That's the gap. The tools are ready. The governance isn't.

If you're in a regulated environment...SOC 2, HIPAA, OSFI...you already know the problem. You can't just let 3 different AI agents push code with no cross-validation, no cost visibility, and no single source of truth. It doesn't fly.

MDx Code is the missing layer. It doesn't replace Claude, Codex, or Gemini...it orchestrates them. Routes the right task to the right model at the right cost. Runs adversarial reviews where two models cross-validate each other's work...finding bugs neither catches alone. Logs every action in a chain-hashed audit trail your compliance team can actually verify. And does all of this with less than 200ms of overhead. The wrapper is invisible.

Think of it this way...you wouldn't let 3 senior engineers push to production with no code review, no cost tracking, and no audit trail. Why would you let 3 AI coding agents do the same?

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        CLI Layer                                │
│  Commands · Flags · Typer/Click · First-run wizard · Banner     │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      Routing Layer                              │
│  Task categorization · Strategy selection · Backend profiles    │
│  Circuit breakers · Cost estimation · Budget guardrails         │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                     Backend Layer                               │
│  Claude adapter · Codex adapter · Gemini adapter                │
│  Subprocess spawning · Output streaming · Error classification  │
│  Auto-discovery · Health checks · Fallback recovery             │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                   Governance Layer                              │
│  Policy engine · Compliance matrix · Chain-hashed audit trail   │
│  Adversarial review · Finding consensus · Cost tracking (SQLite)│
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      Output Layer                               │
│  Rich streaming · Markdown detection · Footer · Budget display  │
│  NO_COLOR support · Pipe detection · Onboarding tips            │
└─────────────────────────────────────────────────────────────────┘

Commands

Command	Description
mdx "task"	Execute via best available backend
mdx "task" --pick	Interactively pick a backend
mdx "task" --backend claude	Force a specific backend
mdx "task" --strategy cost	Override routing strategy
mdx review src/	Adversarial multi-model review
mdx review --last	Review last change MDx made
mdx review --diff HEAD~1	Review a git diff
mdx cost	Spending dashboard
mdx cost --week	Weekly cost breakdown
mdx audit	Audit trail history
mdx audit --verify	Verify audit chain integrity
mdx audit --stats	Audit summary statistics
mdx history	Recent task history
mdx summary	Today's AI coding summary
mdx setup	Detect available backends
mdx status	Backend health and circuit breakers
mdx policy	View active policies
mdx policy init	Create starter .mdxpolicy
mdx policy check <files>	Check files against policies
mdx compliance	Regulatory compliance matrix
mdx hook install	Git pre-commit hook
mdx replay	Replay last task output
mdx undo	Revert last backend change
mdx mcp status	MCP server availability
mdx mcp config	Generate MCP client config
mdx install-completion	Shell tab-completion

How It Works

MDx Code does not run its own agent loop. It spawns real AI coding CLIs (claude, codex, gemini) as subprocesses, streams their output in real-time, and wraps everything with orchestration: smart routing, cost tracking, governance policies, and an immutable audit trail.

Every task execution flows through:

1. Categorize — Keyword-based task classification (no LLM call)
2. Route — Score backends using the selected strategy
3. Execute — Spawn the CLI subprocess and stream output
4. Track — Record cost (SQLite) and audit entry (chain-hashed JSONL)
5. Govern — Evaluate policies and recommend review if triggered

Key Features

• Multi-backend routing — Routes tasks to the best available CLI based on cost, quality, or balanced strategies
• Adversarial review — Run code through multiple models and cross-validate findings with consensus scoring
• Governance policies — Define per-path rules for review requirements, approval gates, and minimum reviewers
• Cost tracking — Token and dollar spend across all backends with savings analysis and budget guardrails
• Audit trail — Immutable, chain-hashed JSONL logs with SHA-256 integrity verification
• Compliance — Maps features to SOC 2, HIPAA, SOX, and OSFI regulatory frameworks
• MCP servers — Expose governance, audit, and cost data to MCP-compatible clients
• Circuit breakers — Automatic fallback when a backend is unhealthy (closed → open → half-open)

Routing Strategies

Strategy	When to Use	How It Works
balanced	Default. Best all-around.	Scores backends on quality × strength / relative cost
quality	Critical code, security-sensitive	Always picks highest-quality backend
cost	Bulk tasks, experiments	Picks cheapest available backend

See docs/routing.md for details on backend profiles, scoring formulas, and circuit breakers.

Performance

Metric	Value
Cold start	20ms (20x improvement from lazy imports)
Config loading	< 1ms (module-level cache)
Routing decision	0.1ms
Total wrapper overhead	< 200ms

The footer displays before async I/O writes (audit, cost tracking) complete — the user never waits for bookkeeping.

Governance & Compliance

Define policies in .mdxpolicy to enforce review requirements per path:

policies:
  - name: auth-critical
    paths: ["src/auth/**", "src/security/**"]
    requires:
      adversarial_review: true
      human_approval: true
    severity: critical

MDx Code maps its features to regulatory frameworks:

Framework	Coverage
SOC 2	Audit trail, access logging, change tracking
HIPAA	Audit controls, integrity verification
SOX	Approval workflows, immutable records
OSFI B-13	Model provenance, technology risk controls

Run mdx compliance to see the full compliance matrix.

Configuration

MDx Code supports three levels of configuration:

• Global — ~/.mdx/config.yaml (routing strategy, budgets, display)
• Project — .mdx.yaml in repo root (overrides global for this project)
• Governance — .mdxpolicy in repo root (policy rules)

See docs/configuration.md for all fields and example configs.

MCP Integration

MDx Code ships three MCP servers for integration with AI coding tools:

• Governance server — Policy checking and compliance data
• Audit server — Audit trail access and verification
• Cost server — Spending data and budget status

See docs/mcp-setup.md for setup instructions.

Requirements

• Python 3.11+
• At least one AI coding CLI:
  • Claude Code
  • Codex CLI
  • Gemini CLI

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

Security

See SECURITY.md for vulnerability reporting and security policy.

License

MIT