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, Sakana Fugu, 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 [email protected] or [email protected] | | Kimi | claudish --model [email protected] | | GLM | claudish --model [email protected] | | MiniMax | claudish --model [email protected] | | OllamaCloud | claudish --model oc@qwen3-next | | OpenCode Zen Go | claudish --model zgo@glm-5 | | Alibaba Coding Plan | claudish --model [email protected] | | Alibaba Token Plan | claudish --model [email protected] | | Alibaba PAYG | claudish --model [email protected] | | Muse Code (Meta) | claudish --model [email protected] |

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., [email protected])
• ✅ 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
• ✅ Classifier passthrough - In hybrid setups, keep Claude Code's auto-mode permission classifier on real Claude (Anthropic) while your main loop runs on another provider (--classifier-provider anthropic)
• ✅ 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:

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

• 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: Log in with a subscription you already pay for (no API key)

If you have ChatGPT Plus/Pro, an Antigravity plan, a Kimi or GLM coding plan, a SuperGrok subscription, or Anthropic Max, claudish login uses it directly. No API key, no per-token billing.

claudish login                 # interactive picker of every provider you can log into
claudish login codex           # ChatGPT Plus/Pro (OpenAI's own PKCE flow)
claudish login antigravity     # Gemini via your Antigravity plan
claudish login grok            # SuperGrok / X Premium+
claudish login kimi            # Kimi
claudish login muse            # Muse Code (Meta), or reuse the Muse Code CLI's login
Then just name the model
claudish --model [email protected] "implement user authentication"
claudish --model [email protected] "add tests"

Run claudish --probe [email protected] afterwards to confirm the credential resolved and see which provider will actually serve the request.

Option 2: Interactive Mode

# 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 3: 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 --models-top --json

1. 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.
     
   });

1. 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 --models-top)

• 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 | -m | Model to use (provider@model syntax) | Interactive selector | | --default-provider | | Default provider for bare model routing (v7.0.0+) | Auto-detected | | --model-opus | | Model for Opus role (planning, complex tasks) | | | --model-sonnet | | Model for Sonnet role (default coding) | | | --model-haiku | | Model for Haiku role (fast tasks) | | | --model-subagent | | Model for sub-agents (Task tool) | | | --classifier-provider | | Route the auto-mode permission classifier to native Anthropic (anthropic) | Off | | --classifier-model | | Native Claude model for the classifier passthrough (also enables it) | claude-sonnet-5 | | --profile | -p | Named profile for model mapping | Default profile | | --config | | Use this file as the run's ONLY config (replaces global + project) | | | --op-env | | Load env vars from a 1Password Environment (highest priority) | | | --interactive | -i | Interactive mode (persistent session) | Auto when no prompt | | --auto-approve | -y | Skip permission prompts | false | | --no-auto-approve | | Explicitly enable permission prompts | | | --dangerous | | Pass --dangerouslyDisableSandbox | false | | --port | | Proxy server port | Random (3000-9000) | | --debug-claudish | -d | Enable debug logging to logs/ | false | | --log-level | | Log verbosity: debug, info, minimal | info | | --quiet | -q | Suppress [claudish] messages | Default in single-shot | | --verbose | -v | Show [claudish] messages | Default in interactive | | --json | | JSON output for tool integration (implies --quiet) | false | | --stdin | | Read prompt from stdin | false | | --free | | Show only free models in selector | false | | --monitor | | Proxy to real Anthropic API and log traffic | false | | --summarize-tools | | Summarize tool descriptions (for local models) | false | | --cost-track | | Enable cost tracking (enables monitor mode) | false | | --cost-audit | | Show cost analysis report | | | --cost-reset | | Reset accumulated cost statistics | | | --models [query] | -s (--models-search) | List all models or fuzzy search | | | --models-top | | Show curated recommended models | | | --models-refresh | | Force refresh model cache | | | --init | | Install Claudish skill in current project | | | --mcp | | Run as MCP server | | | login [provider] | | Log in to a subscription provider via OAuth (no argument = interactive picker) | | | logout [provider] | | Clear a provider's OAuth credentials | | | --kimi-logout | | Deprecated alias for claudish logout kimi | | | --help-ai | | Show AI agent usage guide | | | --version | | Show version | | | --help | -h | Show help message | | | -- | | Everything after passes to Claude Code | |

Flag passthrough: Any unrecognized flag is automatically forwarded to Claude Code (e.g., --agent, --effort, --permission-mode).

Environment Variables

Claudish loads provider API keys and model settings (CLAUDISH_MODEL, CLAUDISH_MODEL_*) from .env in the current directory at startup; any other variable there is ignored, so set the rest in your shell. For the full list, see Settings Reference.

API Keys (at least one required for cloud models)

