Unison - Providers Together

Unison - Providers Together
_{Formerly known as Zen MCP}

👉 Watch more examples

Your CLI + Multiple Models = Your AI Dev Team

Use the 🤖 CLI you love:
Claude Code · Gemini CLI · Codex CLI · Qwen Code CLI · Cursor · and more

With multiple models within a single prompt:
Gemini · OpenAI · Anthropic · Grok · Azure · Ollama · OpenRouter · DIAL · On-Device Model

---

What this fork adds over PAL

Unison forks BeehiveInnovations/pal-mcp-server and preserves every PAL tool, provider, and workflow. On top of that, it changes what's possible in four ways:

• 🔗 CLI-to-CLI orchestration. The new clink tool spawns seven subagents — Claude Code, Codex, Gemini CLI, opencode, Aider, Crush, and Amp — in isolated contexts with role presets, read-only enforcement (native CLI flags + post-call filesystem-snapshot diff), and a cross-cutting recursion guard for MCP-aware CLIs. PAL has no equivalent.
• 🌐 75+ providers through one integration. clink + opencode routes a single call to OpenAI, Anthropic, Google, Ollama, OpenRouter, xAI, Mistral, Groq, DeepSeek, and ~70 more via provider/model syntax. No per-provider implementation work.
• 🧠 2000+ models, auto-discovered. Every model from every authenticated provider appears at startup via LiteLLM; a weekly CI workflow opens a PR with the latest catalog. Auto-mode picks the smartest available model using intelligence_score, not hardcoded preference lists that go stale.
• 🛡️ Production reliability. Optional SQLite conversation backend survives restarts; a per-provider circuit breaker fails fast on outages so consensus doesn't hang on a dead provider.

Migration is lossless — every PAL tool, provider, and workflow is preserved. The full PAL vs Unison comparison below breaks down each capability.

---

🆕 Now with CLI-to-CLI Bridge

The new clink (CLI + Link) tool connects external AI CLIs directly into your workflow:

• Connect external CLIs like Gemini CLI, Codex CLI, Claude Code, opencode, Aider, Crush, and Amp directly into your workflow
• CLI Subagents - Launch isolated CLI instances from within your current CLI! Claude Code can spawn Codex subagents, Codex can spawn Gemini CLI subagents, etc. Offload heavy tasks (code reviews, bug hunting) to fresh contexts while your main session's context window remains unpolluted. Each subagent returns only final results.
• Context Isolation - Run separate investigations without polluting your primary workspace
• Role Specialization - Spawn planner, codereviewer, or custom role agents with specialized system prompts
• Per-call Model Selection - Pick a model at call time via the model parameter. Opencode uses provider/model (e.g. anthropic/claude-sonnet-4-5, openai/gpt-5, ollama/llama3.2) and unlocks ~75 providers through a single integration. Manifests can declare an optional supported_models allowlist to curate available models per CLI
• Full CLI Capabilities - Web search, file inspection, MCP tool access, latest documentation lookups
• Seamless Continuity - Sub-CLIs participate as first-class members with full conversation context between tools

# Codex spawns Codex subagent for isolated code review in fresh context
clink with codex codereviewer to audit auth module for security issues
# Subagent reviews in isolation, returns final report without cluttering your context as codex reads each file and walks the directory structure

# Per-call model selection through opencode (anthropic, openai, ollama, openrouter, ...)
clink with opencode using anthropic/claude-sonnet-4-5 to refactor the payment flow

# Consensus from different AI models → Implementation handoff with full context preservation between tools
Use consensus with gpt-5 and gemini-pro to decide: dark mode or offline support next
Continue with clink gemini - implement the recommended feature
# Gemini receives full debate context and starts coding immediately

👉 Learn more about clink

---

How to clink

The clink tool takes four parameters that matter day-to-day: cli_name, role, model, and read_only. Everything else (file attachments, continuation IDs) works the same as any other Unison tool.

Basic invocation

# Minimum: just pick a CLI and prompt it
clink with gemini to summarize the auth module

# Pick a role preset (default | planner | codereviewer)
clink with codex codereviewer to audit auth/ for OWASP top 10 issues
clink with claude planner to draft a phased migration off the legacy queue

