Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Claudish AI Agent Usage Guide
Version: 2.2.0 Target Audience: AI Agents running within Claude Code Purpose: Quick reference for using Claudish CLI and MCP server in agentic workflows
TL;DR - Quick Start
# 1. Get available models
claudish --models --json
# 2. Auto-detected routing (model name determines provider)
claudish --model gpt-4o "your task here" # → OpenAI
claudish --model gemini-2.0-flash "your task here" # → Google
claudish --model llama-3.1-70b "your task here" # → OllamaCloud
# 3. Explicit provider routing (new @ syntax)
claudish --model [email protected] "your task here"
claudish --model oai@o1 "deep reasoning task"
claudish --model openrouter@deepseek/deepseek-r1 "analysis" # Unknown vendors need OR@
# 4. Run with local model (with concurrency control)
claudish --model [email protected] "your task here"
claudish --model [email protected]:3 "parallel task" # 3 concurrent requests
# 5. For large prompts, use stdin
echo "your task" | claudish --stdin --model gpt-4o
What is Claudish?
Claudish = Claude Code + Any AI Model
- ✅ Run Claude Code with any AI model via
provider@modelrouting - ✅ Native auto-detection -
gpt-4o→ OpenAI,gemini-*→ Google,llama-*→ OllamaCloud - ✅ Supports direct APIs: Google, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, Poe
- ✅ Supports local models (Ollama, LM Studio, vLLM, MLX) with concurrency control
- ✅ MCP Server mode - expose models as tools for Claude Code
- ✅ 100% Claude Code feature compatibility
- ✅ Local proxy server (no data sent to Claudish servers)
- ✅ Cost tracking and model selection
Model Routing (v4.0+)
New Syntax: provider@model[:concurrency]
| Shortcut | Provider | Example |
|---|---|---|
google@, g@ |
Google Gemini | [email protected] |
oai@ |
OpenAI Direct | oai@gpt-4o |
or@, openrouter@ |
OpenRouter | or@deepseek/deepseek-r1 |
mm@, mmax@ |
MiniMax Direct | mm@MiniMax-M2 |
kimi@, moon@ |
Kimi Direct | kimi@kimi-k2 |
glm@, zhipu@ |
GLM Direct | glm@glm-4 |
sakana@, fugu@ |
Sakana Fugu | fugu@fugu-ultra |
sc@ |
Sakana Fugu Subscription | sc@fugu-ultra |
llama@, oc@ |
OllamaCloud | [email protected] |
v@, vertex@ |
Vertex AI | [email protected] |
poe@ |
Poe | poe@GPT-4o |
ollama@ |
Ollama (local) | [email protected]:3 |
lmstudio@ |
LM Studio | lmstudio@qwen |
Native Model Auto-Detection
| Model Pattern | Routes To |
|---|---|
gemini-*, google/* |
Google API |
gpt-*, o1-*, o3-* |
OpenAI API |
llama-*, meta-llama/* |
OllamaCloud |
kimi-*, moonshot-* |
Kimi API |
glm-*, zhipu/* |
GLM API |
fugu-*, sakana/* |
Sakana Fugu |
claude-* |
Native Anthropic |
| Unknown vendors | Error (use openrouter@) |
Vertex AI Partner Models
Vertex AI supports Google + partner models (MaaS):
# Google Gemini on Vertex
claudish --model v/gemini-2.5-flash "task"
# Partner models (MiniMax, Mistral, DeepSeek, Qwen, OpenAI OSS)
claudish --model vertex/minimax/minimax-m2-maas "task"
claudish --model vertex/mistralai/codestral-2 "write code"
claudish --model vertex/deepseek/deepseek-v3-2-maas "analyze"
claudish --model vertex/qwen/qwen3-coder-480b-a35b-instruct-maas "implement"
claudish --model vertex/openai/gpt-oss-120b-maas "reason"
Prerequisites
Install Claudish:
npm install -g claudishSet API Key (at least one):
# OpenRouter (100+ models) export OPENROUTER_API_KEY='sk-or-v1-...' # OR Gemini direct export GEMINI_API_KEY='...' # OR Vertex AI (Application Default Credentials) gcloud auth application-default login # Optional - claudish otherwise uses the ADC quota project or `gcloud config get project` export VERTEX_PROJECT='your-gcp-project-id'Optional but recommended:
export ANTHROPIC_API_KEY='sk-ant-api03-placeholder'
Top Models for Development
| Model ID | Provider | Category | Best For |
|---|---|---|---|
openai/gpt-5.3 |
OpenAI | Reasoning | Default - Most advanced reasoning |
minimax/minimax-m2.1 |
MiniMax | Coding | Budget-friendly, fast |
z-ai/glm-4.7 |
Z.AI | Coding | Balanced performance |
google/gemini-3-pro-preview |
Reasoning | 1M context window | |
moonshotai/kimi-k2-thinking |
MoonShot | Reasoning | Extended thinking |
deepseek/deepseek-v3.2 |
DeepSeek | Coding | Code specialist |
qwen/qwen3-vl-235b-a22b-thinking |
Alibaba | Vision | Vision + reasoning |
Direct API Options (lower latency):
| Model ID | Backend | Best For |
|---|---|---|
g/gemini-2.0-flash |
Gemini | Fast tasks, large context |
v/gemini-2.5-flash |
Vertex AI | Enterprise, GCP billing |
oai/gpt-4o |
OpenAI | General purpose |
ollama/llama3.2 |
Local | Free, private |
Vertex AI Partner Models (MaaS):
| Model ID | Provider | Best For |
|---|---|---|
vertex/minimax/minimax-m2-maas |
MiniMax | Fast, budget-friendly |
vertex/mistralai/codestral-2 |
Mistral | Code specialist |
vertex/deepseek/deepseek-v3-2-maas |
DeepSeek | Deep reasoning |
vertex/qwen/qwen3-coder-480b-a35b-instruct-maas |
Qwen | Agentic coding |
vertex/openai/gpt-oss-120b-maas |
OpenAI | Open-weight reasoning |
Update models:
claudish --models --force-update
Critical: File-Based Pattern for Sub-Agents
⚠️ Problem: Context Window Pollution
Running Claudish directly in main conversation pollutes context with:
- Entire conversation transcript
- All tool outputs
- Model reasoning (10K+ tokens)
✅ Solution: File-Based Sub-Agent Pattern
Pattern:
- Write instructions to file
- Run Claudish with file input
- Read result from file
- Return summary only (not full output)
Example:
// Step 1: Write instruction file
const instructionFile = `/tmp/claudish-task-${Date.now()}.md`;
const resultFile = `/tmp/claudish-result-${Date.now()}.md`;
const instruction = `# Task
Implement user authentication
# Requirements
- JWT tokens
- bcrypt password hashing
- Protected route middleware
# Output
Write to: ${resultFile}
`;
await Write({ file_path: instructionFile, content: instruction });
// Step 2: Run Claudish
await Bash(`claudish --model x-ai/grok-code-fast-1 --stdin < ${instructionFile}`);
// Step 3: Read result
const result = await Read({ file_path: resultFile });
// Step 4: Return summary only
const summary = extractSummary(result);
return `✅ Completed. ${summary}`;
// Clean up
await Bash(`rm ${instructionFile} ${resultFile}`);
Using Claudish in Sub-Agents
Method 1: Direct Bash Execution
// For simple tasks with short output
const { stdout } = await Bash("claudish --model x-ai/grok-code-fast-1 --json 'quick task'");
const result = JSON.parse(stdout);
// Return only essential info
return `Cost: $${result.total_cost_usd}, Result: ${result.result.substring(0, 100)}...`;
Method 2: Task Tool Delegation
// For complex tasks requiring isolation
const result = await Task({
subagent_type: "general-purpose",
description: "Implement feature with Grok",
prompt: `
Use Claudish to implement feature with Grok model:
STEPS:
1. Create instruction file at /tmp/claudish-instruction-${Date.now()}.md
2. Write feature requirements to file
3. Run: claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-instruction-*.md
4. Read result and return ONLY:
- Files modified (list)
- Brief summary (2-3 sentences)
- Cost (if available)
DO NOT return full implementation details.
Keep response under 300 tokens.
`
});
Method 3: Multi-Model Comparison
// Compare results from multiple models
const models = [
"x-ai/grok-code-fast-1",
"google/gemini-2.5-flash",
"openai/gpt-5"
];
for (const model of models) {
const result = await Bash(`claudish --model ${model} --json "analyze security"`);
const data = JSON.parse(result.stdout);
console.log(`${model}: $${data.total_cost_usd}`);
// Store results for comparison
}
Essential CLI Flags
Core Flags
| Flag | Description | Example |
|---|---|---|
--model <model> |
OpenRouter model to use | --model x-ai/grok-code-fast-1 |
--stdin |
Read prompt from stdin | cat task.md | claudish --stdin --model grok |
--json |
JSON output (structured) | claudish --json "task" |
--list-models |
List available models | claudish --list-models --json |
Useful Flags
| Flag | Description | Default |
|---|---|---|
--quiet / -q |
Suppress logs | Enabled in single-shot |
--verbose / -v |
Show logs | Enabled in interactive |
--debug / -d |
Debug logging to file | Disabled |
--no-auto-approve |
Require prompts | Auto-approve enabled |
Common Workflows
Workflow 1: Quick Code Fix (Grok)
# Fast coding with visible reasoning
claudish --model x-ai/grok-code-fast-1 "fix null pointer error in user.ts"
Workflow 2: Complex Refactoring (GPT-5)
# Advanced reasoning for architecture
claudish --model openai/gpt-5 "refactor to microservices architecture"
Workflow 3: Code Review (Gemini)
# Deep analysis with large context
git diff | claudish --stdin --model google/gemini-2.5-flash "review for bugs"
Workflow 4: UI Implementation (Qwen Vision)
# Vision model for visual tasks
claudish --model qwen/qwen3-vl-235b-a22b-instruct "implement dashboard from design"
MCP Server Mode
Claudish can run as an MCP (Model Context Protocol) server, exposing OpenRouter models as tools that Claude Code can call mid-conversation. This is useful when you want to:
- Query external models without spawning a subprocess
- Compare responses from multiple models
- Use specific models for specific subtasks
Starting MCP Server
# Start MCP server (stdio transport)
claudish --mcp
Claude Code Configuration
Add to ~/.claude/settings.json:
{
"mcpServers": {
"claudish": {
"command": "claudish",
"args": ["--mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-..."
}
}
}
}
Or use npx (no installation needed):
{
"mcpServers": {
"claudish": {
"command": "npx",
"args": ["claudish@latest", "--mcp"]
}
}
}
Available MCP Tools
| Tool | Description | Example Use |
|---|---|---|
run_prompt |
One quick prompt to one model's API; no tools, no session | Get a second opinion from Grok |
list_models |
Show recommended models | Find models with tool support |
search_models |
Fuzzy search all models | Find vision-capable models |
compare_models |
DEBUG tool (debug group): one prompt to several models, raw answers side by side |
Check that routes answer |
Using MCP Tools from Claude Code
Once configured, Claude Code can use these tools directly:
User: "Use Grok to review this code"
Claude: [calls run_prompt tool with model="x-ai/grok-code-fast-1"]
User: "What models support vision?"
Claude: [calls search_models tool with query="vision"]
User: "Check that GPT-5 and Gemini both answer"
Claude: [calls compare_models tool with models=["openai/gpt-5.3", "google/gemini-3-pro-preview"]]
User: "Have GPT-5 and Gemini both review this design"
Claude: [calls team tool with mode="run-and-judge" — a real multi-model task, not compare_models]
MCP vs CLI Mode
| Feature | CLI Mode | MCP Mode |
|---|---|---|
| Use case | Replace Claude Code model | Call models as tools |
| Context | Full Claude Code session | Single prompt/response |
| Streaming | Full streaming | Buffered response |
| Best for | Primary model replacement | Second opinions, comparisons |
MCP Tool Details
run_prompt
{
model: string, // e.g., "x-ai/grok-code-fast-1"
prompt: string, // The prompt to send
system_prompt?: string // Optional system prompt
}
No output-limit parameter: the request carries no max_tokens, and the provider applies its
own default. A bare Claude name (claude-*, opus, sonnet, haiku) runs as one Claude Code
print-mode call (claudish -p) on the user's own Claude Code login, with tools, MCP servers and
settings off; its answer ends with Auth: Claude Code login (subscription). The explicit
anthropic@claude-* is the metered Anthropic API.
list_models
// No parameters - returns curated list of recommended models
{}
search_models
{
query: string, // e.g., "grok", "vision", "free"
limit?: number // Default: 10
}
compare_models
{
models: string[], // e.g., ["openai/gpt-5.3", "x-ai/grok-code-fast-1"]
prompt: string, // Prompt to send to all models
system_prompt?: string // Optional system prompt
}
Getting Model List
JSON Output (Recommended)
claudish --models-top --json
Output (abridged; one row shown):
{
"contractVersion": 3,
"generationId": "g-20261016120000000-abcdef12",
"version": "g-20261016120000000-abcdef12",
"lastUpdated": "2026-10-16T12:00:00.000Z",
"generatedAt": "2026-10-16T12:00:00.000Z",
"recommendationTiers": ["flagship", "cost_efficient", "lightweight", "luxury", "subscription"],
"models": [
{
"id": "grok-code-fast-1",
"name": "Grok Code Fast 1",
"description": "Ultra-fast agentic coding",
"provider": "x-ai",
"recommendationTier": "flagship",
"priority": 1,
"pricing": {
"input": "$0.2/1M",
"output": "$1.5/1M",
"average": "$0.85/1M"
},
"context": "256000"
}
]
}
recommendationTier is one of flagship, cost_efficient, lightweight, luxury or
subscription; recommendationTiers lists the tiers this claudish version knows. priority is
the rank within that tier, from 1. A model listed in two tiers is two rows, so dedupe ids
yourself. Only subscription rows carry subscriptions[].command, the model spec to run.
Prices are "N/A" when the catalog has none.
claudish --list-models --json prints the full catalog instead; its records carry no
recommendationTier.
Filter with jq
# Flagship model ids, in rank order
claudish --models-top --json | jq -r '.models | map(select(.recommendationTier == "flagship")) | sort_by(.priority) | .[].id'
# Runnable subscription commands
claudish --models-top --json | jq -r '.models[] | select(.recommendationTier == "subscription") | .subscriptions[]?.command'
Parse in TypeScript
const { stdout } = await Bash("claudish --models-top --json");
const data = JSON.parse(stdout);
// Every recommended model id, once (a model in two tiers is two rows)
const modelIds = [...new Set(data.models.map(m => m.id))];
// Flagship models, in rank order
const flagshipModels = data.models
.filter(m => m.recommendationTier === "flagship")
.sort((a, b) => a.priority - b.priority);
// Cheapest model by average price ("$0.85/1M"; "N/A" when unpriced)
const price = m => Number.parseFloat(m.pricing.average.replace(/^\$/, ""));
const cheapest = data.models
.filter(m => !Number.isNaN(price(m)))
.sort((a, b) => price(a) - price(b))[0];
JSON Output Format
When using --json flag, Claudish returns:
{
"result": "AI response text",
"total_cost_usd": 0.068,
"usage": {
"input_tokens": 1234,
"output_tokens": 5678
},
"duration_ms": 12345,
"num_turns": 3,
"modelUsage": {
"x-ai/grok-code-fast-1": {
"inputTokens": 1234,
"outputTokens": 5678
}
}
}
Extract fields:
claudish --json "task" | jq -r '.result' # Get result text
claudish --json "task" | jq -r '.total_cost_usd' # Get cost
claudish --json "task" | jq -r '.usage' # Get token usage
Error Handling
Check Claudish Installation
try {
await Bash("which claudish");
} catch (error) {
console.error("Claudish not installed. Install with: npm install -g claudish");
// Use fallback (embedded Claude models)
}
Check API Key
const apiKey = process.env.OPENROUTER_API_KEY;
if (!apiKey) {
console.error("OPENROUTER_API_KEY not set. Get key at: https://openrouter.ai/keys");
// Use fallback
}
Handle Model Errors
try {
const result = await Bash("claudish --model x-ai/grok-code-fast-1 'task'");
} catch (error) {
if (error.message.includes("Model not found")) {
console.error("Model unavailable. Listing alternatives...");
await Bash("claudish --list-models");
} else {
console.error("Claudish error:", error.message);
}
}
Graceful Fallback
async function runWithClaudishOrFallback(task: string) {
try {
// Try Claudish with Grok
const result = await Bash(`claudish --model x-ai/grok-code-fast-1 "${task}"`);
return result.stdout;
} catch (error) {
console.warn("Claudish unavailable, using embedded Claude");
// Run with standard Claude Code
return await runWithEmbeddedClaude(task);
}
}
Cost Tracking
View Cost in Status Line
Claudish shows cost in Claude Code status line:
directory • x-ai/grok-code-fast-1 • $0.12 • 67%
Get Cost from JSON
COST=$(claudish --json "task" | jq -r '.total_cost_usd')
echo "Task cost: \$${COST}"
Track Cumulative Costs
let totalCost = 0;
for (const task of tasks) {
const result = await Bash(`claudish --json --model grok "${task}"`);
const data = JSON.parse(result.stdout);
totalCost += data.total_cost_usd;
}
console.log(`Total cost: $${totalCost.toFixed(4)}`);
Best Practices Summary
✅ DO
- Use file-based pattern for sub-agents to avoid context pollution
- Choose appropriate model for task (Grok=speed, GPT-5=reasoning, Qwen=vision)
- Use --json output for automation and parsing
- Handle errors gracefully with fallbacks
- Track costs when running multiple tasks
- Update models regularly with
--force-update - Use --stdin for large prompts (git diffs, code review)
❌ DON'T
- Don't run Claudish directly in main conversation (pollutes context)
- Don't ignore model selection (different models have different strengths)
- Don't parse text output (use --json instead)
- Don't hardcode model lists (query dynamically)
- Don't skip error handling (Claudish might not be installed)
- Don't return full output in sub-agents (summary only)
Quick Reference Commands
# Installation
npm install -g claudish
# Get models
claudish --list-models --json
# Run task
claudish --model x-ai/grok-code-fast-1 "your task"
# Large prompt
git diff | claudish --stdin --model google/gemini-2.5-flash "review"
# JSON output
claudish --json --model grok "task" | jq -r '.total_cost_usd'
# Update models
claudish --list-models --force-update
# Get help
claudish --help
Example: Complete Sub-Agent Implementation
/**
* Example: Implement feature with Claudish + Grok
* Returns summary only, full implementation in file
*/
async function implementFeatureWithGrok(description: string): Promise<string> {
const timestamp = Date.now();
const instructionFile = `/tmp/claudish-implement-${timestamp}.md`;
const resultFile = `/tmp/claudish-result-${timestamp}.md`;
try {
// 1. Create instruction
const instruction = `# Feature Implementation
## Description
${description}
## Requirements
- Clean, maintainable code
- Comprehensive tests
- Error handling
- Documentation
## Output File
${resultFile}
## Format
\`\`\`markdown
## Files Modified
- path/to/file1.ts
- path/to/file2.ts
## Summary
[2-3 sentence summary]
## Tests Added
- test description 1
- test description 2
\`\`\`
`;
await Write({ file_path: instructionFile, content: instruction });
// 2. Run Claudish
await Bash(`claudish --model x-ai/grok-code-fast-1 --stdin < ${instructionFile}`);
// 3. Read result
const result = await Read({ file_path: resultFile });
// 4. Extract summary
const filesMatch = result.match(/## Files Modified\s*\n(.*?)(?=\n##|$)/s);
const files = filesMatch ? filesMatch[1].trim().split('\n').length : 0;
const summaryMatch = result.match(/## Summary\s*\n(.*?)(?=\n##|$)/s);
const summary = summaryMatch ? summaryMatch[1].trim() : "Implementation completed";
// 5. Clean up
await Bash(`rm ${instructionFile} ${resultFile}`);
// 6. Return concise summary
return `✅ Feature implemented. Modified ${files} files. ${summary}`;
} catch (error) {
// 7. Handle errors
console.error("Claudish implementation failed:", error.message);
// Clean up if files exist
try {
await Bash(`rm -f ${instructionFile} ${resultFile}`);
} catch {}
return `❌ Implementation failed: ${error.message}`;
}
}
Additional Resources
- Full Documentation:
<claudish-install-path>/README.md - Skill Document:
skills/claudish-usage/SKILL.md(in repository root) - Model Integration:
skills/claudish-integration/SKILL.md(in repository root) - OpenRouter Docs: https://openrouter.ai/docs
- Claudish GitHub: https://github.com/MadAppGang/claude-code
Get This Guide
# Print this guide
claudish --help-ai
# Save to file
claudish --help-ai > claudish-agent-guide.md
Version: 2.2.0 Last Updated: January 22, 2026 Maintained by: MadAppGang