MARS — Multi-Agent Resolution Synthesis

Multiple LLMs debate your question through structured rounds of argumentation, critique, and synthesis to produce a single, well-reasoned answer.

Installation

Requires Python 3.10+.

pip install mars-llm

Quick Start

1. Configure your API keys (one-time setup):

mars configure

This walks you through setting up API keys for each provider interactively. You need at least two providers configured to run a debate.

2. Run a debate:

mars debate "What is the best sorting algorithm for nearly-sorted data?"

3. View the results:

mars show

4. Check provider status anytime:

mars providers

CLI Reference

mars debate PROMPT [OPTIONS]

Run a multi-LLM debate on PROMPT. PROMPT can be plain text or @file to read from a file.

mars configure

Interactive setup for API keys and integrations. Prompts for each provider's API key, validates it, and stores keys in ~/.mars/config. Optionally sets up Claude Code integration.

mars providers

List configured providers with their default models and configuration status.

mars show [SUBCOMMAND]

View results of a completed debate. With no subcommand, shows a compact summary.

mars history

List past debates with timestamps, providers, rounds, and costs.

mars copy

Copy the final answer to the system clipboard.

Configuration

MARS looks for API keys in three places (highest priority wins):

This means you can set keys globally with mars configure and override them per-project with a local .env file if needed.

Providers

Override models per-run with -p provider:model or --model provider:model.

Vertex AI (Google Cloud)

Vertex AI acts as a gateway to both Claude and Gemini models through a single authentication mechanism (Application Default Credentials).

Setup:

gcloud auth application-default login
mars configure   # enter your GCP project ID and region

Use -p vertex:model to specify models. The same vertex provider routes to Claude or Gemini based on the model name:

# Claude via Vertex
mars debate "Question" -p vertex:claude-sonnet-4 -p openai

# Gemini via Vertex
mars debate "Question" -p vertex:gemini-2.5-flash -p openai

# Both Claude and Gemini via Vertex
mars debate "Question" \
  -p vertex:claude-sonnet-4 \
  -p vertex:gemini-2.5-flash

Vertex AI config variables:

Auto-detected from ANTHROPIC_VERTEX_PROJECT_ID, GOOGLE_CLOUD_PROJECT, and CLOUD_ML_REGION if set.

Default Providers

Set default providers so you don't need -p every time:

mars configure   # prompted at the end for default providers

Or set MARS_DEFAULT_PROVIDERS directly:

export MARS_DEFAULT_PROVIDERS="vertex:claude-opus-4-6,vertex:gemini-2.5-flash"

Debate Modes

Round-Robin (default)

All providers answer the prompt independently. Each provider then critiques the others' answers and produces an improved response. This repeats until answers converge (similarity exceeds --threshold) or max rounds are reached. A final synthesis step merges the best points into one answer.

Judge

All providers answer independently. A designated judge provider (-j) evaluates every response and produces a final ruling with resolution reasoning.

mars debate "Is Rust better than Go for CLI tools?" \
  -p openai -p anthropic -p google \
  -m judge -j anthropic

Examples

Basic two-provider debate:

mars debate "What are the trade-offs between microservices and monoliths?"

Three providers with model overrides:

mars debate "Design a rate limiter" \
  -p openai -p anthropic -p google \
  --model openai:gpt-4.1 --model anthropic:claude-opus-4-20250514

Using context files:

mars debate @question.md -c @codebase-summary.txt -c @requirements.txt

Vertex AI — Claude vs Gemini:

mars debate "Best practices for API versioning" \
  -p vertex:claude-sonnet-4 \
  -p vertex:gemini-2.5-flash -v

Tuning convergence and temperature:

mars debate "Optimal database indexing strategy" \
  -p openai -p anthropic \
  --threshold 0.70 -t 0.3 -r 5

Reviewing results after a debate:

mars show                    # summary of most recent debate
mars show answer             # just the final answer
mars show costs              # cost breakdown
mars history                 # list all past debates
mars history -n 5            # last 5 debates
mars copy                    # copy final answer to clipboard
mars copy --full             # copy prompt + answer + attribution

Output Structure

Each debate produces a timestamped directory:

mars-output/<timestamp>_<slug>/
├── final-answer.md
└── audit/
    ├── 00-prompt-and-context.md
    ├── 01-round-1-responses.md
    ├── 02-round-2-critiques.md
    ├── 03-round-3-critiques.md
    ├── attribution.md
    ├── costs.md
    ├── round-diffs.md
    ├── convergence.md
    └── resolution.md

Analysis Output

Attribution

Three metrics per provider, computed via sentence-level similarity:

• Contribution — percentage of final answer sentences traced to this provider (best-match attribution above threshold).
• Survival — percentage of this provider's round-1 sentences that appear in the final answer.
• Influence — rate at which other providers adopted this provider's sentences in subsequent rounds.

Cost Tracking

Token counts (input + output) and estimated USD cost per provider. Pricing uses prefix-matched model lookup (e.g., claude-sonnet-4-20250514 matches claude-sonnet-4 pricing). Ollama models show zero cost.

Claude Code Integration

mars configure detects Claude Code and offers to install /mars:debate as a slash command. Once installed, you can run debates from any Claude Code session:

/mars:debate What is the best approach to database sharding?
/mars:debate Compare Kubernetes vs Docker Swarm for container orchestration

Claude Code will check your configured providers, run the debate with streaming output, and summarize the result.

Configuration Tips

Temperature: 0.0 for deterministic/factual answers, 0.7 for creative tasks, 1.0+ for experimental diversity. Each provider uses its own default when -t is omitted.

Convergence threshold: Lower values (e.g., 0.70) stop debate sooner when answers are roughly similar. Higher values (e.g., 0.95) force more rounds of refinement. Default 0.85 balances quality and cost.

Synthesis provider: By default, MARS prefers Anthropic then OpenAI for synthesis. Use -s to override.

Retries: All provider calls retry up to 3 times with exponential backoff on transient errors (timeouts, rate limits, 503s).

License

MIT