CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.
CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.
Claudish Usage Skill
Version: 1.1.0
Purpose: Guide AI agents on how to use Claudish CLI to run Claude Code with OpenRouter models
Status: Production Ready
⚠️ CRITICAL RULES - READ FIRST
🚫 NEVER Run Claudish from Main Context
Claudish MUST ONLY be run through sub-agents unless the user explicitly requests direct execution.
Why:
Running Claudish directly pollutes main context with 10K+ tokens (full conversation + reasoning)
Destroys context window efficiency
Makes main conversation unmanageable
When you can run Claudish directly:
✅ User explicitly says "run claudish directly" or "don't use a sub-agent"
✅ User is debugging and wants to see full output
✅ User specifically requests main context execution
When you MUST use sub-agent:
✅ User says "use Grok to implement X" (delegate to sub-agent)
✅ User says "ask GPT-5 to review X" (delegate to sub-agent)
✅ User mentions any model name without "directly" (delegate to sub-agent)
✅ Any production task (always delegate)
📋 Workflow Decision Tree
User Request
↓
Does it mention Claudish/OpenRouter/model name? → NO → Don't use this skill
↓ YES
↓
Does user say "directly" or "in main context"? → YES → Run in main context (rare)
↓ NO
↓
Find appropriate agent or create one → Delegate to sub-agent (default)
🤖 Agent Selection Guide
Step 1: Find the Right Agent
When user requests Claudish task, follow this process:
Check for existing agents that support proxy mode or external model delegation
If no suitable agent exists:
Suggest creating a new proxy-mode agent for this task type
Offer to proceed with generic general-purpose agent if user declines
If user declines agent creation:
Warn about context pollution
Ask if they want to proceed anyway
Step 2: Agent Type Selection Matrix
Task Type
Recommended Agent
Fallback
Notes
Code implementation
Create coding agent with proxy mode
general-purpose
Best: custom agent for project-specific patterns
Code review
Use existing code review agent + proxy
general-purpose
Check if plugin has review agent first
Architecture planning
Use existing architect agent + proxy
general-purpose
Look for architect or planner agents
Testing
Use existing test agent + proxy
general-purpose
Look for test-architect or tester agents
Refactoring
Create refactoring agent with proxy
general-purpose
Complex refactors benefit from specialized agent
Documentation
general-purpose
-
Simple task, generic agent OK
Analysis
Use existing analysis agent + proxy
general-purpose
Check for analyzer or detective agents
Other
general-purpose
-
Default for unknown task types
Step 3: Agent Creation Offer (When No Agent Exists)
Template response:
I notice you want to use [Model Name] for [task type].
RECOMMENDATION: Create a specialized [task type] agent with proxy mode support.
This would:
✅ Provide better task-specific guidance
✅ Reusable for future [task type] tasks
✅ Optimized prompting for [Model Name]
Options:
1. Create specialized agent (recommended) - takes 2-3 minutes
2. Use generic general-purpose agent - works but less optimized
3. Run directly in main context (NOT recommended - pollutes context)
Which would you prefer?
Step 4: Common Agents by Plugin
Frontend Plugin:
typescript-frontend-dev - Use for UI implementation with external models
frontend-architect - Use for architecture planning with external models
senior-code-reviewer - Use for code review (can delegate to external models)
test-architect - Use for test planning/implementation
Bun Backend Plugin:
backend-developer - Use for API implementation with external models
api-architect - Use for API design with external models
Code Analysis Plugin:
codebase-detective - Use for investigation tasks with external models
No Plugin:
general-purpose - Default fallback for any task
Step 5: Example Agent Selection
Example 1: User says "use Grok to implement authentication"
Task: Code implementation (authentication)
Plugin: Bun Backend (if backend) or Frontend (if UI)
Decision:
1. Check for backend-developer or typescript-frontend-dev agent
2. Found backend-developer? → Use it with Grok proxy
3. Not found? → Offer to create custom auth agent
4. User declines? → Use general-purpose with file-based pattern
Example 2: User says "ask GPT-5 to review my API design"
Task: Code review (API design)
Plugin: Bun Backend
Decision:
1. Check for api-architect or senior-code-reviewer agent
2. Found? → Use it with GPT-5 proxy
3. Not found? → Use general-purpose with review instructions
4. Never run directly in main context
Example 3: User says "use Gemini to refactor this component"
Task: Refactoring (component)
Plugin: Frontend
Decision:
1. No specialized refactoring agent exists
2. Offer to create component-refactoring agent
3. User declines? → Use typescript-frontend-dev with proxy
4. Still no agent? → Use general-purpose with file-based pattern
Overview
Claudish is a CLI tool that allows running Claude Code with any OpenRouter model (Grok, GPT-5, MiniMax, Gemini, etc.) by proxying requests through a local Anthropic API-compatible server.
Key Principle:ALWAYS use Claudish through sub-agents with file-based instructions to avoid context window pollution.
What is Claudish?
Claudish (Claude-ish) is a proxy tool that:
✅ Runs Claude Code with any OpenRouter model (not just Anthropic models)
✅ Uses local API-compatible proxy server
✅ Supports 100% of Claude Code features
✅ Provides cost tracking and model selection
✅ Enables multi-model workflows
Use Cases:
Run tasks with different AI models (Grok for speed, GPT-5 for reasoning, Gemini for vision)
Compare model performance on same task
Reduce costs with cheaper models for simple tasks
Access models with specialized capabilities
Requirements
System Requirements
OpenRouter API Key - Required (set as OPENROUTER_API_KEY environment variable)
Claudish CLI - Install with: npm install -g claudish or bun install -g claudish
Claude Code - Must be installed
Environment Variables
# Requiredexport OPENROUTER_API_KEY='sk-or-v1-...'# Your OpenRouter API key# Optional (but recommended)export ANTHROPIC_API_KEY='sk-ant-api03-placeholder'# Prevents Claude Code dialog# Optional - default modelexport CLAUDISH_MODEL='x-ai/grok-code-fast-1'# or ANTHROPIC_MODEL
# With npm (works everywhere)
npm install -g claudish
# With Bun (faster)
bun install -g claudish
# Verify installation
claudish --version
Step 2: Get Available Models
# List ALL OpenRouter models grouped by provider
claudish --models
# Fuzzy search models by name, ID, or description
claudish --models gemini
claudish --models "grok code"# Show top recommended programming models (curated list)
claudish --top-models
# JSON output for parsing
claudish --models --json
claudish --top-models --json
# Force update from OpenRouter API
claudish --models --force-update
Step 3: Run Claudish
Interactive Mode (default):
# Shows model selector, persistent session
claudish
Single-shot Mode:
# One task and exit (requires --model)
claudish --model x-ai/grok-code-fast-1 "implement user authentication"
With stdin for large prompts:
# Read prompt from stdin (useful for git diffs, code review)
git diff | claudish --stdin --model openai/gpt-5-codex "Review these changes"
Recommended Models
Top Models for Development (verified from OpenRouter):
# List all models (auto-updates every 2 days)
claudish --models
# Search for specific models
claudish --models grok
claudish --models "gemini flash"# Show curated top models
claudish --top-models
# Force immediate update
claudish --models --force-update
NEW: Direct Agent Selection (v2.1.0)
Use --agent flag to invoke agents directly without the file-based pattern:
# Use specific agent (prepends @agent- automatically)
claudish --model x-ai/grok-code-fast-1 "implement React component"# Claude receives: "Use the @agent-frontend:developer agent to: implement React component"# List available agents in project
claudish --list-agents
When to use --agent vs file-based pattern:
Use --agent when:
Single, simple task that needs agent specialization
// multi-phase-workflow.mdPhase1: Use api-architect to design APIPhase2: Use backend-developer to implement
Phase3: Use test-architect to add tests
Phase4: Use senior-code-reviewer to review
then:
claudish --model x-ai/grok-code-fast-1 --stdin < multi-phase-workflow.md
Best Practice: File-Based Sub-Agent Pattern
⚠️ CRITICAL: Don't Run Claudish Directly from Main Conversation
Why: Running Claudish directly in main conversation pollutes context window with:
Entire conversation transcript
All tool outputs
Model reasoning (can be 10K+ tokens)
Solution: Use file-based sub-agent pattern
File-Based Pattern (Recommended)
Step 1: Create instruction file
# /tmp/claudish-task-{timestamp}.md## Task
Implement user authentication with JWT tokens
## Requirements- Use bcrypt for password hashing
- Generate JWT with 24h expiration
- Add middleware for protected routes
## Deliverables
Write implementation to: /tmp/claudish-result-{timestamp}.md
## Output Format```markdown
## Implementation
[code here]
## Files Created/Modified
- path/to/file1.ts
- path/to/file2.ts
## Tests
[test code if applicable]
## Notes
[any important notes]
**Step 2: Run Claudish with file instruction**
```bash
# Read instruction from file, write result to file
claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-task-{timestamp}.md > /tmp/claudish-result-{timestamp}.md
Step 3: Read result file and provide summary
// In your agent/command:const result = awaitRead({ file_path: "/tmp/claudish-result-{timestamp}.md" });
// Parse resultconst filesModified = extractFilesModified(result);
const summary = extractSummary(result);
// Provide short feedback to main agentreturn`✅ Task completed. Modified ${filesModified.length} files. ${summary}`;
Complete Example: Using Claudish in Sub-Agent
/**
* Example: Run code review with Grok via Claudish sub-agent
*/asyncfunctionrunCodeReviewWithGrok(files: string[]) {
const timestamp = Date.now();
const instructionFile = `/tmp/claudish-review-instruction-${timestamp}.md`;
const resultFile = `/tmp/claudish-review-result-${timestamp}.md`;
// Step 1: Create instruction fileconst instruction = `# Code Review Task
## Files to Review
${files.map(f => `- ${f}`).join('\n')}
## Review Criteria
- Code quality and maintainability
- Potential bugs or issues
- Performance considerations
- Security vulnerabilities
## Output Format
Write your review to: ${resultFile}
Use this format:
\`\`\`markdown
## Summary
[Brief overview]
## Issues Found
### Critical
- [issue 1]
### Medium
- [issue 2]
### Low
- [issue 3]
## Recommendations
- [recommendation 1]
## Files Reviewed
- [file 1]: [status]
\`\`\`
`;
awaitWrite({ file_path: instructionFile, content: instruction });
// Step 2: Run Claudish with stdinawaitBash(`claudish --model x-ai/grok-code-fast-1 --stdin < ${instructionFile}`);
// Step 3: Read resultconst result = awaitRead({ file_path: resultFile });
// Step 4: Parse and return summaryconst summary = extractSummary(result);
const issueCount = extractIssueCount(result);
// Step 5: Clean up temp filesawaitBash(`rm ${instructionFile}${resultFile}`);
// Step 6: Return concise feedbackreturn {
success: true,
summary,
issueCount,
fullReview: result // Available if needed, but not in main context
};
}
functionextractSummary(review: string): string {
const match = review.match(/## Summary\s*\n(.*?)(?=\n##|$)/s);
return match ? match[1].trim() : "Review completed";
}
functionextractIssueCount(review: string): { critical: number; medium: number; low: number } {
const critical = (review.match(/### Critical\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
const medium = (review.match(/### Medium\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
const low = (review.match(/### Low\s*\n(.*?)(?=\n###|$)/s)?.[1].match(/^-/gm) || []).length;
return { critical, medium, low };
}
Sub-Agent Delegation Pattern
When running Claudish from an agent, use the Task tool to create a sub-agent:
Pattern 1: Simple Task Delegation
/**
* Example: Delegate implementation to Grok via Claudish
*/asyncfunctionimplementFeatureWithGrok(featureDescription: string) {
// Use Task tool to create sub-agentconst result = awaitTask({
subagent_type: "general-purpose",
description: "Implement feature with Grok",
prompt: `
Use Claudish CLI to implement this feature with Grok model:
${featureDescription}
INSTRUCTIONS:
1. Search for available models:
claudish --models grok
2. Run implementation with Grok:
claudish --model x-ai/grok-code-fast-1 "${featureDescription}"
3. Return ONLY:
- List of files created/modified
- Brief summary (2-3 sentences)
- Any errors encountered
DO NOT return the full conversation transcript or implementation details.
Keep your response under 500 tokens.
`
});
return result;
}
Pattern 2: File-Based Task Delegation
/**
* Example: Use file-based instruction pattern in sub-agent
*/asyncfunctionanalyzeCodeWithGemini(codebasePath: string) {
const timestamp = Date.now();
const instructionFile = `/tmp/claudish-analyze-${timestamp}.md`;
const resultFile = `/tmp/claudish-analyze-result-${timestamp}.md`;
// Create instruction fileconst instruction = `# Codebase Analysis Task
## Codebase Path
${codebasePath}
## Analysis Required
- Architecture overview
- Key patterns used
- Potential improvements
- Security considerations
## Output
Write analysis to: ${resultFile}
Keep analysis concise (under 1000 words).
`;
awaitWrite({ file_path: instructionFile, content: instruction });
// Delegate to sub-agentconst result = awaitTask({
subagent_type: "general-purpose",
description: "Analyze codebase with Gemini",
prompt: `
Use Claudish to analyze codebase with Gemini model.
Instruction file: ${instructionFile}
Result file: ${resultFile}
STEPS:
1. Read instruction file: ${instructionFile}
2. Run: claudish --model google/gemini-2.5-flash --stdin < ${instructionFile}
3. Wait for completion
4. Read result file: ${resultFile}
5. Return ONLY a 2-3 sentence summary
DO NOT include the full analysis in your response.
The full analysis is in ${resultFile} if needed.
`
});
// Read full result if neededconst fullAnalysis = awaitRead({ file_path: resultFile });
// Clean upawaitBash(`rm ${instructionFile}${resultFile}`);
return {
summary: result,
fullAnalysis
};
}
Pattern 3: Multi-Model Comparison
/**
* Example: Run same task with multiple models and compare
*/asyncfunctioncompareModels(task: string, models: string[]) {
const results = [];
for (const model of models) {
const timestamp = Date.now();
const resultFile = `/tmp/claudish-${model.replace('/', '-')}-${timestamp}.md`;
// Run task with each modelawaitTask({
subagent_type: "general-purpose",
description: `Run task with ${model}`,
prompt: `
Use Claudish to run this task with ${model}:
${task}
STEPS:
1. Run: claudish --model ${model} --json "${task}"
2. Parse JSON output
3. Return ONLY:
- Cost (from total_cost_usd)
- Duration (from duration_ms)
- Token usage (from usage.input_tokens and usage.output_tokens)
- Brief quality assessment (1-2 sentences)
DO NOT return full output.
`
});
results.push({
model,
resultFile
});
}
return results;
}
Common Workflows
Workflow 1: Quick Code Generation with Grok
# Fast, agentic coding with visible reasoning
claudish --model x-ai/grok-code-fast-1 "add error handling to api routes"
Workflow 2: Complex Refactoring with GPT-5
# Advanced reasoning for complex tasks
claudish --model openai/gpt-5 "refactor authentication system to use OAuth2"
Workflow 3: UI Implementation with Qwen (Vision)
# Vision-language model for UI tasks
claudish --model qwen/qwen3-vl-235b-a22b-instruct "implement dashboard from figma design"
Workflow 4: Code Review with Gemini
# State-of-the-art reasoning for thorough review
git diff | claudish --stdin --model google/gemini-2.5-flash "Review these changes for bugs and improvements"
Workflow 5: Multi-Model Consensus
# Run same task with multiple modelsfor model in"x-ai/grok-code-fast-1""google/gemini-2.5-flash""openai/gpt-5"; doecho"=== Testing with $model ==="
claudish --model "$model""find security vulnerabilities in auth.ts"done
Claudish CLI Flags Reference
Essential Flags
Flag
Description
Example
--model <model>
OpenRouter model to use
--model x-ai/grok-code-fast-1
--stdin
Read prompt from stdin
git diff | claudish --stdin --model grok
--models
List all models or search
claudish --models or claudish --models gemini
--top-models
Show top recommended models
claudish --top-models
--json
JSON output (implies --quiet)
claudish --json "task"
--help-ai
Print AI agent usage guide
claudish --help-ai
Advanced Flags
Flag
Description
Default
--interactive / -i
Interactive mode
Auto (no prompt = interactive)
--quiet / -q
Suppress log messages
Quiet in single-shot
--verbose / -v
Show log messages
Verbose in interactive
--debug / -d
Enable debug logging to file
Disabled
--port <port>
Proxy server port
Random (3000-9000)
--no-auto-approve
Require permission prompts
Auto-approve enabled
--dangerous
Disable sandbox
Disabled
--monitor
Proxy to real Anthropic API (debug)
Disabled
--force-update
Force refresh model cache
Auto (>2 days)
Output Modes
Quiet Mode (default in single-shot)
claudish --model grok "task"# Clean output, no [claudish] logs
Verbose Mode
claudish --verbose "task"# Shows all [claudish] logs for debugging
awaitTask({
subagent_type: "general-purpose",
description: "Task with Claudish",
prompt: "Use claudish --model grok '...' and return summary only"
});
5. ✅ Update Models Regularly
Why: Get latest model recommendations
How:
# Auto-updates every 2 days
claudish --models
# Search for specific models
claudish --models deepseek
# Force update now
claudish --models --force-update
❌❌❌ NEVER Run Claudish Directly in Main Conversation (CRITICAL)
This is the #1 mistake. Never do this unless user explicitly requests it.
WRONG - Destroys context window:
// ❌ NEVER DO THIS - Pollutes main context with 10K+ tokensawaitBash("claudish --model grok 'implement feature'");
// ❌ NEVER DO THIS - Full conversation in main contextawaitBash("claudish --model gemini 'review code'");
// ❌ NEVER DO THIS - Even with --json, output is hugeconst result = awaitBash("claudish --json --model gpt-5 'refactor'");
RIGHT - Always use sub-agents:
// ✅ ALWAYS DO THIS - Delegate to sub-agentconst result = awaitTask({
subagent_type: "general-purpose", // or specific agentdescription: "Implement feature with Grok",
prompt: `
Use Claudish to implement the feature with Grok model.
CRITICAL INSTRUCTIONS:
1. Create instruction file: /tmp/claudish-task-${Date.now()}.md
2. Write detailed task requirements to file
3. Run: claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-task-*.md
4. Read result file and return ONLY a 2-3 sentence summary
DO NOT return full implementation or conversation.
Keep response under 300 tokens.
`
});
// ✅ Even better - Use specialized agent if availableconst result = awaitTask({
subagent_type: "backend-developer", // or frontend-dev, etc.description: "Implement with external model",
prompt: `
Use Claudish with x-ai/grok-code-fast-1 model to implement authentication.
Follow file-based instruction pattern.
Return summary only.
`
});
When you CAN run directly (rare exceptions):
// ✅ Only when user explicitly requests// User: "Run claudish directly in main context for debugging"if (userExplicitlyRequestedDirect) {
awaitBash("claudish --model grok 'task'");
}
Problem: User provides a custom model ID that's not in --top-models
Wrong (rejecting custom models):
const availableModels = ["x-ai/grok-code-fast-1", "openai/gpt-5"];
const userModel = "custom/provider/model-123";
if (!availableModels.includes(userModel)) {
thrownewError("Model not in my shortlist"); // ❌ DON'T DO THIS
}
Right (accept any valid model ID):
// Claudish accepts ANY valid OpenRouter model ID, even if not in --top-modelsconst userModel = "custom/provider/model-123";
// Validate it's a non-empty string with provider formatif (!userModel.includes("/")) {
console.warn("Model should be in format: provider/model-name");
}
// Use it directly - Claudish will validate with OpenRouterawaitBash(`claudish --model ${userModel} "task"`);
Scenario: User says "use my custom model X" and expects it to be remembered
Solution 1: Environment Variable (Recommended)
// Set for the session
process.env.CLAUDISH_MODEL = userPreferredModel;
// Or set permanently in user's shell profileawaitBash(`echo 'export CLAUDISH_MODEL="${userPreferredModel}"' >> ~/.zshrc`);
Solution 2: Session Cache
// Store in a temporary session fileconst sessionFile = "/tmp/claudish-user-preferences.json";
const prefs = {
preferredModel: userPreferredModel,
lastUsed: newDate().toISOString()
};
awaitWrite({ file_path: sessionFile, content: JSON.stringify(prefs, null, 2) });
// Load in subsequent commandsconst { stdout } = awaitRead({ file_path: sessionFile });
const prefs = JSON.parse(stdout);
const model = prefs.preferredModel || defaultModel;
Solution 3: Prompt Once, Remember for Session
// In a multi-step workflow, ask onceif (!process.env.CLAUDISH_MODEL) {
const { stdout } = awaitBash("claudish --models --json");
const models = JSON.parse(stdout).models;
const response = awaitAskUserQuestion({
question: "Select model (or enter custom model ID):",
options: models.map((m, i) => ({ label: m.name, value: m.id })).concat([
{ label: "Enter custom model...", value: "custom" }
])
});
if (response === "custom") {
const customModel = awaitAskUserQuestion({
question: "Enter OpenRouter model ID (format: provider/model):"
});
process.env.CLAUDISH_MODEL = customModel;
} else {
process.env.CLAUDISH_MODEL = response;
}
}
// Use the selected model for all subsequent callsconst model = process.env.CLAUDISH_MODEL;
awaitBash(`claudish --model ${model} "task 1"`);
awaitBash(`claudish --model ${model} "task 2"`);
Guidance for Agents:
✅ Accept any model ID user provides (unless obviously malformed)
✅ Don't filter based on your "shortlist" - let Claudish handle validation
✅ Offer to set CLAUDISH_MODEL environment variable for session persistence
✅ Explain that --top-models shows curated recommendations, --models shows all
✅ Validate format (should contain "/") but not restrict to known models
❌ Never reject a user's custom model with "not in my shortlist"
❌ Don't Skip Error Handling
Wrong:
const result = awaitBash("claudish --model grok 'task'");
Right:
try {
const result = awaitBash("claudish --model grok 'task'");
} catch (error) {
console.error("Claudish failed:", error.message);
// Fallback to embedded Claude or handle error
}