| Variable | Provider | Aliases | |----------|----------|---------| | OPENROUTER_API_KEY | OpenRouter (default backend, 580+ models) | | | GEMINI_API_KEY | Google Gemini (g@, google@) | | | OPENAI_API_KEY | OpenAI (oai@) | | | MINIMAX_API_KEY | MiniMax (mm@, mmax@) | | | MINIMAX_CODING_API_KEY | MiniMax Coding Plan (mmc@) | | | MOONSHOT_API_KEY | Kimi/Moonshot (kimi@) | KIMI_API_KEY | | KIMI_CODING_API_KEY | Kimi Coding Plan (kc@) | Or OAuth via claudish login kimi | | ZHIPU_API_KEY | GLM/Zhipu (glm@) | GLM_API_KEY | | GLM_CODING_API_KEY | GLM Coding Plan (gc@) | ZAI_CODING_API_KEY | | ZAI_API_KEY | Z.AI (zai@) | | | SAKANA_API_KEY | Sakana Fugu (sakana@, fugu@) | | | SAKANA_CODING_API_KEY | Sakana Fugu Subscription (sc@) | SAKANA_API_KEY | | QWEN_CODING_PLAN_API_KEY | Alibaba Coding Plan (qcode@) | _(separate key and host)_ | | QWEN_TOKEN_PLAN_API_KEY | Alibaba Token Plan (qtoken@) | _(separate key and host)_ | | DASHSCOPE_API_KEY | Alibaba PAYG (qpay@) | _(separate key and host)_ | | META_API_KEY | Meta Model API, metered (meta@) | _(never signs the muse@ subscription)_ | | OLLAMA_API_KEY | OllamaCloud (oc@) | | | OPENCODE_API_KEY | OpenCode Zen (zen@) | | | OPENCODE_GO_API_KEY | OpenCode Zen Go plan (zgo@) | _(separate from the metered Zen credential)_ | | LITELLM_API_KEY | LiteLLM (ll@) — requires LITELLM_BASE_URL | | | POE_API_KEY | Poe (poe@) | | | VERTEX_PROJECT | Vertex AI (v@) — optional; the ADC quota project or gcloud config get project is used otherwise | GOOGLE_CLOUD_PROJECT | | ANTHROPIC_API_KEY | Placeholder (suppresses Claude Code dialog) | |

Bundled Endpoint Catalog

25 extra vendors ship inside the package as predefined endpoints. Each appears only when its key is already present locally (env var, alias, or config.apiKeys) — set the variable and vendor@model starts working with no config file. A key that lives only in 1Password does not activate a row (activation is synchronous); use predefinedEndpoints.enable for that case. See Predefined Endpoints.

All 25 rows ship probe-verified — the configured path was confirmed to reach the vendor's own auth layer, and a bogus sibling path to answer differently. None is live-verified: that is strong evidence about routing and weak evidence about a vendor's streaming dialect on a successful turn. The endpoint layer itself was verified end to end against a real API.

| Variable | Provider | Notes | |----------|----------|-------| | GROQ_API_KEY | Groq (groq@) | | | CEREBRAS_API_KEY | Cerebras (cerebras@) | | | TOGETHER_API_KEY | Together AI (together@) | | | FIREWORKS_API_KEY | Fireworks AI (fireworks@) | | | DEEPINFRA_API_KEY | DeepInfra (deepinfra@) | | | NEBIUS_API_KEY | Nebius AI Studio (nebius@) | | | HYPERBOLIC_API_KEY | Hyperbolic (hyperbolic@) | | | SAMBANOVA_API_KEY | SambaNova Cloud (sambanova@) | | | NOVITA_API_KEY | Novita AI (novita@) | | | BASETEN_API_KEY | Baseten (baseten@) | | | PERPLEXITY_API_KEY | Perplexity Sonar (perplexity@) | | | VENICE_API_KEY | Venice AI (venice@) | | | CHUTES_API_KEY | Chutes (chutes@) | | | FEATHERLESS_API_KEY | Featherless AI (featherless@) | | | PARASAIL_API_KEY | Parasail (parasail@) | | | INFERENCE_NET_API_KEY | Inference.net (inference-net@) | | | AIMLAPI_API_KEY | AI/ML API (aimlapi@) | | | REQUESTY_API_KEY | Requesty (requesty@) | | | NANOGPT_API_KEY | NanoGPT (nanogpt@) | | | COHERE_API_KEY | Cohere (cohere@) | OpenAI-compatibility layer | | SCALEWAY_API_KEY | Scaleway Generative APIs (scaleway@) | | | UPSTAGE_API_KEY | Upstage Solar (upstage@) | | | WRITER_API_KEY | Writer Palmyra (writer@) | | | MOONSHOT_CN_API_KEY | Moonshot AI China region (moonshot-cn@) | Different service from MOONSHOT_API_KEY / moonshot@ above | | TUNING_ENGINES_API_KEY | Tuning Engines (tuningengines@) | Self-hosted: also set TUNING_ENGINES_BASE_URL |

Every one of these also accepts CUSTOM__KEY as an alias, and any of them can be replaced outright by a customEndpoints entry of the same name.

Claudish Settings

