madrox: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Development Setup

# Install dependencies
uv sync --all-groups

# Activate virtual environment
source .venv/bin/activate

Plugin Mode (Claude Code)

Madrox can be installed as a Claude Code plugin. The plugin is configured via .mcp.json and managed by start_plugin.sh.

# Install from within Claude Code
/plugin install /path/to/madrox

How it works:

• Claude Code runs start_plugin.sh on startup
• The script starts the HTTP backend (port 8001) and Next.js frontend dashboard (port 3002) in the background
• Waits for the backend health check to pass
• Runs a STDIO MCP proxy in the foreground (Claude Code connects to this)
• On exit, background processes are cleaned up automatically
• The STDIO server is a proxy — all tool calls are forwarded to the HTTP backend via HTTP

/madrox:dashboard skill: Opens the Madrox Monitor dashboard at http://localhost:3002 in the browser. Defined in skills/dashboard/SKILL.md.

Running the Server

The server supports two transport modes that are auto-detected:

HTTP/SSE Transport (Claude Code):

# Start HTTP server (default when running in terminal)
python run_orchestrator.py

# Server starts on http://localhost:8001
# Uses Server-Sent Events (SSE) for MCP protocol

STDIO Transport (Codex CLI):

# STDIO mode is auto-activated when stdin is piped
# Used by Codex CLI MCP client configuration

# Force STDIO mode via environment variable
MADROX_TRANSPORT=stdio python run_orchestrator.py

# Example Codex CLI config (~/.codex/config.toml):
# [mcp_servers.madrox]
# command = "python"
# args = ["/path/to/madrox/run_orchestrator.py"]
# env = { MADROX_TRANSPORT = "stdio" }

Quick Start with start.sh:

# Start both backend (port 8001) and frontend dashboard (port 3002)
./start.sh

# Start only the backend
./start.sh --be

# Start only the frontend
./start.sh --fe

Note: When backgrounding the backend, set MADROX_TRANSPORT=http to prevent STDIO auto-detection.