Reference guide for using external AI models via claudish MCP tools and CLI. Orchestration workflows (/team, /delegate) use MCP tools. Direct usage uses CLI. Includes model routing and error handling patterns.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Reference guide for using external AI models via claudish MCP tools and CLI. Orchestration workflows (/team, /delegate) use MCP tools. Direct usage uses CLI. Includes model routing and error handling patterns.
disable-model-invocation
true
External Models via Claudish โ Reference Guide
โ ๏ธ Learn and Reuse Model Preferences
Models are learned per context and reused automatically:
cat .claude/multimodel-team.json 2>/dev/null
Detect context from task keywords (debug/research/coding/review)
If contextPreferences[context] exists โ USE IT (no asking)
If empty (first time) โ ASK user โ SAVE for that context
User says "change models" โ UPDATE preferences
How External Models Work
External models are invoked via claudish MCP tools. The orchestrator calls MCP tools directly โ no Bash invocation needed.
Orchestrator โ claudish MCP tool โ External Model
From /team Command (Automatic)
The /team command handles this automatically:
Internal models โ Task({resolved_agent}) โ auto-detected from task type
Claudish handles all model routing internally. Pass bare model names โ claudish auto-resolves them to the best available provider.
# Just use bare model names โ claudish handles the rest
claudish --model grok --stdin --quiet < task.md > result.md
claudish --model gemini --stdin --quiet < task.md > result.md
claudish --model gpt --stdin --quiet < task.md > result.md
Do NOT add provider prefixes (x-ai/, google/, openai/, minimax/, etc.) โ claudish manages provider detection and routing automatically since v5.4.0.
Correct Usage Patterns
Single External Model (via MCP)
// One-shot prompt
run_prompt(model="grok", prompt="Review this code for security issues")
// Session-based (for longer tasks)
create_session(model="grok", prompt=TASK_PROMPT, timeout_seconds=300)
Parallel External Models (in /team)
// Single MCP tool call handles all external models in parallel
team(mode="run", path=SESSION_DIR, models=["grok", "gemini"],
input=VOTE_PROMPT, timeout=180)
Verifying Results
For team tool: Check each model's status in the structured response.
For create_session: The completed channel event confirms success; failed event contains error details.
CRITICAL: When claudish fails, STOP and REPORT โ never silently substitute a different model.
Rules
If claudish exits with non-zero exit code or empty output: STOP and report the exact error (from stderr log) to the user before trying any alternative.
Never silently substitute a different model than the user requested. If the user asked for Gemini, don't silently launch GPT-5 instead.
Never silently retry with a different provider prefix. If or@google/gemini fails, don't silently try g@gemini without telling the user.
Report all attempts made so the user understands what was tried and can make an informed decision.
Failure Report Template
"{Model} failed โ {error category}.
Attempts:
1. {command tried} โ {exact error from stderr}
Options:
(1) {Fix suggestion}
(2) Use a different model
(3) Skip and continue without this model
(4) Cancel
(5) Report this error to claudish developers
Which do you prefer?"
When to apply
This protocol applies whenever a user has requested a specific external model. It does NOT apply to automated pipelines where the user said "use whatever works" or when the /team command is managing its own failure reporting.
Error Reporting
After reporting the failure to the user, offer to send a sanitized error report to claudish developers:
Options:
(1) {Fix suggestion}
(2) Use a different model
(3) Skip and continue without this model
(4) Cancel
(5) Report this error to claudish developers
If the user selects (5), call the claudish report_error MCP tool:
report_error(
error_type: "provider_failure", // or "stream_error", "adapter_error", "team_failure"
model: "{MODEL_ID}",
stderr_snippet: "{error content from MCP result or channel event}",
session_path: "{SESSION_DIR}",
additional_context: "Invoked via multimodel plugin"
)
Consent required: Always ask before calling. Data is sanitized (API keys, paths, emails stripped).
Automatic reporting: Users can enable via claudish config โ Privacy โ Telemetry, or CLAUDISH_TELEMETRY=1. When enabled, errors report automatically.
See also: multimodel:error-recovery skill, Pattern 0 (User Escalation).
Troubleshooting
"claudish: command not found"
Fix:npm install -g claudish
"OPENROUTER_API_KEY not set"
Fix:export OPENROUTER_API_KEY=your-key
Non-zero exit code
Fix: Check stderr log for error details. Common causes: rate limits, invalid model ID, API key issues.
