MindMesh

MindMesh is an MCP-based AI provider orchestration layer for Claude Code. Claude remains the decision-maker while external providers (OpenAI, Gemini, Z.ai, Ollama) act as reviewers and consultants — analyzing your code without touching the repository.

Architecture

Claude Code  -->  MindMesh Plugin  -->  MCP Server (stdio)  -->  Provider Router  -->  AI Provider
                                        CLI (Typer)         -->  Provider Router  -->  AI Provider

MCP Tools

Tool	Description
review_code	Multi-provider code review with structured findings
security_audit	Security-focused analysis of files or git diff
bug_investigate	Root cause analysis for a reported bug or error
ask_provider	Free-form question to a provider (raw text, no JSON parse)
compare_providers	Run the same task across providers, Finding format
delegate_task	Delegate with mode: advisory, analysis, review, planning, patch_suggestion
list_endpoints	Show configured endpoints, optional health check (check=True)
preview_context	Preview context/policy without making provider calls
validate_policy	Validate policy and config rules
test_patch	Apply a patch in an isolated git worktree and run tests
local_scan	Run local security scanners (bandit, semgrep) — no LLM calls

All pipeline tools support min_severity, dry_run, and no_cache parameters.

CLI

Entry point: mindmesh

Command	Description
review	Code review
security	Security audit
bugfix	Bug investigation
compare	Compare providers
delegate	Delegate task
ask	Free-form question
list	List endpoints
preview	Preview context
validate	Validate policy
test-patch	Test a patch in worktree
history	Browse run history
stats	Usage statistics dashboard
providers	List available providers
add-endpoint	Add an endpoint to .mindmesh.yml
remove-endpoint	Remove an endpoint from .mindmesh.yml
scan	Run local security scanners (no LLM cost)
commit	Generate commit message from diff
pr	Generate PR title and description

Output formats:

• Default: human-readable tables/panels
• --json on any command for raw JSON
• --output sarif on review and security for SARIF v2.1.0 (GitHub Code Scanning compatible)
• --stream on ask for live token streaming

Providers

Provider	SDK	Streaming
OpenAI	openai (AsyncOpenAI)	Native
Gemini	google-genai	Fallback
Z.ai	httpx	Fallback
Ollama	httpx	Native

Installation

# Recommended — global tool install (isolated env, CLI in PATH)
uv tool install "mindmesh-ai[all]"    # OpenAI + Gemini
uv tool install "mindmesh-ai[openai]" # OpenAI only
uv tool install "mindmesh-ai[gemini]" # Gemini only
uv tool install mindmesh-ai           # Core only (Z.ai + Ollama via httpx)

# Alternative — pip
pip install "mindmesh-ai[all]"

Quick Start

Requirements: Python 3.12+, at least one API key

1. Set API keys — in your project's .env file or shell profile:

# Option A: .env file in project root (recommended)
echo "OPENAI_API_KEY=sk-..." >> .env
echo "GEMINI_API_KEY=AI..." >> .env

# Option B: shell profile (~/.zshrc or ~/.bashrc) for all projects
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AI...

2. Use the CLI:

mindmesh list                          # see configured endpoints
mindmesh review --scope git_diff       # review your changes
mindmesh ask "Is this safe?" --stream  # ask a provider

3. Connect to Claude Code — add to your project's .claude/settings.json:

{
  "enabledPlugins": {"mindmesh@mindmesh-local": true},
  "extraKnownMarketplaces": {
    "mindmesh-local": {
      "source": {
        "source": "directory",
        "path": "<run: mindmesh plugin-path>"
      }
    }
  }
}

Find the plugin path:

mindmesh plugin-path

Then talk to Claude naturally: "Review this diff with OpenAI and Gemini"

4. Update:

mindmesh update

CLI Examples

