Madrox - Multi-Agent Orchestrator for Claude & Codex

Python 3.11+ License: MIT Tests Code style: ruff

An MCP server that lets AI instances spawn and manage hierarchical networks of Claude and Codex agents. Build recursive multi-level teams with bidirectional communication, role specialization, task interruption, and real-time monitoring — all orchestrated through tmux sessions.

Why Madrox?

Capability Claude Subagent Madrox
Hierarchy depth 2 levels (flat) 3+ levels (recursive)
Models Claude only Claude + Codex
Interruption Must terminate & restart Stop & redirect, keep context
Visibility Black box Full tree view, metrics, dashboard
Parallel ops Sequential only Batch spawn/message/interrupt
Communication One-way (parent → child) Bidirectional + peer-to-peer
Workspace Shared Isolated per-instance
Resource tracking None Tokens, cost limits, auto-cleanup

Plugin Installation (Recommended)

The fastest way to get started — install Madrox as a Claude Code plugin:

# Install from local clone
/plugin install /path/to/madrox

After installing, restart your Claude Code session. All Madrox MCP tools become available automatically. The plugin starts the HTTP backend (port 8001) and the monitor dashboard (port 3002) in the background.

Use the /madrox:dashboard skill to open the real-time monitor dashboard in your browser.

Prerequisites: Python 3.11+, tmux, uv, npm

Quick Start (Manual)

# 1. Install
git clone https://github.com/barkain/madrox.git && cd madrox
uv sync && source .venv/bin/activate

# 2. Start (backend + dashboard)
./start.sh

# 3. Register with Claude Code
claude mcp add madrox http://localhost:8001/mcp --transport http

Then ask Claude Code to spawn a madrox dev team from template — or see examples/ for scripted usage.

Documentation

Topic Link
Installation & setup docs/SETUP.md
Architecture & design docs/ARCHITECTURE.md
API reference (24+ MCP tools) docs/API_REFERENCE.md
Features & usage patterns docs/FEATURES.md
Troubleshooting docs/TROUBLESHOOTING.md
Team templates docs/TEMPLATES.md
Examples examples/

Contributing

See CONTRIBUTING.md. Run uv run pytest tests/ -v and uv run ruff check src/ before submitting.

License

MIT — see LICENSE.