Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Claudish AI Agent Usage Guide
Version: 7.0.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. Run task with specific model (OpenRouter)
claudish --model openai/gpt-5.3 "your task here"
# 3. Run with direct Gemini API
claudish --model g/gemini-2.0-flash "your task here"
# 4. Run with local model
claudish --model ollama/llama3.2 "your task here"
# 5. For large prompts, use stdin
echo "your task" | claudish --stdin --model openai/gpt-5.3
What is Claudish?
Claudish = Claude Code + Any AI Model
- ✅ Run Claude Code with any AI model via prefix-based routing
- ✅ Supports OpenRouter (100+ models), direct Gemini API, direct OpenAI API
- ✅ Supports local models (Ollama, LM Studio, vLLM, MLX)
- ✅ 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
| Prefix | Backend | Example |
|---|---|---|
| (none) | OpenRouter | openai/gpt-5.3 |
g/ gemini/ |
Google Gemini | g/gemini-2.0-flash |
v/ vertex/ |
Vertex AI | v/gemini-2.5-flash |
oai/ openai/ |
OpenAI | oai/gpt-4o |
ollama/ |
Ollama | ollama/llama3.2 |
lmstudio/ |
LM Studio | lmstudio/model |
http://... |
Custom | http://localhost:8000/model |
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"
Default provider (v7.0.0+)
Bare model names (no provider@ prefix) route through the configured default provider. Override per-invocation:
claudish --default-provider litellm --model minimax-m2.5 "task"
Explicit provider@model syntax always bypasses defaultProvider and routes directly to the named provider.
Custom endpoints can be registered in ~/.claudish/config.json. See docs/settings-reference.md for the full schema.
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 --models-refresh
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" |
--models |
List available models | claudish --models --json |
Useful Flags
| Flag | Description | Default |
|---|---|---|
--default-provider <name> |
Override default provider for bare model routing (v7.0.0+) | Auto-detected |
--quiet / -q |
Suppress logs | Enabled in single-shot |
--verbose / -v |
Show logs | Enabled in interactive |
--debug-claudish / -d |
Debug logging to file | Disabled |
--no-auto-approve |
Require prompts | Auto-approve enabled |
Claude Code Flag Passthrough
Any Claude Code flag that claudish doesn't recognize is automatically forwarded. This means you can use:
# Agent selection
claudish --model grok --agent code-review --stdin --quiet < prompt.md
# Effort and budget control
claudish --model grok --effort high --max-budget-usd 0.50 --stdin --quiet < prompt.md
# Permission mode
claudish --model grok --permission-mode plan --stdin --quiet < prompt.md
Use -- separator when flag values start with -:
claudish --model grok -- --system-prompt "-v mode" --stdin --quiet < prompt.md
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",
"supportsTools": true,
"supportsReasoning": true,
"supportsVision": false
}
]
}
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. supportsTools, supportsReasoning and
supportsVision come from the cloud models catalog; a field is absent when the catalog does not
publish it, so treat absent as unknown, not as false.
claudish --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 --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
--models-refresh - 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 --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 --models --models-refresh
# 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: 7.0.0 Last Updated: April 14, 2026 Maintained by: MadAppGang