Collection

---
name: claudish-usage
description: 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:**

1. **Check for existing agents** that support proxy mode or external model delegation
2. **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
3. **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

```bash
# Required
export 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 model
export CLAUDISH_MODEL='x-ai/grok-code-fast-1'  # or ANTHROPIC_MODEL
```

**Get OpenRouter API Key:**

1. Visit https://openrouter.ai/keys
2. Sign up (free tier available)
3. Create API key
4. Set as environment variable

## Quick Start Guide

### Step 1: Install Claudish

```bash
# With npm (works everywhere)
npm install -g claudish

# With Bun (faster)
bun install -g claudish

# Verify installation
claudish --version
```

### Step 2: Get Available Models

```bash
# 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):**

```bash
# Shows model selector, persistent session
claudish
```

**Single-shot Mode:**

```bash
# One task and exit (requires --model)
claudish --model x-ai/grok-code-fast-1 "implement user authentication"
```

**With stdin for large prompts:**

```bash
# 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):**

1. **x-ai/grok-code-fast-1** - xAI's Grok (fast coding, visible reasoning)
   - Category: coding
   - Context: 256K
   - Best for: Quick iterations, agentic coding

2. **google/gemini-2.5-flash** - Google's Gemini (state-of-the-art reasoning)
   - Category: reasoning
   - Context: 1000K
   - Best for: Complex analysis, multi-step reasoning

3. **minimax/minimax-m2** - MiniMax M2 (high performance)
   - Category: coding
   - Context: 128K
   - Best for: General coding tasks

4. **openai/gpt-5** - OpenAI's GPT-5 (advanced reasoning)
   - Category: reasoning
   - Context: 128K
   - Best for: Complex implementations, architecture decisions

5. **qwen/qwen3-vl-235b-a22b-instruct** - Alibaba's Qwen (vision-language)
   - Category: vision
   - Context: 32K
   - Best for: UI/visual tasks, design implementation

**Get Latest Models:**

```bash
# 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:**

```bash
# Use specific agent (prepends @agent- automatically)
claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "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
- Direct conversation with one agent
- Testing agent behavior
- CLI convenience

**Use file-based pattern when:**

- Complex multi-step workflows
- Multiple agents needed
- Large codebases
- Production tasks requiring review
- Need isolation from main conversation

**Example comparisons:**

**Simple task (use `--agent`):**

```bash
claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "create button component"
```

**Complex task (use file-based):**

```typescript
// multi-phase-workflow.md
Phase 1: Use api-architect to design API
Phase 2: Use backend-developer to implement
Phase 3: Use test-architect to add tests
Phase 4: 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**

````markdown
# /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**

```typescript
// In your agent/command:
const result = await Read({ file_path: '/tmp/claudish-result-{timestamp}.md' })

// Parse result
const filesModified = extractFilesModified(result)
const summary = extractSummary(result)

// Provide short feedback to main agent
return `✅ Task completed. Modified ${filesModified.length} files. ${summary}`
```

### Complete Example: Using Claudish in Sub-Agent

```typescript
/**
 * Example: Run code review with Grok via Claudish sub-agent
 */
async function runCodeReviewWithGrok(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 file
  const 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]
\`\`\`
`

  await Write({ file_path: instructionFile, content: instruction })

  // Step 2: Run Claudish with stdin
  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: Parse and return summary
  const summary = extractSummary(result)
  const issueCount = extractIssueCount(result)

  // Step 5: Clean up temp files
  await Bash(`rm ${instructionFile} ${resultFile}`)

  // Step 6: Return concise feedback
  return {
    success: true,
    summary,
    issueCount,
    fullReview: result, // Available if needed, but not in main context
  }
}