| Variable | Description | Default | |----------|-------------|---------| | CLAUDISH_MODEL | Default model (overrides ANTHROPIC_MODEL) | Interactive selector | | CLAUDISH_PORT | Default proxy port | Random (3000-9000) | | CLAUDISH_CONTEXT_WINDOW | Override context window size (local models) | Auto-detected | | CLAUDISH_MODEL_OPUS | Model for Opus role | | | CLAUDISH_MODEL_SONNET | Model for Sonnet role | | | CLAUDISH_MODEL_HAIKU | Model for Haiku role | | | CLAUDISH_MODEL_SUBAGENT | Model for sub-agents | | | CLAUDISH_SUMMARIZE_TOOLS | Summarize tool descriptions (true/1) | false | | CLAUDISH_TELEMETRY | Override telemetry (0/false/off to disable) | From config | | CLAUDISH_LOCAL_MAX_PARALLEL | Max concurrent local model requests (1-8) | 1 | | CLAUDISH_LOCAL_QUEUE_ENABLED | Enable/disable local model queue | true | | CLAUDISH_DEFAULT_PROVIDER | Default provider for bare model routing (v7.0.0+) | Auto-detected | | CLAUDISH_QWEN_NO_THINK | Disable thinking for Qwen models (1) | | | CLAUDISH_NO_PREDEFINED_ENDPOINTS | Turn the bundled endpoint catalog off entirely (1) | Catalog on | | CLAUDISH_CLASSIFIER_PROVIDER | Route auto-mode permission classifier to native Anthropic (anthropic) — see Classifier Passthrough | Off | | CLAUDISH_CLASSIFIER_MODEL | Native Claude model for the classifier passthrough (also enables it) | claude-sonnet-5 | | CLAUDISH_CLASSIFIER_DEBUG | Dump raw requests to logs/classifier-capture.jsonl for classifier-detection debugging (1) | Off |

Claude Code Compatibility

| Variable | Description | |----------|-------------| | ANTHROPIC_MODEL | Fallback for CLAUDISH_MODEL | | ANTHROPIC_DEFAULT_OPUS_MODEL | Fallback for CLAUDISH_MODEL_OPUS | | ANTHROPIC_DEFAULT_SONNET_MODEL | Fallback for CLAUDISH_MODEL_SONNET | | ANTHROPIC_DEFAULT_HAIKU_MODEL | Fallback for CLAUDISH_MODEL_HAIKU | | CLAUDE_CODE_SUBAGENT_MODEL | Fallback for CLAUDISH_MODEL_SUBAGENT | | CLAUDE_PATH | Custom path to Claude Code binary |

Custom Endpoints

| Variable | Provider | Default | |----------|----------|---------| | GEMINI_BASE_URL | Gemini API | https://generativelanguage.googleapis.com | | OPENAI_BASE_URL | OpenAI/Azure | https://api.openai.com | | MINIMAX_BASE_URL | MiniMax | https://api.minimax.io (China-platform keys: https://api.minimaxi.com) | | MOONSHOT_BASE_URL | Kimi/Moonshot | https://api.moonshot.ai | | ZHIPU_BASE_URL | GLM/Zhipu | https://open.bigmodel.cn | | ZAI_BASE_URL | Z.AI | https://api.z.ai | | QWEN_CODING_PLAN_BASE_URL | Alibaba Coding Plan | https://coding-intl.dashscope.aliyuncs.com | | QWEN_TOKEN_PLAN_BASE_URL | Alibaba Token Plan | https://token-plan.ap-southeast-1.maas.aliyuncs.com | | DASHSCOPE_BASE_URL | Alibaba PAYG | https://dashscope-intl.aliyuncs.com | | META_BASE_URL | Meta Model API (meta@) | https://api.meta.ai | | OLLAMACLOUD_BASE_URL | OllamaCloud | https://ollama.com | | OPENCODE_BASE_URL | OpenCode Zen | https://opencode.ai/zen | | LITELLM_BASE_URL | LiteLLM proxy server | _(required with LITELLM_API_KEY)_ | | OLLAMA_BASE_URL | Ollama (local) | http://localhost:11434 | | OLLAMA_HOST | Alias for OLLAMA_BASE_URL | | | LMSTUDIO_BASE_URL | LM Studio (local) | http://localhost:1234 | | VLLM_BASE_URL | vLLM (local) | http://localhost:8000 | | MLX_BASE_URL | MLX (local) | http://127.0.0.1:8080 | | TUNING_ENGINES_BASE_URL | Tuning Engines (tuningengines@), self-hosted gateway | https://api.tuningengines.com |

A malformed base-URL override SKIPS the provider — it never falls back to the public host. You set the variable to keep traffic inside your own network; quietly redirecting a typo to a vendor's public endpoint would send exactly the data you were isolating to exactly the place you were isolating it from.

Priority order: CLI flags > CLAUDISH_ env vars > ANTHROPIC_ env vars > profile config > interactive selector.

Important Notes:

• Set ANTHROPIC_API_KEY=sk-ant-api03-placeholder (or any value) to suppress the Claude Code login dialog
• In interactive mode, if no API key is set, you'll be prompted to enter one

Configuration Files

Claudish uses a two-scope configuration system:

| File | Scope | Purpose | |------|-------|---------| | ~/.claudish/config.json | Global | Profiles, telemetry, routing rules (shared across projects) | | .claudish.json | Local | Project-specific profiles and routing rules (overrides global) | | .env | Local | Provider API keys and model settings (auto-loaded at startup) |

Profile configuration (~/.claudish/config.json):

{
  "version": "1.0.0",
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "name": "default",
      "models": {
        "opus": "[email protected]",
        "sonnet": "google@gemini-3-pro",
        "haiku": "[email protected]",
        "subagent": "[email protected]"
      }
    }
  },
  "routing": {
    "kimi-*": ["kc", "kimi", "openrouter"],
    "glm-*": ["gc", "glm"],
    "*": ["litellm", "openrouter"]
  }
}

Custom routing rules map model name patterns to ordered provider fallback chains. Patterns support exact names, globs (kimi-), and catch-all. Local .claudish.json routing rules replace global rules entirely.

Manage profiles with:

claudish init [--local|--global]            # Setup wizard
claudish profile list [--local|--global]    # List profiles
claudish profile add [--local|--global]     # Add profile
claudish profile use <name>                 # Set default
claudish profile edit <name>                # Edit profile

For the complete configuration reference, see Settings Reference.

1Password Integration