# Pick a per-call model (especially powerful with opencode)
clink with opencode using anthropic/claude-sonnet-4-5 to refactor payments.py
clink with opencode using openai/gpt-5 to write a property-based test suite

# Read-only mode (analysis without file writes)
clink with claude codereviewer in read-only mode to review PR #482

Supported CLIs

CLI	Strengths	Read-only flag
gemini	Long-context analysis, free tier, web search	--approval-mode plan
codex	OpenAI-hosted reasoning models, web search via tool	prompt-only
claude	Anthropic models with strong agentic behavior	--permission-mode plan
opencode	75+ providers behind one CLI (OpenAI, Anthropic, Google, Ollama, OpenRouter, xAI, Mistral, Groq, …) via provider/model syntax	(none — see note)
aider	Largest AI-CLI userbase, git-integrated diff-edit workflow, multi-provider via standard env keys	--dry-run (native)
crush	Charm-built multi-provider TUI / CLI, provider/model syntax for routing	(none — prompt + snapshot)
amp	Sourcegraph-backed, code-search-aware tools, structured JSONL output, image input via --stream-json-input	(none — prompt + snapshot)

Note on opencode/crush/amp read-only mode: these three CLIs have no native flag for read-only-while-still-executing semantics. Read-only enforcement falls back to prompt-level instruction + post-execution filesystem snapshot diff — both CLI-agnostic. CLI bookkeeping that each CLI creates on first-run (.opencode/..., .crush/...) is classified separately under read_only_violations.by_cli_bookkeeping so it doesn't drown out genuine model-write detection. Aider is the exception — its documented --dry-run flag provides native read-only enforcement, supplemented by snapshot verification.

Recursion guard for MCP-aware CLIs: Crush and Amp both support user-defined MCP servers. If you wire Unison as an MCP server in their config AND invoke clink with cli_name="crush" (or "amp") from a Unison-aware CLI, you'd create a context-window-exploding loop. A cross-cutting guard at CLinkTool.execute() reads UNISON_CLINK_DEPTH from the environment and refuses invocations beyond CLINK_MAX_RECURSION_DEPTH (default 1) with a clear remediation message. Applies to ALL spawned CLIs.

Where to find valid model values

opencode is the heavy hitter — one integration unlocks the entire models.dev catalog. To see what your installation can serve:

opencode models                          # all models from authenticated providers
opencode models | grep ^anthropic/        # filter by provider
opencode models | wc -l                   # count (typically 300+ once you've authed a few providers)
opencode providers list                   # check which providers are authenticated

CLI	How to discover valid models	Format
opencode	opencode models (local) · models.dev (catalog)	provider/model (e.g. anthropic/claude-sonnet-4-5, openai/gpt-5, ollama/llama3.2)
claude	claude --help · Claude Code docs	aliases (sonnet, opus, haiku) or full IDs
gemini	gemini --help · Gemini CLI docs	model IDs (e.g. gemini-2.5-pro)
codex	codex --help · Codex CLI docs	OpenAI model IDs (e.g. o3-mini)
aider	aider --help · Aider docs	provider-prefixed names (e.g. gpt-4o-mini, claude-sonnet-4-5) per Aider's --model flag
crush	crush models (local)	provider/model (e.g. anthropic/claude-sonnet-4-5, openai/gpt-4o) — same shape as opencode
amp	amp --help · Amp owner's manual	Named modes only: deep, large, rush, smart (mapped to --mode, not arbitrary model strings)

Validation behavior: the model field is free-text — invalid values come back as a CLI-level error in response metadata, not a schema rejection. Authentication for opencode providers is opencode's own concern (opencode auth); Unison doesn't manage credentials.

Curating models per CLI (optional)

