<div align="center">

🔮 Claudish

Claude Code. Any Model.

Use your existing AI subscriptions with Claude Code. Works with Anthropic Max, Gemini Advanced, ChatGPT Plus/Codex, Kimi, GLM, OllamaCloud — plus 580+ models via OpenRouter and local models for complete privacy.

Website · Documentation · Report Bug

</div>

---

Claudish (Claude-ish) is a CLI tool that allows you to run Claude Code with any AI model by proxying requests through a local Anthropic API-compatible server.

Supported Providers:

• Cloud: OpenRouter (580+ models), Google Gemini, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, OpenCode Zen
• Local: Ollama, LM Studio, vLLM, MLX
• Enterprise: Vertex AI (Google Cloud)

Use Your Existing AI Subscriptions

Stop paying for multiple AI subscriptions. Claudish lets you use subscriptions you already have with Claude Code's powerful interface:

| Your Subscription | Command | |-------------------|---------| | Anthropic Max | Native support (just use claude) | | Gemini Advanced | claudish --model g@gemini-3-pro-preview | | ChatGPT Plus/Codex | claudish --model oai@gpt-5.3 or oai@gpt-5.3-codex | | Kimi | claudish --model kimi@kimi-k2.5 | | GLM | claudish --model glm@GLM-4.7 | | MiniMax | claudish --model mm@minimax-m2.1 | | OllamaCloud | claudish --model oc@qwen3-next | | OpenCode Zen Go | claudish --model zgo@glm-5 |

100% Offline Option — Your code never leaves your machine:

claudish --model ollama@qwen3-coder:latest "your task"

Bring Your Own Key (BYOK)

Claudish is a BYOK AI coding assistant:

• ✅ Use API keys you already have
• ✅ No additional subscription fees
• ✅ Full cost control — pay only for what you use
• ✅ Works with any provider
• ✅ Switch models mid-session

Features

• ✅ Multi-provider support - OpenRouter, Gemini, Vertex AI, OpenAI, OllamaCloud, and local models
• ✅ New routing syntax - Use provider@model[:concurrency] for explicit routing (e.g., google@gemini-2.0-flash)
• ✅ Native auto-detection - Models like gpt-4o, gemini-2.0-flash, llama-3.1-70b route to their native APIs automatically
• ✅ Direct API access - Google, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, Poe with direct billing
• ✅ Vertex AI Model Garden - Access Google + partner models (MiniMax, Mistral, DeepSeek, Qwen, OpenAI OSS)
• ✅ Local model support - Ollama, LM Studio, vLLM, MLX with ollama@, lmstudio@ syntax and concurrency control
• ✅ Cross-platform - Works with both Node.js and Bun (v1.3.0+)
• ✅ Universal compatibility - Use with npx or bunx - no installation required
• ✅ Interactive setup - Prompts for API key and model if not provided (zero config!)
• ✅ Monitor mode - Proxy to real Anthropic API and log all traffic (for debugging)
• ✅ Protocol compliance - 1:1 compatibility with Claude Code communication protocol
• ✅ Headless mode - Automatic print mode for non-interactive execution
• ✅ Quiet mode - Clean output by default (no log pollution)
• ✅ JSON output - Structured data for tool integration
• ✅ Real-time streaming - See Claude Code output as it happens
• ✅ Parallel runs - Each instance gets isolated proxy
• ✅ Autonomous mode - Bypass all prompts with flags
• ✅ Context inheritance - Runs in current directory with same .claude settings
• ✅ Claude Code flag passthrough - Forward any Claude Code flag (--agent, --effort, --permission-mode, etc.) in any order
• ✅ Vision proxy - Non-vision models automatically get image descriptions via Claude, so every model can "see"

Installation

Quick Install

# Shell script (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/MadAppGang/claudish/main/install.sh | bash

# Homebrew (macOS)
brew tap MadAppGang/tap && brew install claudish

# npm
npm install -g claudish

# Bun
bun install -g claudish

Prerequisites

• Claude Code - Claude CLI must be installed
• At least one API key:
  • OpenRouter API Key - Access 100+ models (free tier available)
  • Google Gemini API Key - For direct Gemini access
  • OpenAI API Key - For direct OpenAI access
  • OllamaCloud API Key - For cloud-hosted Ollama models (oc/ prefix)
  • Or local models (Ollama, LM Studio) - No API key needed

Other Install Options

Use without installing:

npx claudish@latest --model x-ai/grok-code-fast-1 "your prompt"
bunx claudish@latest --model x-ai/grok-code-fast-1 "your prompt"

Install from source:

git clone https://github.com/MadAppGang/claudish.git
cd claudish
bun install && bun run build && bun link

Quick Start

Step 0: Initialize Claudish Skill (First Time Only)

# Navigate to your project directory
cd /path/to/your/project

# Install Claudish skill for automatic best practices
claudish --init

# Reload Claude Code to discover the skill

What this does:

• ✅ Installs Claudish usage skill in .claude/skills/claudish-usage/
• ✅ Enables automatic sub-agent delegation
• ✅ Enforces file-based instruction patterns
• ✅ Prevents context window pollution

After running --init, Claude will automatically:

• Use sub-agents when you mention external models (Grok, GPT-5, etc.)
• Follow best practices for Claudish usage
• Suggest specialized agents for different tasks

Option 1: Interactive Mode (Easiest)

# Just run it - will prompt for API key and model
claudish

# Enter your OpenRouter API key when prompted
# Select a model from the list
# Start coding!

Option 2: With Environment Variables

# Set up environment
export OPENROUTER_API_KEY=sk-or-v1-...     # For OpenRouter models
export GEMINI_API_KEY=...                   # For direct Google API
export OPENAI_API_KEY=sk-...                # For direct OpenAI API
export ANTHROPIC_API_KEY=sk-ant-api03-placeholder  # Required placeholder

# Run with auto-detected model
claudish --model gpt-4o "implement user authentication"     # → OpenAI
claudish --model gemini-2.0-flash "add tests"               # → Google

# Or with explicit provider
claudish --model openrouter@anthropic/claude-3.5-sonnet "review code"

Note: In interactive mode, if OPENROUTER_API_KEY is not set, you'll be prompted to enter it. This makes first-time usage super simple!

AI Agent Usage

For AI agents running within Claude Code: Use the dedicated AI agent guide for comprehensive instructions on file-based patterns and sub-agent delegation.

# Print complete AI agent usage guide
claudish --help-ai

# Save guide to file for reference
claudish --help-ai > claudish-agent-guide.md

Quick Reference for AI Agents:

Main Workflow for AI Agents

1. Get available models:

   # List all models or search
   claudish --models
   claudish --models gemini
   
   # Get top recommended models (JSON)
   claudish --top-models --json
   

2. Run Claudish through sub-agent (recommended pattern):

   // Don't run Claudish directly in main conversation
   // Use Task tool to delegate to sub-agent
   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: /tmp/claudish-task-${Date.now()}.md
   2. Write feature requirements to file
   3. Run: claudish --model x-ai/grok-code-fast-1 --stdin < /tmp/claudish-task-*.md
   4. Read result and return ONLY summary (2-3 sentences)
   
   DO NOT return full implementation. Keep response under 300 tokens.
     `
   });
   

3. File-based instruction pattern (avoids context pollution):

   // Write instructions to file
   const instructionFile = `/tmp/claudish-task-${Date.now()}.md`;
   const resultFile = `/tmp/claudish-result-${Date.now()}.md`;
   
   await Write({ file_path: instructionFile, content: `
   # Task
   Your task description here
   
   # Output
   Write results to: ${resultFile}
   ` });
   
   // Run Claudish with stdin
   await Bash(`claudish --model x-ai/grok-code-fast-1 --stdin < ${instructionFile}`);
   
   // Read result
   const result = await Read({ file_path: resultFile });
   
   // Return summary only
   return extractSummary(result);
   

Key Principles:

• ✅ Use file-based patterns to avoid context window pollution
• ✅ Delegate to sub-agents instead of running directly
• ✅ Return summaries only (not full conversation transcripts)
• ✅ Choose appropriate model for task (see --models or --top-models)

Resources:

• Full AI agent guide: claudish --help-ai
• Skill document: skills/claudish-usage/SKILL.md (in repository root)
• Model integration: skills/claudish-integration/SKILL.md (in repository root)

Usage

Basic Syntax

claudish [OPTIONS] <claude-args...>

Options

For the exhaustive reference with all details, see Settings Reference.

| Flag | Short | Description | Default | |------|-------|-------------|---------| | --model <model> | -m | Model to use (provider@model syntax) | Interactive selector | | --model-opus <model> | | Model for Opus role (planning, complex tasks) | | | --model-sonnet <model> | | Model for Sonnet role (default coding) | | | `--m