function extractSummary(review: string): string {
  const match = review.match(/## Summary\s*\n(.*?)(?=\n##|$)/s)
  return match ? match[1].trim() : 'Review completed'
}

function extractIssueCount(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

```typescript
/**
 * Example: Delegate implementation to Grok via Claudish
 */
async function implementFeatureWithGrok(featureDescription: string) {
  // Use Task tool to create sub-agent
  const result = await Task({
    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

```typescript
/**
 * Example: Use file-based instruction pattern in sub-agent
 */
async function analyzeCodeWithGemini(codebasePath: string) {
  const timestamp = Date.now()
  const instructionFile = `/tmp/claudish-analyze-${timestamp}.md`
  const resultFile = `/tmp/claudish-analyze-result-${timestamp}.md`

  // Create instruction file
  const 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).
`

  await Write({ file_path: instructionFile, content: instruction })

  // Delegate to sub-agent
  const result = await Task({
    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 needed
  const fullAnalysis = await Read({ file_path: resultFile })

  // Clean up
  await Bash(`rm ${instructionFile} ${resultFile}`)

  return {
    summary: result,
    fullAnalysis,
  }
}
```

### Pattern 3: Multi-Model Comparison

```typescript
/**
 * Example: Run same task with multiple models and compare
 */
async function compareModels(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 model
    await Task({
      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

```bash
# 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

```bash
# Advanced reasoning for complex tasks
claudish --model openai/gpt-5 "refactor authentication system to use OAuth2"
```

### Workflow 3: UI Implementation with Qwen (Vision)

```bash
# 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

```bash
# 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

```bash
# Run same task with multiple models
for model in "x-ai/grok-code-fast-1" "google/gemini-2.5-flash" "openai/gpt-5"; do
  echo "=== 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

1. **Quiet Mode (default in single-shot)**

   ```bash
   claudish --model grok "task"
   # Clean output, no [claudish] logs
   ```

2. **Verbose Mode**

   ```bash
   claudish --verbose "task"
   # Shows all [claudish] logs for debugging
   ```

3. **JSON Mode**
   ```bash
   claudish --json "task"
   # Structured output: {result, cost, usage, duration}
   ```

## Cost Tracking

Claudish automatically tracks costs in the status line:

```
directory • model-id • $cost • ctx%
```

**Example:**

```
my-project • x-ai/grok-code-fast-1 • $0.12 • 67%
```

Shows:

- 💰 **Cost**: $0.12 USD spent in current session
- 📊 **Context**: 67% of context window remaining

**JSON Output Cost:**

```bash
claudish --json "task" | jq '.total_cost_usd'
# Output: 0.068
```

## Error Handling

### Error 1: OPENROUTER_API_KEY Not Set

**Error:**

```
Error: OPENROUTER_API_KEY environment variable is required
```

**Fix:**

```bash
export OPENROUTER_API_KEY='sk-or-v1-...'
# Or add to ~/.zshrc or ~/.bashrc
```

### Error 2: Claudish Not Installed

**Error:**

```
command not found: claudish
```

**Fix:**

```bash
npm install -g claudish
# Or: bun install -g claudish
```

### Error 3: Model Not Found

**Error:**

```
Model 'invalid/model' not found
```

**Fix:**

```bash
# List available models
claudish --models

# Use valid model ID
claudish --model x-ai/grok-code-fast-1 "task"
```

### Error 4: OpenRouter API Error

**Error:**

```
OpenRouter API error: 401 Unauthorized
```

**Fix:**

1. Check API key is correct
2. Verify API key at https://openrouter.ai/keys
3. Check API key has credits (free tier or paid)

### Error 5: Port Already in Use

**Error:**

```
Error: Port 3000 already in use
```

**Fix:**

```bash
# Let Claudish pick random port (default)
claudish --model grok "task"

# Or specify different port
claudish --port 8080 --model grok "task"
```

## Best Practices

### 1. ✅ Use File-Based Instructions

**Why:** Avoids context window pollution

**How:**

```bash
# Write instruction to file
echo "Implement feature X" > /tmp/task.md

# Run with stdin
claudish --stdin --model grok < /tmp/task.md > /tmp/result.md

# Read result
cat /tmp/result.md
```

### 2. ✅ Choose Right Model for Task

**Fast Coding:** `x-ai/grok-code-fast-1`
**Complex Reasoning:** `google/gemini-2.5-flash` or `openai/gpt-5`
**Vision/UI:** `qwen/qwen3-vl-235b-a22b-instruct`

### 3. ✅ Use --json for Automation

**Why:** Structured output, easier parsing

**How:**

```bash
RESULT=$(claudish --json "task" | jq -r '.result')
COST=$(claudish --json "task" | jq -r '.total_cost_usd')
```

### 4. ✅ Delegate to Sub-Agents

**Why:** Keeps main conversation context clean

**How:**

```typescript
await Task({
  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:**

```bash
# Auto-updates every 2 days
claudish --models

# Search for specific models
claudish --models deepseek

# Force update now
claudish --models --force-update
```

### 6. ✅ Use --stdin for Large Prompts

**Why:** Avoid command line length limits

**How:**

```bash
git diff | claudish --stdin --model grok "Review changes"
```

## Anti-Patterns (Avoid These)

### ❌❌❌ 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:**

```typescript
// ❌ NEVER DO THIS - Pollutes main context with 10K+ tokens
await Bash("claudish --model grok 'implement feature'")

// ❌ NEVER DO THIS - Full conversation in main context
await Bash("claudish --model gemini 'review code'")

// ❌ NEVER DO THIS - Even with --json, output is huge
const result = await Bash("claudish --json --model gpt-5 'refactor'")
```

**RIGHT - Always use sub-agents:**

```typescript
// ✅ ALWAYS DO THIS - Delegate to sub-agent
const result = await Task({
  subagent_type: 'general-purpose', // or specific agent
  description: '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 available
const result = await Task({
  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):**

```typescript
// ✅ Only when user explicitly requests
// User: "Run claudish directly in main context for debugging"
if (userExplicitlyRequestedDirect) {
  await Bash("claudish --model grok 'task'")
}
```

### ❌ Don't Ignore Model Selection

**Wrong:**

```bash
# Always using default model
claudish "any task"
```

**Right:**

```bash
# Choose appropriate model
claudish --model x-ai/grok-code-fast-1 "quick fix"
claudish --model google/gemini-2.5-flash "complex analysis"
```

### ❌ Don't Parse Text Output

**Wrong:**

```bash
OUTPUT=$(claudish --model grok "task")
COST=$(echo "$OUTPUT" | grep cost | awk '{print $2}')
```

**Right:**

```bash
# Use JSON output
COST=$(claudish --json --model grok "task" | jq -r '.total_cost_usd')
```

### ❌ Don't Hardcode Model Lists

**Wrong:**

```typescript
const MODELS = ['x-ai/grok-code-fast-1', 'openai/gpt-5']
```

**Right:**

```typescript
// Query dynamically
const { stdout } = await Bash('claudish --models --json')
const models = JSON.parse(stdout).models.map((m) => m.id)
```

### ✅ Do Accept Custom Models From Users

**Problem:** User provides a custom model ID that's not in --top-models

**Wrong (rejecting custom models):**

```typescript
const availableModels = ['x-ai/grok-code-fast-1', 'openai/gpt-5']
const userModel = 'custom/provider/model-123'

if (!availableModels.includes(userModel)) {
  throw new Error('Model not in my shortlist') // ❌ DON'T DO THIS
}
```

**Right (accept any valid model ID):**

```typescript
// Claudish accepts ANY valid OpenRouter model ID, even if not in --top-models
const userModel = 'custom/provider/model-123'

// Validate it's a non-empty string with provider format
if (!userModel.includes('/')) {
  console.warn('Model should be in format: provider/model-name')
}

// Use it directly - Claudish will validate with OpenRouter
await Bash(`claudish --model ${userModel} "task"`)
```

**Why:** Users may have access to:

- Beta/experimental models
- Private/custom fine-tuned models
- Newly released models not yet in rankings
- Regional/enterprise models
- Cost-saving alternatives

**Always accept user-provided model IDs** unless they're clearly invalid (empty, wrong format).

### ✅ Do Handle User-Preferred Models

**Scenario:** User says "use my custom model X" and expects it to be remembered

**Solution 1: Environment Variable (Recommended)**

```typescript
// Set for the session
process.env.CLAUDISH_MODEL = userPreferredModel

// Or set permanently in user's shell profile
await Bash(`echo 'export CLAUDISH_MODEL="${userPreferredModel}"' >> ~/.zshrc`)
```

**Solution 2: Session Cache**

```typescript
// Store in a temporary session file
const sessionFile = '/tmp/claudish-user-preferences.json'
const prefs = {
  preferredModel: userPreferredModel,
  lastUsed: new Date().toISOString(),
}
await Write({ file_path: sessionFile, content: JSON.stringify(prefs, null, 2) })

// Load in subsequent commands
const { stdout } = await Read({ file_path: sessionFile })
const prefs = JSON.parse(stdout)
const model = prefs.preferredModel || defaultModel
```

**Solution 3: Prompt Once, Remember for Session**

```typescript
// In a multi-step workflow, ask once
if (!process.env.CLAUDISH_MODEL) {
  const { stdout } = await Bash('claudish --models --json')
  const models = JSON.parse(stdout).models

  const response = await AskUserQuestion({
    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 = await AskUserQuestion({
      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 calls
const model = process.env.CLAUDISH_MODEL
await Bash(`claudish --model ${model} "task 1"`)
await Bash(`claudish --model ${model} "task 2"`)
```

**Guidance for Agents:**

1. ✅ **Accept any model ID** user provides (unless obviously malformed)
2. ✅ **Don't filter** based on your "shortlist" - let Claudish handle validation
3. ✅ **Offer to set CLAUDISH_MODEL** environment variable for session persistence
4. ✅ **Explain** that --top-models shows curated recommendations, --models shows all
5. ✅ **Validate format** (should contain "/") but not restrict to known models
6. ❌ **Never reject** a user's custom model with "not in my shortlist"

### ❌ Don't Skip Error Handling

**Wrong:**

```typescript
const result = await Bash("claudish --model grok 'task'")
```

**Right:**

```typescript
try {
  const result = await Bash("claudish --model grok 'task'")
} catch (error) {
  console.error('Claudish failed:', error.message)
  // Fallback to embedded Claude or handle error
}
```

## Agent Integration Examples

### Example 1: Code Review Agent

```typescript
/**
 * Agent: code-reviewer (using Claudish with multiple models)
 */
async function reviewCodeWithMultipleModels(files: string[]) {
  const models = [
    'x-ai/grok-code-fast-1', // Fast initial scan
    'google/gemini-2.5-flash', // Deep analysis
    'openai/gpt-5', // Final validation
  ]

  const reviews = []

  for (const model of models) {
    const timestamp = Date.now()
    const instructionFile = `/tmp/review-${model.replace('/', '-')}-${timestamp}.md`
    const resultFile = `/tmp/review-result-${model.replace('/', '-')}-${timestamp}.md`

    // Create instruction
    const instruction = createReviewInstruction(files, resultFile)
    await Write({ file_path: instructionFile, content: instruction })

    // Run review with model
    await Bash(`claudish --model ${model} --stdin < ${instructionFile}`)

    // Read result
    const result = await Read({ file_path: resultFile })

    // Extract summary
    reviews.push({
      model,
      summary: extractSummary(result),
      issueCount: extractIssueCount(result),
    })

    // Clean up
    await Bash(`rm ${instructionFile} ${resultFile}`)
  }

  return reviews
}
```

### Example 2: Feature Implementation Command

```typescript
/**
 * Command: /implement-with-model
 * Usage: /implement-with-model "feature description"
 */
async function implementWithModel(featureDescription: string) {
  // Step 1: Get available models
  const { stdout } = await Bash('claudish --models --json')
  const models = JSON.parse(stdout).models

  // Step 2: Let user select model
  const selectedModel = await promptUserForModel(models)

  // Step 3: Create instruction file
  const timestamp = Date.now()
  const instructionFile = `/tmp/implement-${timestamp}.md`
  const resultFile = `/tmp/implement-result-${timestamp}.md`

  const instruction = `# Feature Implementation

## Description
${featureDescription}

## Requirements
- Write clean, maintainable code
- Add comprehensive tests
- Include error handling
- Follow project conventions

## Output
Write implementation details to: ${resultFile}

Include:
- Files created/modified
- Code snippets
- Test coverage
- Documentation updates
`

  await Write({ file_path: instructionFile, content: instruction })

  // Step 4: Run implementation
  await Bash(`claudish --model ${selectedModel} --stdin < ${instructionFile}`)

  // Step 5: Read and present results
  const result = await Read({ file_path: resultFile })

  // Step 6: Clean up
  await Bash(`rm ${instructionFile} ${resultFile}`)

  return result
}
```

## Troubleshooting

### Issue: Slow Performance

**Symptoms:** Claudish takes long time to respond

**Solutions:**

1. Use faster model: `x-ai/grok-code-fast-1` or `minimax/minimax-m2`
2. Reduce prompt size (use --stdin with concise instructions)
3. Check internet connection to OpenRouter

### Issue: High Costs

**Symptoms:** Unexpected API costs

**Solutions:**

1. Use budget-friendly models (check pricing with `--models` or `--top-models`)
2. Enable cost tracking: `--cost-tracker`
3. Use --json to monitor costs: `claudish --json "task" | jq '.total_cost_usd'`

### Issue: Context Window Exceeded

**Symptoms:** Error about token limits

**Solutions:**

1. Use model with larger context (Gemini: 1000K, Grok: 256K)
2. Break task into smaller subtasks
3. Use file-based pattern to avoid conversation history

### Issue: Model Not Available

**Symptoms:** "Model not found" error

**Solutions:**

1. Update model cache: `claudish --models --force-update`
2. Check OpenRouter website for model availability
3. Use alternative model from same category

## Additional Resources

**Documentation:**

- Full README: `mcp/claudish/README.md` (in repository root)
- AI Agent Guide: Print with `claudish --help-ai`
- Model Integration: `skills/claudish-integration/SKILL.md` (in repository root)

**External Links:**

- Claudish GitHub: https://github.com/MadAppGang/claude-code
- OpenRouter: https://openrouter.ai
- OpenRouter Models: https://openrouter.ai/models
- OpenRouter API Docs: https://openrouter.ai/docs

**Version Information:**

```bash
claudish --version
```

**Get Help:**

```bash
claudish --help        # CLI usage
claudish --help-ai     # AI agent usage guide
```

---

**Maintained by:** MadAppGang
**Last Updated:** November 25, 2025
**Skill Version:** 1.1.0