Resolve provider API keys from 1Password instead of storing them in plaintext. Claudish reads secret references (op://vault/item/field) and resolves them at startup — the secret never lives in your config or shell history.

Authentication is automatic, in this order:

1. OP_SERVICE_ACCOUNT_TOKEN — a service-account token for headless/CI use (resolved via the official 1Password SDK, in-process, no op CLI needed). Service accounts can only read shared vaults, not your Private vault.
2. op CLI session — if you're signed into the 1Password desktop app (op signin), claudish uses that session (interactive, Touch ID). This is the zero-setup path on a laptop.

About the authorization prompt: When claudish reads a secret via the op CLI session, the 1Password desktop app shows an authorization prompt. By design, 1Password labels that prompt with the requesting process — i.e. your terminal (tmux, iTerm, etc.) — not "claudish". This is a 1Password behavior that no app can override; the prompt always names the process, never the integration. claudish is identified as claudish in 1Password's activity/audit log, just not in the live prompt. To avoid the prompt entirely (e.g. CI, or if the terminal name bothers you), use a OP_SERVICE_ACCOUNT_TOKEN — the service-account path authenticates directly against the 1Password API with no desktop prompt at all.

Single references

Point any API key at a 1Password field:

{
  "apiKeys": {
    "OPENROUTER_API_KEY": "op://Shared/OpenRouter/credential",
    "OPENAI_API_KEY": "op://Shared/OpenAI/api-key"
  }
}

A ${VAR} in a custom-endpoint apiKey and an op://... value are both resolved the same way. Multiple references are resolved in a single batch (one auth prompt).

Glob import — many keys from one item

If you keep all your provider keys in one 1Password item (each field named after its env var, e.g. OPENROUTER_API_KEY, ANTHROPIC_API_KEY), import them all with one entry. Add a top-level onepassword array of glob paths:

{
  "onepassword": [
    "op://Jack/AI LLM keys//_API_KEY"
  ]
}

The glob position mirrors the op:// path structure:

| Pattern | Imports | |---------|---------| | op://Vault/Item/* | all top-level (sectionless) fields | | op://Vault/Item/*_API_KEY | top-level fields ending in _API_KEY | | op://Vault/Item/Section/* | all fields in Section | | op://Vault/Item//_API_KEY | *_API_KEY fields across all sections | | op://Vault/Item/M/ | all fields in sections starting with M |

Each matched field label becomes the env var name (trimmed of whitespace). Labels that aren't valid env var names (e.g. Customer Key) are skipped with a warning. Only matched fields are decrypted — claudish lists field names first, then fetches values only for the ones you import.

Preview what a glob would import without revealing any secret values:

claudish op --list "op://Jack/AI LLM keys//_API_KEY"
  OPENROUTER_API_KEY   ✓  (section: Open router)
  ANTHROPIC_API_KEY    ✓  (section: Claude)
  Customer Key         ✗  skipped (not a valid env var name)
  9 importable, 1 skipped

Or run a one-off session with keys loaded inline, no config needed:

claudish op "op://Jack/AI LLM keys//_API_KEY" --model openrouter@deepseek/deepseek-r1 "task"

Finding the path

In the 1Password app, hover a field → its menu → Copy Secret Reference gives op://Vault/Item/[Section/]Field. For a glob, you only need the vault and item names (visible in the sidebar and title) plus /* — claudish discovers the fields. The claudish op --list preview confirms a glob before you commit it to config.

1Password Environments

1Password Environments (named sets of env vars) load via --op-env , where is the Environment ID copied from the desktop app (Developer → View Environments → Manage environment → Copy environment ID):

claudish --op-env <environment-id> --model openrouter@... "task"

Environment values are the highest-priority source (they override config and shell env). Requires the op CLI ≥ 2.35 (beta) — the latest stable op (2.34.0) does not yet include the op environment command.

Zero-code alternative

You can also wrap claudish with op run (no config changes needed), using an env file of op:// references:

op run --env-file=.env -- claudish --model openrouter@... "task"

Model Routing (v4.0.0+)

Claudish uses provider@model[:concurrency] syntax for explicit routing, plus smart auto-detection for native providers:

New Syntax: provider@model[:concurrency]

# Explicit provider routing
claudish --model [email protected] "quick task"
claudish --model openrouter@deepseek/deepseek-r1 "analysis"
claudish --model oai@gpt-4o "implement feature"
claudish --model [email protected]:3 "code review"  # 3 concurrent requests

Provider Shortcuts

| Shortcut | Provider | API Key | Example | |----------|----------|---------|---------| | g@, google@ | Google Gemini | GEMINI_API_KEY | [email protected] | | oai@ | OpenAI Direct | OPENAI_API_KEY | oai@gpt-4o | | or@, openrouter@ | OpenRouter | OPENROUTER_API_KEY | or@deepseek/deepseek-r1 | | mm@, mmax@ | MiniMax Direct | MINIMAX_API_KEY | [email protected] | | kimi@, moon@ | Kimi Direct | MOONSHOT_API_KEY | kimi@kimi-k2 | | glm@, zhipu@ | GLM Direct | ZHIPU_API_KEY | glm@glm-4 | | zai@ | Z.AI Direct | ZAI_API_KEY | zai@glm-4 | | mistral@ | Mistral | MISTRAL_API_KEY | mistral@mistral-large-2512 | | sakana@, fugu@ | Sakana Fugu | SAKANA_API_KEY | fugu@fugu-ultra | | sc@ | Sakana Fugu Subscription | SAKANA_CODING_API_KEY | sc@fugu-ultra | | qcode@ | Alibaba Coding Plan | QWEN_CODING_PLAN_API_KEY | [email protected] | | qtoken@ | Alibaba Token Plan | QWEN_TOKEN_PLAN_API_KEY | [email protected] | | qpay@ | Alibaba PAYG | DASHSCOPE_API_KEY | [email protected] | | meta@ | Meta Model API (metered) | META_API_KEY | [email protected] | | muse@ | Muse Code subscription (Meta) | _(claudish login muse, or the Muse Code CLI's Keychain login)_ | [email protected] | | llama@, lc@ | OllamaCloud | OLLAMA_API_KEY | [email protected] | | oc@ | OllamaCloud | OLLAMA_API_KEY | [email protected] | | zen@ | OpenCode Zen | OPENCODE_API_KEY | zen@gpt-5-nano | | zgo@, zengo@ | OpenCode Zen Go plan | OPENCODE_GO_API_KEY | zgo@glm-5 | | v@, vertex@ | Vertex AI | _(Application Default Credentials; VERTEX_PROJECT optional)_ | [email protected] | | ag@, antigravity@ | Antigravity (Gemini subscription) | _(OAuth via claudish login antigravity)_ | [email protected] | | go@ | _deprecated alias → ag@_ | _(OAuth)_ | [email protected] | | poe@ | Poe | POE_API_KEY | poe@GPT-4o | | ollama@ | Ollama (local) | _(none)_ | [email protected] | | lms@, lmstudio@ | LM Studio (local) | _(none)_ | [email protected] | | vllm@ | vLLM (local) | _(none)_ | vllm@mistral-7b | | mlx@ | MLX (local) | _(none)_ | [email protected] |

Native Model Auto-Detection

When no provider is specified, Claudish auto-detects from model name:

| Model Pattern | Routes To | Example | |---------------|-----------|---------| | gemini-, google/ | Google Gemini | gemini-2.0-flash | | gpt-, o1-, o3-* | OpenAI Direct | gpt-4o | | llama-, meta-llama/ | OllamaCloud | llama-3.1-70b | | abab-, minimax/ | MiniMax Direct | abab-6.5 | | kimi-, moonshot- | Kimi Direct | kimi-k2 | | glm-, zhipu/ | GLM Direct | glm-4 | | fugu-, sakana/ | Sakana Fugu | fugu-ultra | | qwen3., qwen3- | Alibaba subscriptions, OpenCode Go, PAYG, then OpenRouter | qwen3.7-plus | | poe:* | Poe | poe:GPT-4o | | claude-, anthropic/ | Native Anthropic | claude-sonnet-4 | | Unknown vendor/model | Error | Use openrouter@vendor/model |

Alibaba product rosters: Coding Plan, Token Plan, and PAYG use separate credentials and endpoints. The catalog supplies each product's route and model wire ID; account discovery narrows the models actually available to your key. Cross-vendor models on an Alibaba plan can be selected explicitly, for example [email protected].

Examples

# Auto-detected native routing (no prefix needed!)
claudish --model gemini-2.0-flash "quick task"      # → Google API
claudish --model gpt-4o "implement feature"          # → OpenAI API
claudish --model llama-3.1-70b "code review"         # → OllamaCloud
Explicit provider routing
claudish --model [email protected] "complex analysis"
claudish --model oai@o1 "complex reasoning"
claudish --model openrouter@deepseek/deepseek-r1 "deep analysis"
OllamaCloud - cloud-hosted Llama models
claudish --model [email protected] "code review"
claudish --model [email protected] "analyze image"
Vertex AI - Google Cloud (Application Default Credentials)
gcloud auth application-default login                # once
claudish --model [email protected] "task"           # project from ADC / gcloud config
VERTEX_PROJECT=my-project claudish --model [email protected] "explicit project"
Alibaba Cloud Model Studio products
claudish --model [email protected] "implement feature"
claudish --model [email protected] "implement feature"
claudish --model [email protected] "implement feature"
claudish --model [email protected] "review"
Local models with concurrency control
claudish --model [email protected]:3 "review"     # 3 concurrent requests
claudish --model [email protected]:0 "fast"       # No limit (bypass queue)
Unknown vendors require explicit OpenRouter
claudish --model openrouter@qwen/qwen-2.5 "task"
claudish --model or@mistralai/mistral-large "analysis"

Default provider (v7.0.0+)

The routing priority for bare model names (no provider@ prefix) is configurable. By default, Claudish tries LiteLLM (if configured), then OpenRouter. Override this with defaultProvider:

# Set default provider globally
claudish config set defaultProvider openrouter
Or via env var
export CLAUDISH_DEFAULT_PROVIDER=openrouter
Or per-invocation
claudish --default-provider litellm --model minimax-m2.5 "task"

Precedence: --default-provider flag > CLAUDISH_DEFAULT_PROVIDER env var > config file defaultProvider > legacy LiteLLM auto-promotion > OPENROUTER_API_KEY detection > hardcoded "openrouter".

Explicit provider@model syntax always bypasses defaultProvider and routes directly.

Custom endpoints (v7.0.0+)

Register your own OpenAI-compatible endpoints in ~/.claudish/config.json. See Settings Reference for the full schema.

{
  "customEndpoints": {
    "my-vllm": {
      "kind": "simple",
      "url": "http://gpu-box:8000/v1",
      "format": "openai",
      "apiKey": "${VLLM_API_KEY}"
    }
  },
  "defaultProvider": "my-vllm"
}

Then route to it with: claudish --model my-vllm@llama3 "task"

If the endpoint needs no credential (a local router, an inference server on a trusted network), say so with authScheme: "none" and omit apiKey — claudish then sends no auth header at all:

{
  "customEndpoints": {
    "localrouter": {
      "kind": "simple",
      "url": "http://127.0.0.1:8402/v1",
      "format": "openai",
      "authScheme": "none"
    }
  }
}

Do not use a placeholder like "apiKey": "none" for this — that is a literal key, and it goes out as Authorization: Bearer none, which some gateways reject.

Legacy Syntax (Deprecated)

The old prefix/model syntax still works but shows deprecation warnings:

# Old (deprecated)          →  New (recommended)
claudish --model g/gemini-pro     →  claudish --model g@gemini-pro
claudish --model oai/gpt-4o       →  claudish --model oai@gpt-4o
claudish --model ollama/llama3.2  →  claudish --model [email protected]

Curated Models

Top recommended models for development (v3.1.1):

| Model | Provider | Best For | |-------|----------|----------| | openai/gpt-5.3 | OpenAI | Default - Most advanced reasoning | | minimax/minimax-m2.1 | MiniMax | Budget-friendly, fast | | z-ai/glm-4.7 | Z.AI | Balanced performance | | google/gemini-3-pro-preview | Google | 1M context window | | moonshotai/kimi-k2-thinking | MoonShot | Extended reasoning | | deepseek/deepseek-v3.2 | DeepSeek | Code specialist | | qwen/qwen3-vl-235b-a22b-thinking | Alibaba | Vision + reasoning |

Vertex AI Partner Models (MaaS - Google Cloud billing):

| Model | 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 |

List all models:

claudish --models              # List all OpenRouter models
claudish --models gemini       # Search for specific models
claudish --models-top          # Show curated recommendations

Claude Code Flag Passthrough (NEW in v5.3.0)

Claudish forwards all unrecognized flags directly to Claude Code. This means any Claude Code flag works with claudish — no wrapper needed:

# Use Claude Code agents
claudish --model grok --agent code-review "review auth system"
Control effort and permissions
claudish --model grok --effort high --permission-mode plan "design API"
Set budget caps
claudish --model grok --max-budget-usd 0.50 "quick fix"
Custom system prompts
claudish --model grok --append-system-prompt "Always respond in JSON" "list files"
Restrict available tools
claudish --model grok --allowedTools "Read,Grep" "search for auth bugs"

Claudish flags (--model, --stdin, --quiet, -y, etc.) can appear in any order — they are always recognized regardless of position.

Use -- when a Claude Code flag value starts with -:

claudish --model grok -- --system-prompt "-verbose logging" "task"

Vision Proxy (NEW in v5.1.0)

Every model can now "see" images — even models without native vision support.

When you send an image to a non-vision model (like local Ollama models), Claudish automatically:

1. Detects that the model cannot process images
2. Sends each image to the Anthropic API (Claude Sonnet) for a rich description
3. Replaces the image block with [Image Description: ...] text
4. Forwards the enriched message to the target model

Claude Code → image + "what's in this?" → Claudish
                                             ↓
                              ┌──────────────────────────────┐
                              │ Model supports vision?       │
                              │  YES → pass image through    │
                              │  NO  → describe via Claude → │
                              │        replace with text     │
                              └──────────────────────────────┘
                                             ↓
                                      Target Model

How it works:

• Uses your existing x-api-key from Claude Code (no extra configuration)
• Each image is described in parallel (fast even with multiple images)
• 30-second timeout per image with graceful fallback to stripping
• Descriptions include text content, layout, colors, code, diagrams, and UI elements

# Local Ollama model (no vision) — images are automatically described
claudish --model [email protected] "what's in this screenshot?"
Vision-capable model — images pass through unchanged
claudish --model [email protected] "what's in this screenshot?"

Fallback behavior: If the vision proxy fails (network error, timeout, API issue), Claudish falls back to stripping images — the request still goes through, just without image context.

Status Line Display

Claudish automatically shows critical information in the Claude Code status bar - no setup required!

Ultra-Compact Format: directory • model-id • $cost • ctx%

Visual Design:

• 🔵 Directory (bright cyan, bold) - Where you are
• 🟡 Model ID (bright yellow) - Actual OpenRouter model ID
• 🟢 Cost (bright green) - Real-time session cost from OpenRouter
• 🟣 Context (bright magenta) - % of context window remaining
• ⚪ Separators (dim) - Visual dividers

• claudish • x-ai/grok-code-fast-1 • $0.003 • 95% - Using Grok, $0.003 spent, 95% context left
• my-project • openai/gpt-5-codex • $0.12 • 67% - Using GPT-5, $0.12 spent, 67% context left
• backend • minimax/minimax-m2 • $0.05 • 82% - Using MiniMax M2, $0.05 spent, 82% left
• test • openrouter/auto • $0.01 • 90% - Using any custom model, $0.01 spent, 90% left

• 💰 Cost tracking - Real-time USD from Claude Code session data
• 📊 Context monitoring - Percentage of model's context window remaining
• ⚡ Performance optimized - Ultra-compact to fit with thinking mode UI

• ✅ Ultra-compact - Directory limited to 15 chars (leaves room for everything)
• ✅ Critical first - Most important info (directory, model) comes first
• ✅ Smart truncation - Long directories shortened with "..."
• ✅ Space reservation - Reserves ~40 chars for Claude's thinking mode UI
• ✅ Color-coded - Instant visual scanning
• ✅ No overflow - Fits perfectly even with thinking mode enabled

• ✅ ANY OpenRouter model - Not limited to shortlist (e.g., openrouter/auto, custom models)
• ✅ Actual model IDs - Shows exact OpenRouter model ID (no translation)
• ✅ Context fallback - Unknown models use 100k context window (safe default)
• ✅ Shortlist optimized - Our recommended models have accurate context sizes
• ✅ Future-proof - Works with new models added to OpenRouter

• Each Claudish instance creates a temporary settings file with custom status line
• Settings use --settings flag (doesn't modify global Claude Code config)
• Status line uses simple bash script with ANSI colors (no external dependencies!)
• Displays actual OpenRouter model ID from CLAUDISH_ACTIVE_MODEL_NAME env var
• Context tracking uses model-specific sizes for our shortlist, 100k fallback for others
• Temp files are automatically cleaned up when Claudish exits
• Each instance is completely isolated - run multiple in parallel!

• ✅ Doesn't modify ~/.claude/settings.json
• ✅ Each instance has its own config
• ✅ Safe to run multiple Claudish instances in parallel
• ✅ Standard Claude Code unaffected
• ✅ Temp files auto-cleanup on exit
• ✅ No external dependencies (bash only, no jq!)

Examples

Basic Usage

# Simple prompt
claudish "fix the bug in user.ts"
Multi-word prompt
claudish "implement user authentication with JWT tokens"

With Specific Model

# Auto-detected native routing (model name determines provider)
claudish --model gpt-4o "refactor entire API layer"           # → OpenAI
claudish --model gemini-2.0-flash "quick fix"                 # → Google
claudish --model llama-3.1-70b "code review"                  # → OllamaCloud
Explicit provider routing (new @ syntax)
claudish --model [email protected] "complex analysis"
claudish --model oai@o1 "deep reasoning task"
claudish --model openrouter@deepseek/deepseek-r1 "analysis"   # Unknown vendors need explicit OR
Local models with concurrency control
claudish --model [email protected] "code review"
claudish --model [email protected]:3 "parallel processing"      # 3 concurrent
claudish --model [email protected] "implement dashboard UI"

Autonomous Mode

Auto-approve is enabled by default. For fully autonomous mode, add --dangerous:

# Basic usage (auto-approve already enabled)
claudish "delete unused files"
Fully autonomous (auto-approve + dangerous sandbox disabled)
claudish --dangerous "install dependencies"
Disable auto-approve if you want prompts
claudish --no-auto-approve "make important changes"

Custom Port

# Use specific port
claudish --port 3000 "analyze codebase"
Or set default
export CLAUDISH_PORT=3000
claudish "your task"

Passing Claude Flags

# Verbose mode
claudish "debug issue" --verbose
Custom working directory
claudish "analyze code" --cwd /path/to/project
Multiple flags
claudish --model openai/gpt-5.3-codex "task" --verbose --debug-claudish

Monitor Mode

NEW! Claudish now includes a monitor mode to help you understand how Claude Code works internally.

# Enable monitor mode (requires real Anthropic API key)
claudish --monitor --debug-claudish "implement a feature"

What Monitor Mode Does:

• ✅ Proxies to REAL Anthropic API (not OpenRouter) - Uses your actual Anthropic API key
• ✅ Logs ALL traffic - Captures complete requests and responses
• ✅ Both streaming and JSON - Logs SSE streams and JSON responses
• ✅ Debug logs to file - Saves to logs/claudish_*.log when --debug-claudish is used
• ✅ Pass-through proxy - No translation, forwards as-is to Anthropic

• 🔍 Understanding Claude Code's API protocol
• 🐛 Debugging integration issues
• 📊 Analyzing Claude Code's behavior
• 🔬 Research and development

# Monitor mode requires a REAL Anthropic API key (not placeholder)
export ANTHROPIC_API_KEY='sk-ant-api03-...'

Use with --debug-claudish to save logs to file
claudish --monitor --debug-claudish "your task"
Logs are saved to: logs/claudish_TIMESTAMP.log

Example Output:

[Monitor] Server started on http://127.0.0.1:8765
[Monitor] Mode: Passthrough to real Anthropic API
[Monitor] All traffic will be logged for analysis

=== [MONITOR] Claude Code → Anthropic API Request ===
{
  "model": "claude-sonnet-4.5",
  "messages": [...],
  "max_tokens": 4096,
  ...
}
=== End Request ===
=== [MONITOR] Anthropic API → Claude Code Response (Streaming) ===
event: message_start
data: {"type":"message_start",...}
event: content_block_start
data: {"type":"content_block_start",...}
...
=== End Streaming Response ===

Note: Monitor mode charges your Anthropic account (not OpenRouter). Use --debug-claudish flag to save logs for analysis.

Output Modes

Claudish supports three output modes for different use cases:

1. Quiet Mode (Default in Single-Shot)

Clean output with no [claudish] logs - perfect for piping to other tools:

# Quiet by default in single-shot
claudish "what is 2+2?"
Output: 2 + 2 equals 4.
Use in pipelines
claudish "list 3 colors" | grep -i blue
Redirect to file
claudish "analyze code" > analysis.txt

2. Verbose Mode

Show all [claudish] log messages for debugging:

# Verbose mode
claudish --verbose "what is 2+2?"
Output:
[claudish] Starting Claude Code with openai/gpt-4o
[claudish] Proxy URL: http://127.0.0.1:8797
[claudish] Status line: dir • openai/gpt-4o • $cost • ctx%
...
2 + 2 equals 4.
[claudish] Shutting down proxy server...
[claudish] Done
Interactive mode is verbose by default
claudish --interactive

3. JSON Output Mode

Structured output perfect for automation and tool integration:

# JSON output (always quiet)
claudish --json "what is 2+2?"
Output: {"type":"result","result":"2 + 2 equals 4.","total_cost_usd":0.068,"usage":{...}}
Extract just the result with jq
claudish --json "list 3 colors" | jq -r '.result'
Get cost and token usage
claudish --json "analyze code" | jq '{result, cost: .total_cost_usd, tokens: .usage.input_tokens}'
Use in scripts
RESULT=$(claudish --json "check if tests pass" | jq -r '.result')
echo "AI says: $RESULT"
Track costs across multiple runs
for task in task1 task2 task3; do
  claudish --json "$task" | jq -r '"\(.total_cost_usd)"'
done | awk '{sum+=$1} END {print "Total: $"sum}'

JSON Output Fields:

• result - The AI's response text
• total_cost_usd - Total cost in USD
• usage.input_tokens - Input tokens used
• usage.output_tokens - Output tokens used
• `duration