Add a supported_models allowlist to any conf/cli_clients/*.json manifest. When set, requests are validated against the list before the CLI is invoked — out-of-list values are rejected with a clear error naming the allowed values:

{
  "name": "opencode",
  "command": "opencode run",
  "supported_models": [
    "anthropic/claude-sonnet-4-5",
    "anthropic/claude-opus-4-5",
    "openai/gpt-5"
  ],
  "roles": { "default": { "prompt_path": "systemprompts/clink/default.txt" } }
}

When supported_models is omitted (the default), any model string is forwarded verbatim.

When model is omitted

Each manifest's additional_args carries the CLI's default — claude defaults to sonnet, gemini and codex use whatever default their CLI picks. Calls that don't specify model produce byte-for-byte identical commands to before this feature shipped, so existing workflows keep working unchanged.

---

Why Unison MCP?

Why rely on one AI model when you can orchestrate them all?

A Model Context Protocol server that supercharges tools like Claude Code, Codex CLI, and IDE clients such as Cursor or the Claude Dev VS Code extension. Unison MCP connects your favorite AI tool to multiple AI models for enhanced code analysis, problem-solving, and collaborative development.

True AI Collaboration with Conversation Continuity

Unison supports conversation threading so your CLI can discuss ideas with multiple AI models, exchange reasoning, get second opinions, and even run collaborative debates between models to help you reach deeper insights and better solutions.

Your CLI always stays in control but gets perspectives from the best AI for each subtask. Context carries forward seamlessly across tools and models, enabling complex workflows like: code reviews with multiple models → automated planning → implementation → pre-commit validation.

You're in control. Your CLI of choice orchestrates the AI team, but you decide the workflow. Craft powerful prompts that bring in Gemini Pro, GPT 5, Flash, or local offline models exactly when needed.

Reasons to Use Unison MCP

A typical workflow with Claude Code as an example:

1. Multi-Model Orchestration - Claude coordinates with Gemini Pro, O3, GPT-5, and 50+ other models to get the best analysis for each task

2. Context Revival Magic - Even after Claude's context resets, continue conversations seamlessly by having other models "remind" Claude of the discussion

3. Guided Workflows - Enforces systematic investigation phases that prevent rushed analysis and ensure thorough code examination

4. Extended Context Windows - Break Claude's limits by delegating to Gemini (1M tokens) or O3 (200K tokens) for massive codebases

5. True Conversation Continuity - Full context flows across tools and models - Gemini remembers what O3 said 10 steps ago

6. Model-Specific Strengths - Extended thinking with Gemini Pro, blazing speed with Flash, strong reasoning with O3, privacy with local Ollama

7. Professional Code Reviews - Multi-pass analysis with severity levels, actionable feedback, and consensus from multiple AI experts

8. Smart Debugging Assistant - Systematic root cause analysis with hypothesis tracking and confidence levels

9. Automatic Model Selection - Claude intelligently picks the right model for each subtask (or you can specify)

10. Vision Capabilities - Analyze screenshots, diagrams, and visual content with vision-enabled models

11. Local Model Support - Run Llama, Mistral, or other models locally for complete privacy and zero API costs

12. Bypass MCP Token Limits - Automatically works around MCP's 25K limit for large prompts and responses

The Killer Feature: When Claude's context resets, just ask to "continue with O3" - the other model's response magically revives Claude's understanding without re-ingesting documents!

Example: Multi-Model Code Review Workflow

1. Perform a codereview using gemini pro and o3 and use planner to generate a detailed plan, implement the fixes and do a final precommit check by continuing from the previous codereview
2. This triggers a codereview workflow where Claude walks the code, looking for all kinds of issues
3. After multiple passes, collects relevant code and makes note of issues along the way
4. Maintains a confidence level between exploring, low, medium, high and certain to track how confidently it's been able to find and identify issues
5. Generates a detailed list of critical -> low issues
6. Shares the relevant files, findings, etc with Gemini Pro to perform a deep dive for a second codereview
7. Comes back with a response and next does the same with o3, adding to the prompt if a new discovery comes to light
8. When done, Claude takes in all the feedback and combines a single list of all critical -> low issues, including good patterns in your code. The final list includes new findings or revisions in case Claude misunderstood or missed something crucial and one of the other models pointed this out
9. It then uses the planner workflow to break the work down into simpler steps if a major refactor is required
10. Claude then performs the actual work of fixing highlighted issues
11. When done, Claude returns to Gemini Pro for a precommit review

All within a single conversation thread! Gemini Pro in step 11 knows what was recommended by O3 in step 7! Taking that context and review into consideration to aid with its final pre-commit review.

Think of it as Claude Code for Claude Code. This MCP isn't magic. It's just super-glue.

Remember: Claude stays in full control — but YOU call the shots. Unison is designed to have Claude engage other models only when needed — and to follow through with meaningful back-and-forth. You're the one who crafts the powerful prompt that makes Claude bring in Gemini, Flash, O3 — or fly solo. You're the guide. The prompter. The puppeteer.

You are the AI - Actually Intelligent.

Recommended AI Stack

For Claude Code Users

For best results when using Claude Code:

• Sonnet 4.5 - All agentic work and orchestration
• Gemini 3.0 Pro OR GPT-5.2 / Pro - Deep thinking, additional code reviews, debugging and validations, pre-commit analysis

For Codex Users

For best results when using Codex CLI:

• GPT-5.2 Codex Medium - All agentic work and orchestration
• Gemini 3.0 Pro OR GPT-5.2-Pro - Deep thinking, additional code reviews, debugging and validations, pre-commit analysis

PAL vs Unison: full comparison

Unison inherits the entire PAL feature set. Every row below is an addition or hard upgrade — nothing is removed.

Capability	PAL MCP	Unison MCP
CLI-to-CLI orchestration	—	clink spawns 7 CLIs as subagents — Claude, Codex, Gemini, opencode, Aider, Crush, Amp — with role presets (planner, codereviewer), optional supported_models allowlist per CLI, and a cross-cutting recursion guard for MCP-aware targets
Read-only mode for sub-CLIs	—	Native CLI flags (--approval-mode plan, --permission-mode plan) + prompt instruction + post-call filesystem-snapshot diff; CLI bookkeeping (e.g. .opencode/) classified separately so it doesn't drown out genuine model writes
Provider reach via one integration	One provider per implementation	75+ providers through opencode via provider/model syntax (OpenAI, Anthropic, Google, Ollama, OpenRouter, xAI, Mistral, Groq, DeepSeek, …)
Model catalog	Static JSON files, manually curated — go stale the day a provider ships a new model	2000+ models auto-discovered via LiteLLM at startup, with curated overrides for tuned metadata
Discovered vs curated	All models treated equally	listmodels distinguishes curated (hand-tuned intelligence_score, aliases) from auto-discovered
Auto-mode model selection	Hardcoded preference lists per provider	Data-driven using intelligence_score and capability flags — newly discovered high-scoring models surface automatically
Catalog freshness	Manual JSON updates only	Weekly CI workflow fetches the latest LiteLLM catalog and opens a PR for human review
Conversation persistence	In-memory only — lost on restart	Optional SQLite backend (STORAGE_BACKEND=sqlite), zero-config
Provider failure handling	Wait through the full retry cycle on every call	Per-provider circuit breaker — fails fast after N consecutive failures, auto-probes recovery; consensus skips dead providers and synthesizes from the rest

All core tools, providers, workflows, and conversation continuity features from PAL are fully preserved. See docs/name-change.md for migration notes.

How model routing works: User-facing aliases (e.g., "gemini", "pro", "flash") are curated in conf/*.json and always point to a specific model. When auto-mode selects a model (no alias specified), it uses intelligence_score and capability flags dynamically — so newly discovered models with high scores are preferred automatically. The weekly LiteLLM refresh PR flags new models that need alias curation.

Quick Start (5 minutes)

Prerequisites: Python 3.10+, Git, uv installed

1. Get API Keys (choose one or more):

• OpenRouter - Access multiple models with one API
• Gemini - Google's latest models
• OpenAI - O3, GPT-5 series
• Azure OpenAI - Enterprise deployments of GPT-4o, GPT-4.1, GPT-5 family
• X.AI - Grok models
• DIAL - Vendor-agnostic model access
• Ollama - Local models (free)

2. Install (choose one):

Option A: Clone and Automatic Setup (recommended)

git clone https://github.com/izzoa/unison-mcp-server.git
cd unison-mcp-server

# Handles everything: setup, config, API keys from system environment. 
# Auto-configures Claude Desktop, Claude Code, Gemini CLI, Codex CLI, Qwen Code CLI
# Enable / disable additional settings in .env
./run-server.sh  

Option B: Instant Setup with uvx

// Add to ~/.claude/settings.json or .mcp.json
// Don't forget to add your API keys under env
{
  "mcpServers": {
    "unison": {
      "command": "bash",
      "args": ["-c", "for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \"$p\" ] && exec \"$p\" --from git+https://github.com/izzoa/unison-mcp-server.git unison-mcp-server; done; echo 'uvx not found' >&2; exit 1"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin",
        "GEMINI_API_KEY": "your-key-here",
        "DISABLED_TOOLS": "analyze,refactor,testgen,secaudit,docgen,tracer",
        "DEFAULT_MODEL": "auto"
      }
    }
  }
}

3. Start Using!

"Use unison to analyze this code for security issues with gemini pro"
"Debug this error with o3 and then get flash to suggest optimizations"
"Plan the migration strategy with unison, get consensus from multiple models"
"clink with cli_name=\"gemini\" role=\"planner\" to draft a phased rollout plan"

👉 Complete Setup Guide with detailed installation, configuration for Gemini / Codex / Qwen, and troubleshooting 👉 Cursor & VS Code Setup for IDE integration instructions 📺 Watch tools in action to see real-world examples

Provider Configuration

Unison activates any provider that has credentials in your .env. See .env.example for deeper customization.

Circuit Breaker — Each provider has a built-in circuit breaker that detects sustained failures (outages, revoked keys, quota exhaustion) and fails fast instead of waiting through the full retry cycle. When a provider fails CIRCUIT_FAILURE_THRESHOLD consecutive times (default 5), its circuit opens and requests return immediately for CIRCUIT_RESET_TIMEOUT_SECONDS (default 60s) before probing recovery. The consensus tool automatically skips unavailable providers and synthesizes from the rest. See .env.example for configuration options.

Core Tools

Note: Each tool comes with its own multi-step workflow, parameters, and descriptions that consume valuable context window space even when not in use. To optimize performance, some tools are disabled by default. See Tool Configuration below to enable them.

Collaboration & Planning (Enabled by default)

• clink - Bridge requests to external AI CLIs (Gemini planner, codereviewer, etc.). Supports read_only mode for safe analysis without file modifications
• chat - Brainstorm ideas, get second opinions, validate approaches. With capable models (GPT-5.2 Pro, Gemini 3.0 Pro), generates complete code / implementation
• thinkdeep - Extended reasoning, edge case analysis, alternative perspectives
• planner - Break down complex projects into structured, actionable plans
• consensus - Get expert opinions from multiple AI models with stance steering

Code Analysis & Quality

• debug - Systematic investigation and root cause analysis
• precommit - Validate changes before committing, prevent regressions
• codereview - Professional reviews with severity levels and actionable feedback
• analyze (disabled by default - enable) - Understand architecture, patterns, dependencies across entire codebases

Development Tools (Disabled by default - enable)

• refactor - Intelligent code refactoring with decomposition focus
• testgen - Comprehensive test generation with edge cases
• secaudit - Security audits with OWASP Top 10 analysis
• docgen - Generate documentation with complexity analysis

Utilities

• apilookup - Forces current-year API/SDK documentation lookups in a sub-process (saves tokens within the current context window), prevents outdated training data responses
• challenge - Prevent "You're absolutely right!" responses with critical analysis
• tracer (disabled by default - enable) - Static analysis prompts for call-flow mapping

👉 Tool Configuration

Default Configuration

To optimize context window usage, only essential tools are enabled by default:

Enabled by default:

• chat, thinkdeep, planner, consensus - Core collaboration tools
• codereview, precommit, debug - Essential code quality tools
• apilookup - Rapid API/SDK information lookup
• challenge - Critical thinking utility

Disabled by default:

• analyze, refactor, testgen, secaudit, docgen, tracer

Enabling Additional Tools

To enable additional tools, remove them from the DISABLED_TOOLS list:

Option 1: Edit your .env file

# Default configuration (from .env.example)
DISABLED_TOOLS=analyze,refactor,testgen,secaudit,docgen,tracer

# To enable specific tools, remove them from the list
# Example: Enable analyze tool
DISABLED_TOOLS=refactor,testgen,secaudit,docgen,tracer

# To enable ALL tools
DISABLED_TOOLS=

Option 2: Configure in MCP settings

// In ~/.claude/settings.json or .mcp.json
{
  "mcpServers": {
    "unison": {
      "env": {
        // Tool configuration
        "DISABLED_TOOLS": "refactor,testgen,secaudit,docgen,tracer",
        "DEFAULT_MODEL": "pro",
        "DEFAULT_THINKING_MODE_THINKDEEP": "high",
        
        // API configuration
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key",
        "OPENROUTER_API_KEY": "your-openrouter-key",
        
        // Logging and performance
        "LOG_LEVEL": "INFO",
        "CONVERSATION_TIMEOUT_HOURS": "6",
        "MAX_CONVERSATION_TURNS": "50"
      }
    }
  }
}

Option 3: Enable all tools

// Remove or empty the DISABLED_TOOLS to enable everything
{
  "mcpServers": {
    "unison": {
      "env": {
        "DISABLED_TOOLS": ""
      }
    }
  }
}

Note:

• Essential tools (version, listmodels) cannot be disabled
• After changing tool configuration, restart your Claude session for changes to take effect
• Each tool adds to context window usage, so only enable what you need

📺 Watch Tools In Action

Chat Tool - Collaborative decision making and multi-turn conversations

Consensus Tool - Multi-model debate and decision making

PreCommit Tool - Comprehensive change validation

API Lookup Tool - Current vs outdated API documentation

Without Unison — stale prompt-caching shape, outdated model ID:

With Unison — apilookup fetches current docs in a sub-process:

Challenge Tool - Critical thinking vs reflexive agreement

Without Unison — reflexive agreement:

With Unison — pushback with concrete checks:

Key Features

AI Orchestration

• Auto model selection - Claude picks the right AI for each task
• Multi-model workflows - Chain different models in single conversations
• Conversation continuity - Context preserved across tools and models
• Context revival - Continue conversations even after context resets

Model Support

• Multiple providers - Gemini, OpenAI, Azure, X.AI, OpenRouter, DIAL, Ollama
• Latest models - GPT-5, Gemini 3.0 Pro, O3, Grok-4, local Llama
• Automatic model discovery - New models appear at startup via LiteLLM integration, no manual config needed
• Thinking modes - Control reasoning depth vs cost
• Vision support - Analyze images, diagrams, screenshots

Developer Experience

• Guided workflows - Systematic investigation prevents rushed analysis
• Smart file handling - Auto-expand directories, manage token limits
• Web search integration - Access current documentation and best practices
• Large prompt support - Bypass MCP's 25K token limit

Example Workflows

Multi-model Code Review:

"Perform a codereview using gemini pro and o3, then use planner to create a fix strategy"

→ Claude reviews code systematically → Consults Gemini Pro → Gets O3's perspective → Creates unified action plan

Collaborative Debugging:

"Debug this race condition with max thinking mode, then validate the fix with precommit"

→ Deep investigation → Expert analysis → Solution implementation → Pre-commit validation

Architecture Planning:

"Plan our microservices migration, get consensus from pro and o3 on the approach"

→ Structured planning → Multiple expert opinions → Consensus building → Implementation roadmap

👉 Advanced Usage Guide for complex workflows, model configuration, and power-user features

Quick Links

📖 Documentation

• Docs Overview - High-level map of major guides
• Getting Started - Complete setup guide
• Tools Reference - All tools with examples
• Advanced Usage - Power user features
• Configuration - Environment variables, restrictions
• Adding Providers - Provider-specific setup (OpenAI, Azure, custom gateways)
• Model Ranking Guide - How intelligence scores drive auto-mode suggestions

🔧 Setup & Support

• WSL Setup - Windows users
• Troubleshooting - Common issues
• Contributing - Code standards, PR process

License

AGPL-3.0 License - see LICENSE file for details.

Acknowledgments

This project is based on BeehiveInnovations/pal-mcp-server. Full credit to the original authors for the foundation this work builds upon.

Built with the power of Multi-Model AI collaboration 🤝

• Actual Intelligence by real Humans
• MCP (Model Context Protocol)
• Codex CLI
• Claude Code
• Gemini
• OpenAI
• Azure OpenAI

Star History