mrx

Multi-role model orchestration CLI — assign different LLMs to reasoning, execution, and tool-calling roles in a single session.

Why mrx

• Role separation: Use a powerful reasoning model for planning and a fast model for output — independently configurable
• Provider-agnostic: OpenAI, Anthropic, Google, Ollama, LM Studio, OpenRouter all work out of the box
• Zero lock-in: One YAML file controls everything; switch models or providers without changing any code

Quick Start

npm install -g mrx
mrx ask "explain recursion"

Or without installing:

npx mrx ask "explain recursion"

Installation

Global install:

npm install -g mrx

One-off via npx:

npx mrx ask "your prompt"

Local clone:

git clone https://github.com/Varun-SV/mrx.git
cd mrx
npm install
npm run dev -- ask "your prompt"

Configuration

Place mrx.config.yaml in your current directory or ~/.mrx/mrx.config.yaml.

default_mode: think_then_answer

session_memory: true
session_db_path: ~/.mrx/sessions.db

models:
  reasoner:
    provider: ollama
    model: qwen3:14b
    temperature: 0.6
    maxTokens: 8192

  executor:
    provider: openai
    model: gpt-4o-mini
    temperature: 0.7
    maxTokens: 4096

  # Optional dedicated tool-caller (falls back to executor)
  tool_caller:
    provider: openrouter
    model: google/gemini-flash-1.5
    temperature: 0.2

tools:
  shell: true
  file_system: true
  web_fetch: true

display:
  show_reasoning: false
  stream: true

See mrx.config.example.yaml for a fully annotated example.

Providers

| Provider | Env var | Notes | |---|---|---| | openai | OPENAI_API_KEY | | | anthropic | ANTHROPIC_API_KEY | | | google | GOOGLE_API_KEY | | | ollama | — | Requires ollama pull <model> locally | | lmstudio | — | Requires LM Studio server running on port 1234 | | openrouter | OPENROUTER_API_KEY | |

Override the API key per-model with apiKey: in the config.

Interaction Modes

think_then_answer (default)

Reasoner generates a chain-of-thought, then executor produces the final response using the reasoning as context. Best for complex questions needing careful analysis.

mrx ask "what are the tradeoffs between microservices and monoliths?"

planner_executor

Reasoner produces a numbered execution plan, then executor works through each step, and finally synthesizes the results. Best for multi-step tasks.

mrx ask "refactor this codebase to use async/await" --mode planner_executor

manual

You prefix messages with @reasoner, @executor, or @tool_caller to route to specific models. Defaults to executor.

mrx chat  # then type: @reasoner analyze this design

CLI Reference

| Command | Description | |---|---| | mrx ask <prompt> | One-shot prompt, prints response | | mrx chat | Start interactive TUI session | | mrx sessions | List saved sessions | | mrx check | Validate config |

| Flag | Description | |---|---| | -m, --mode <mode> | Interaction mode (think_then_answer, planner_executor, manual) | | -c, --config <path> | Path to config file | | --show-reasoning | Print reasoning trace (ask only) | | -s, --session <id> | Resume session by ID (chat only) |

TUI Keybindings

| Key | Action | |---|---| | Enter | Send message | | Ctrl+M | Cycle interaction mode | | Ctrl+R | Toggle reasoning display | | Ctrl+C | Quit |

Tools

| Tool | Description | |---|---| | run_shell | Executes a shell command. Only active when tools.shell: true. | | read_file | Reads a file (100 KB max). | | write_file | Writes a file, creating parent dirs. | | list_directory | Lists directory contents. | | web_fetch | Fetches a URL and returns plain text (50 KB max). |

Safety note: shell: true allows the model to run arbitrary commands. Only enable in trusted environments.

Session History

Enable with session_memory: true in config. Sessions are stored in SQLite at session_db_path.

mrx sessions                  # list sessions
mrx chat --session <id>       # resume a session

Contributing

See CONTRIBUTING.md.

License

MIT © Varun-SV