madappgang/proxy-mode-reference

External Models via Claudish CLI — Reference Guide

⚠️ Learn and Reuse Model Preferences

Models are learned per context and reused automatically:

cat .claude/multimodel-team.json 2>/dev/null

1. Detect context from task keywords (debug/research/coding/review)
2. If contextPreferences[context] exists → USE IT (no asking)
3. If empty (first time) → ASK user → SAVE for that context
4. User says "change models" → UPDATE preferences

---

How External Models Work

External models are invoked deterministically via the claudish CLI. The orchestrator (e.g., /team command) calls claudish directly through Bash — no LLM delegation needed.

Orchestrator → Bash(claudish --model {MODEL_ID} --stdin) → External Model

This approach is 100% reliable because it's a direct CLI invocation, not a prompt-based delegation.

Invoking External Models

From /team Command (Automatic)

The /team command handles this automatically:

• Internal models → Task(dev:researcher)
• External models → Bash(claudish --model {MODEL_ID} --stdin)

Direct CLI Usage

# Pattern
claudish --model {MODEL_ID} --stdin --quiet < prompt-file.md > result.md

# Examples
claudish --model x-ai/grok-code-fast-1 --stdin --quiet < task.md > grok-result.md
claudish --model google/gemini-3-pro-preview --stdin --quiet < task.md > gemini-result.md

Required flags:

• --model — The external model to use
• --stdin — Read prompt from stdin (for large prompts)
• --quiet — Suppress log messages (for clean output capture)

Multi-Backend Routing

Claudish routes to different backends based on model ID prefix:

| Prefix | Backend | Required Key | Example | |--------|---------|--------------|---------| | (none) | OpenRouter | OPENROUTER_API_KEY | openai/gpt-5.2 | | g/ gemini/ | Google Gemini API | GEMINI_API_KEY | g/gemini-2.0-flash | | oai/ | OpenAI Direct API | OPENAI_API_KEY | oai/gpt-4o | | mmax/ mm/ | MiniMax Direct API | MINIMAX_API_KEY | mmax/MiniMax-M2.1 | | kimi/ moonshot/ | Kimi Direct API | KIMI_API_KEY | kimi/kimi-k2-thinking-turbo | | glm/ zhipu/ | GLM Direct API | GLM_API_KEY | glm/glm-4.7 | | ollama/ | Ollama (local) | None | ollama/llama3.2 | | lmstudio/ | LM Studio (local) | None | lmstudio/qwen | | vllm/ | vLLM (local) | None | vllm/model | | mlx/ | MLX (local) | None | mlx/model | | http://... | Custom endpoint | None | http://localhost:8000/model |

⚠️ Prefix Collision Warning

OpenRouter model IDs may collide with routing prefixes. Check the prefix table above.

Collision-free models (safe for OpenRouter):

• x-ai/grok-* ✅
• deepseek/* ✅
• minimax/* ✅ (use mmax/ for MiniMax Direct)
• qwen/* ✅
• mistralai/* ✅
• moonshotai/* ✅ (use kimi/ for Kimi Direct)
• anthropic/* ✅
• z-ai/* ✅ (use glm/ for GLM Direct)
• google/* ✅ (use g/ for Gemini Direct)
• openai/* ✅ (use oai/ for OpenAI Direct)

Direct API prefixes for cost savings: | OpenRouter Model | Direct API Prefix | Notes | |------------------|-------------------|-------| | openai/gpt-* | oai/gpt-* | OpenAI Direct API | | google/gemini-* | g/gemini-* | Gemini Direct API | | minimax/* | mmax/* or mm/* | MiniMax Direct API | | moonshotai/* | kimi/* or moonshot/ | Kimi Direct API | | z-ai/glm-* | glm/* or zhipu/* | GLM Direct API |

---

Correct Usage Patterns

Single External Model

claudish --model x-ai/grok-code-fast-1 --stdin --quiet < task.md > result.md

Parallel External Models (in /team)

# All launched in a single message with run_in_background: true
Bash("claudish --model x-ai/grok-code-fast-1 --stdin --quiet < vote-prompt.md > grok-result.md 2>grok-stderr.log; echo $? > grok.exit")
Bash("claudish --model google/gemini-3-pro-preview --stdin --quiet < vote-prompt.md > gemini-result.md 2>gemini-stderr.log; echo $? > gemini.exit")

Verifying Results

# Check exit code
cat grok.exit  # 0 = success

# Check output size
wc -c < grok-result.md  # Should be >50 bytes

# Check stderr for errors
cat grok-stderr.log

Common Mistakes

Mistake 1: Not capturing exit code

# ❌ WRONG - no way to detect failures
claudish --model grok --stdin < task.md > result.md

# ✅ CORRECT - capture exit code
claudish --model grok --stdin < task.md > result.md 2>stderr.log; echo $? > result.exit

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.