mindmesh review --scope git_diff
mindmesh security --scope src/auth/
mindmesh ask "Explain this architecture" --endpoint gemini-default
mindmesh ask "What does this do?" --stream
mindmesh providers
mindmesh add-endpoint fast-review --provider openai --model gpt-4o-mini
mindmesh commit
mindmesh pr
mindmesh scan src/ --scanner bandit
mindmesh list --check
mindmesh history
mindmesh stats
mindmesh plugin-path

Usage Examples

Once MindMesh is connected, talk to Claude naturally:

• "Review this diff with OpenAI and Gemini"
• "Run a security audit on src/auth"
• "Login endpoint is throwing 500 — investigate"
• "Ask Gemini about this architecture approach"
• "Compare how OpenAI and Gemini rate this PR"
• "Delegate a planning task to OpenAI in advisory mode"
• "Preview what context would be sent before running review"
• "Validate my .mindmesh.yml config"
• "Test this patch against the test suite"
• "Run a local security scan on src/ with bandit"

Configuration

Copy .mindmesh.example.yml to .mindmesh.yml in your project root. Without a config file, MindMesh auto-discovers endpoints from environment variables (OPENAI_API_KEY, GEMINI_API_KEY, etc.).

See .mindmesh.example.yml for the full reference.

Key config sections:

Section	Controls
providers	Provider endpoints, models, timeouts
privacy	block_files, block_dirs, redact_secrets
policy	Provider allow/disable lists, permission rules
cache	enabled, ttl_seconds (SQLite response cache)
prompts	custom_dir for custom Jinja2 templates (falls back to built-in)
compression	enabled, endpoint — AST skeleton + LLM summarizer with fallback
sandbox	Docker isolation for test_patch: enabled, image, network, memory_limit
permissions	allowed_test_commands whitelist, patch/codebase access controls

Features

• Response cache — SQLite-backed with configurable TTL; skip with no_cache
• Run history — SQLite storage, browsable via history and stats commands
• Secret redaction — Regex patterns + entropy-based detection; secrets are never stored or logged
• File policy — .env, *.pem, *.key blocked by default; configurable block lists
• Provider policy (fail-closed) — Disabled providers are hard-blocked, no fallback
• Permission policy — Controls for full codebase access, external patches, auto-apply
• Smart merger — Title similarity + union-find grouping, cross-endpoint only
• Worktree isolation — test_patch runs in a disposable git worktree with Docker sandbox
• Docker sandbox — Test commands run in read-only, no-network containers; errors if Docker is unavailable (fail-closed)
• Command whitelist — allowed_test_commands in config blocks arbitrary command execution
• Provider registry — Centralized provider management; providers, add-endpoint, remove-endpoint CLI commands
• Context compression — AST skeleton extraction (Python) + LLM summarizer with fallback chain
• Local scanners — bandit + semgrep integration, zero API cost, Finding-compatible output
• Streaming — ask --stream for live token output (OpenAI + Ollama native, others fallback)
• SARIF output — v2.1.0, compatible with GitHub Code Scanning
• GitHub Actions — Ready-made workflow at .github/workflows/mindmesh-review.yml
• Token tracking — Real token counts from provider responses in stats and history --detail
• Audit logging — JSONL + SQLite dual logging
• Custom prompts — Override built-in Jinja2 templates per project

Security

• Redaction: Secrets are masked before any content leaves your machine. Detected patterns (API keys, PEM blocks, connection strings, high-entropy tokens) are reported as findings — values are never stored or logged.
• File Policy: .env, *.pem, *.key, and other sensitive paths are blocked by default. Configurable via privacy.block_files / privacy.block_dirs.
• Provider Policy (fail-closed): Disabled providers are hard-blocked. No request is sent and no fallback occurs. Partial failures do not cascade — a failing endpoint does not block others.
• Audit Trail: All tool invocations are logged to JSONL and SQLite for traceability.

Entry Points

Command	Purpose
mindmesh-mcp	MCP server over stdio (for Claude Code)
mindmesh	CLI for terminal usage

Development

uv run pytest          # run tests
uv run ruff check .    # lint
uv run pyright         # type check

License

MIT