claudish-usage

# 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 > **Note:** External models are invoked via Bash+claudish CLI with `--model` flag. > The `--agent` flag gives the external model specialized capabilities. | Task Type | Recommended `--agent` | Alternatives | Notes | |-----------|----------------------|--------------|-------| | **Investigation** | `dev:researcher` | `code-analysis:detective` | For finding bugs, tracing issues | | **Code review** | `agentdev:reviewer` | `frontend:reviewer` | Check if plugin has review agent | | **Architecture** | `dev:architect` | `frontend:architect` | Design and planning tasks | | **Implementation** | `dev:developer` | `frontend:developer` | Building features | | **Testing** | `dev:test-architect` | — | Test strategy and coverage | | **Debugging** | `dev:debugger` | — | Error analysis and tracing | | **Documentation** | `dev:researcher` | — | Simple task, researcher works | | **UI/Design** | `dev:ui` | `frontend:designer` | Visual and UX tasks | ### 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 ``` ## Team Mode Integration When used with the `/team` command for multi-model blind voting: **External models are invoked via Bash+claudish CLI (deterministic, 100% reliable):** ```bash claudish --model x-ai/grok-code-fast-1 --stdin --quiet \ < "ai-docs/sessions/team-xyz/vote-prompt.md" \ > "ai-docs/sessions/team-xyz/grok-result.md" \ 2>"ai-docs/sessions/team-xyz/grok-stderr.log"; \ echo $? > "ai-docs/sessions/team-xyz/grok.exit" ``` The `--agent` flag is **required** to give the external model specialized capabilities (e.g., claudemem search, structured investigation workflow). ## 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) - ✅ Supports **multiple backends** (OpenRouter, Gemini Direct, OpenAI Direct, Ollama, etc.) - ✅ 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 ## Claudish Multi-Backend Routing **CRITICAL:** Claudish supports MULTIPLE backends, not just OpenRouter. The model ID prefix determines which backend processes your request. ### Backend Routing Table | Prefix | Backend | Required API Key | Example Model ID | |--------|---------|------------------|------------------| | (none) | OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-3.5-sonnet` | | `or/` | OpenRouter (explicit) | `OPENROUTER_API_KEY` | `google/gemini-3-pro-preview` | | `g/` `gemini/` `google/` | Google Gemini Direct | `GEMINI_API_KEY` | `g/gemini-2.0-flash` | | `oai/` `openai/` | OpenAI Direct | `OPENAI_API_KEY` | `oai/gpt-4o` | | `ollama/` `ollama:` | Ollama (local) | None | `ollama/llama3.2` | | `lmstudio/` | LM Studio (local) | None | `lmstudio/qwen2.5-coder` | | `vllm/` | vLLM (local) | None | `vllm/mistral-7b` | | `mlx/` | MLX (local) | None | `mlx/llama-3.2-3b` | | `http://...` | Custom endpoint | None | `http://192.168.1.50:8000/model` | ### ⚠️ Prefix Collision Warning **CRITICAL:** Some OpenRouter model IDs START with prefixes that claudish interprets as direct API routing! | Model ID | Claudish Routes To | Problem | Fix | |----------|-------------------|---------|-----| | `google/gemini-3-pro-preview` | Google Gemini Direct | Needs `GEMINI_API_KEY`, different API | Use `google/gemini-3-pro-preview` | | `google/gemini-2.5-flash` | Google Gemini Direct | Needs `GEMINI_API_KEY`, different API | Use `google/gemini-2.5-flash` | | `openai/gpt-5.1-codex` | OpenAI Direct | Needs `OPENAI_API_KEY`, different API | Use `openai/gpt-5.1-codex` | | `openai/gpt-5` | OpenAI Direct | Needs `OPENAI_API_KEY`, different API | Use `openai/gpt-5` | ### Safe Model IDs (No Collision) These OpenRouter model IDs are SAFE to use without the `or/` prefix: - `x-ai/grok-code-fast-1` - No `x-ai/` prefix in claudish - `anthropic/claude-3.5-sonnet` - No `anthropic/` prefix in claudish - `deepseek/deepseek-chat` - No `deepseek/` prefix in claudish - `minimax/minimax-m2` - No `minimax/` prefix in claudish - `qwen/qwen3-coder:free` - No `qwen/` prefix in claudish - `mistralai/devstral-2512:free` - No `mistralai/` prefix in claudish - `moonshotai/kimi-k2-thinking` - No `moonshotai/` prefix in claudish ### When to Use `or/` Prefix **ALWAYS use `or/` prefix when:** 1. The OpenRouter model ID starts with `google/`, `openai/`, `g/`, `oai/` 2. You want to GUARANTEE OpenRouter routing regardless of model ID 3. You're unsure if the model ID might collide **Examples:** ```bash # WRONG - Routes to Google Gemini Direct (needs GEMINI_API_KEY) claudish --model google/gemini-3-pro-preview # CORRECT - Routes to OpenRouter (needs OPENROUTER_API_KEY) claudish --model google/gemini-3-pro-preview # SAFE - No collision (x-ai/ is not a routing prefix) claudish --model x-ai/grok-code-fast-1 ``` ## 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 # OpenRouter (required for most models) export OPENROUTER_API_KEY='sk-or-v1-...' # Google Gemini Direct (optional - for g/gemini/google/ prefixed models) export GEMINI_API_KEY='AIza...' # OpenAI Direct (optional - for oai/openai/ prefixed models) export OPENAI_API_KEY='sk-...' # Note: Ollama, LM Studio, vLLM, MLX backends don't need API keys # 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)