proxy-mode-reference

# External Models via Claudish CLI — Reference Guide ## ⚠️ Learn and Reuse Model Preferences Models are learned per context and reused automatically: ```bash 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 ```bash # 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 ```bash claudish --model x-ai/grok-code-fast-1 --stdin --quiet < task.md > result.md ``` ### Parallel External Models (in /team) ```bash # 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 ```bash # 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 ```bash # ❌ 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.