{"id":34251826,"url":"https://github.com/madappgang/claudish","last_synced_at":"2026-06-28T03:01:17.002Z","repository":{"id":326863411,"uuid":"1105892274","full_name":"MadAppGang/claudish","owner":"MadAppGang","description":"Claude Code. Any Model. The most powerful AI coding agent now speaks every language.","archived":false,"fork":false,"pushed_at":"2026-06-22T02:10:50.000Z","size":3953,"stargazers_count":919,"open_issues_count":51,"forks_count":123,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-06-22T04:10:17.868Z","etag":null,"topics":["ai","claude","claudecode"],"latest_commit_sha":null,"homepage":"https://claudish.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MadAppGang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-28T10:04:27.000Z","updated_at":"2026-06-22T02:10:54.000Z","dependencies_parsed_at":"2026-03-06T08:04:04.761Z","dependency_job_id":null,"html_url":"https://github.com/MadAppGang/claudish","commit_stats":null,"previous_names":["madappgang/claudish"],"tags_count":191,"template":false,"template_full_name":null,"purl":"pkg:github/MadAppGang/claudish","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadAppGang%2Fclaudish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadAppGang%2Fclaudish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadAppGang%2Fclaudish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadAppGang%2Fclaudish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MadAppGang","download_url":"https://codeload.github.com/MadAppGang/claudish/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadAppGang%2Fclaudish/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34875362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claudecode"],"created_at":"2025-12-16T10:15:00.365Z","updated_at":"2026-06-28T03:01:16.978Z","avatar_url":"https://github.com/MadAppGang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔮 Claudish\n\n### Claude Code. Any Model.\n\n[![npm version](https://img.shields.io/npm/v/claudish.svg?style=flat-square\u0026color=00D4AA)](https://www.npmjs.com/package/claudish)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-d97757?style=flat-square)](https://claude.ai/claude-code)\n\n**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.\n\n[Website](https://claudish.com) · [Documentation](https://github.com/MadAppGang/claudish/blob/main/docs/index.md) · [Report Bug](https://github.com/MadAppGang/claudish/issues)\n\n\u003c/div\u003e\n\n---\n\n**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.\n\n**Supported Providers:**\n- **Cloud:** OpenRouter (580+ models), Google Gemini, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, OpenCode Zen\n- **Local:** Ollama, LM Studio, vLLM, MLX\n- **Enterprise:** Vertex AI (Google Cloud)\n\n## Use Your Existing AI Subscriptions\n\n**Stop paying for multiple AI subscriptions.** Claudish lets you use subscriptions you already have with Claude Code's powerful interface:\n\n| Your Subscription | Command |\n|-------------------|---------|\n| **Anthropic Max** | Native support (just use `claude`) |\n| **Gemini Advanced** | `claudish --model g@gemini-3-pro-preview` |\n| **ChatGPT Plus/Codex** | `claudish --model oai@gpt-5.3` or `oai@gpt-5.3-codex` |\n| **Kimi** | `claudish --model kimi@kimi-k2.5` |\n| **GLM** | `claudish --model glm@GLM-4.7` |\n| **MiniMax** | `claudish --model mm@minimax-m2.1` |\n| **OllamaCloud** | `claudish --model oc@qwen3-next` |\n| **OpenCode Zen Go** | `claudish --model zgo@glm-5` |\n\n**100% Offline Option — Your code never leaves your machine:**\n```bash\nclaudish --model ollama@qwen3-coder:latest \"your task\"\n```\n\n## Bring Your Own Key (BYOK)\n\nClaudish is a **BYOK AI coding assistant**:\n- ✅ Use API keys you already have\n- ✅ No additional subscription fees\n- ✅ Full cost control — pay only for what you use\n- ✅ Works with any provider\n- ✅ Switch models mid-session\n\n## Features\n\n- ✅ **Multi-provider support** - OpenRouter, Gemini, Vertex AI, OpenAI, OllamaCloud, and local models\n- ✅ **New routing syntax** - Use `provider@model[:concurrency]` for explicit routing (e.g., `google@gemini-2.0-flash`)\n- ✅ **Native auto-detection** - Models like `gpt-4o`, `gemini-2.0-flash`, `llama-3.1-70b` route to their native APIs automatically\n- ✅ **Direct API access** - Google, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, Poe with direct billing\n- ✅ **Vertex AI Model Garden** - Access Google + partner models (MiniMax, Mistral, DeepSeek, Qwen, OpenAI OSS)\n- ✅ **Local model support** - Ollama, LM Studio, vLLM, MLX with `ollama@`, `lmstudio@` syntax and concurrency control\n- ✅ **Cross-platform** - Works with both Node.js and Bun (v1.3.0+)\n- ✅ **Universal compatibility** - Use with `npx` or `bunx` - no installation required\n- ✅ **Interactive setup** - Prompts for API key and model if not provided (zero config!)\n- ✅ **Monitor mode** - Proxy to real Anthropic API and log all traffic (for debugging)\n- ✅ **Protocol compliance** - 1:1 compatibility with Claude Code communication protocol\n- ✅ **Headless mode** - Automatic print mode for non-interactive execution\n- ✅ **Quiet mode** - Clean output by default (no log pollution)\n- ✅ **JSON output** - Structured data for tool integration\n- ✅ **Real-time streaming** - See Claude Code output as it happens\n- ✅ **Parallel runs** - Each instance gets isolated proxy\n- ✅ **Autonomous mode** - Bypass all prompts with flags\n- ✅ **Context inheritance** - Runs in current directory with same `.claude` settings\n- ✅ **Claude Code flag passthrough** - Forward any Claude Code flag (`--agent`, `--effort`, `--permission-mode`, etc.) in any order\n- ✅ **Vision proxy** - Non-vision models automatically get image descriptions via Claude, so every model can \"see\"\n\n## Installation\n\n### Quick Install\n\n```bash\n# Shell script (Linux/macOS)\ncurl -fsSL https://raw.githubusercontent.com/MadAppGang/claudish/main/install.sh | bash\n\n# Homebrew (macOS)\nbrew tap MadAppGang/tap \u0026\u0026 brew install claudish\n\n# npm\nnpm install -g claudish\n\n# Bun\nbun install -g claudish\n```\n\n### Prerequisites\n\n- [Claude Code](https://claude.com/claude-code) - Claude CLI must be installed\n- At least one API key:\n  - [OpenRouter API Key](https://openrouter.ai/keys) - Access 100+ models (free tier available)\n  - [Google Gemini API Key](https://aistudio.google.com/apikey) - For direct Gemini access\n  - [OpenAI API Key](https://platform.openai.com/api-keys) - For direct OpenAI access\n  - [OllamaCloud API Key](https://ollama.com/account) - For cloud-hosted Ollama models (`oc/` prefix)\n  - Or local models (Ollama, LM Studio) - No API key needed\n\n### Other Install Options\n\n**Use without installing:**\n\n```bash\nnpx claudish@latest --model x-ai/grok-code-fast-1 \"your prompt\"\nbunx claudish@latest --model x-ai/grok-code-fast-1 \"your prompt\"\n```\n\n**Install from source:**\n\n```bash\ngit clone https://github.com/MadAppGang/claudish.git\ncd claudish\nbun install \u0026\u0026 bun run build \u0026\u0026 bun link\n```\n\n## Quick Start\n\n### Step 0: Initialize Claudish Skill (First Time Only)\n\n```bash\n# Navigate to your project directory\ncd /path/to/your/project\n\n# Install Claudish skill for automatic best practices\nclaudish --init\n\n# Reload Claude Code to discover the skill\n```\n\n**What this does:**\n- ✅ Installs Claudish usage skill in `.claude/skills/claudish-usage/`\n- ✅ Enables automatic sub-agent delegation\n- ✅ Enforces file-based instruction patterns\n- ✅ Prevents context window pollution\n\n**After running --init**, Claude will automatically:\n- Use sub-agents when you mention external models (Grok, GPT-5, etc.)\n- Follow best practices for Claudish usage\n- Suggest specialized agents for different tasks\n\n### Option 1: Interactive Mode (Easiest)\n\n```bash\n# Just run it - will prompt for API key and model\nclaudish\n\n# Enter your OpenRouter API key when prompted\n# Select a model from the list\n# Start coding!\n```\n\n### Option 2: With Environment Variables\n\n```bash\n# Set up environment\nexport OPENROUTER_API_KEY=sk-or-v1-...     # For OpenRouter models\nexport GEMINI_API_KEY=...                   # For direct Google API\nexport OPENAI_API_KEY=sk-...                # For direct OpenAI API\nexport ANTHROPIC_API_KEY=sk-ant-api03-placeholder  # Required placeholder\n\n# Run with auto-detected model\nclaudish --model gpt-4o \"implement user authentication\"     # → OpenAI\nclaudish --model gemini-2.0-flash \"add tests\"               # → Google\n\n# Or with explicit provider\nclaudish --model openrouter@anthropic/claude-3.5-sonnet \"review code\"\n```\n\n**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!\n\n## AI Agent Usage\n\n**For AI agents running within Claude Code:** Use the dedicated AI agent guide for comprehensive instructions on file-based patterns and sub-agent delegation.\n\n```bash\n# Print complete AI agent usage guide\nclaudish --help-ai\n\n# Save guide to file for reference\nclaudish --help-ai \u003e claudish-agent-guide.md\n```\n\n**Quick Reference for AI Agents:**\n\n### Main Workflow for AI Agents\n\n1. **Get available models:**\n   ```bash\n   # List all models or search\n   claudish --models\n   claudish --models gemini\n\n   # Get top recommended models (JSON)\n   claudish --models-top --json\n   ```\n\n2. **Run Claudish through sub-agent** (recommended pattern):\n   ```typescript\n   // Don't run Claudish directly in main conversation\n   // Use Task tool to delegate to sub-agent\n   const result = await Task({\n     subagent_type: \"general-purpose\",\n     description: \"Implement feature with Grok\",\n     prompt: `\n   Use Claudish to implement feature with Grok model.\n\n   STEPS:\n   1. Create instruction file: /tmp/claudish-task-${Date.now()}.md\n   2. Write feature requirements to file\n   3. Run: claudish --model x-ai/grok-code-fast-1 --stdin \u003c /tmp/claudish-task-*.md\n   4. Read result and return ONLY summary (2-3 sentences)\n\n   DO NOT return full implementation. Keep response under 300 tokens.\n     `\n   });\n   ```\n\n3. **File-based instruction pattern** (avoids context pollution):\n   ```typescript\n   // Write instructions to file\n   const instructionFile = `/tmp/claudish-task-${Date.now()}.md`;\n   const resultFile = `/tmp/claudish-result-${Date.now()}.md`;\n\n   await Write({ file_path: instructionFile, content: `\n   # Task\n   Your task description here\n\n   # Output\n   Write results to: ${resultFile}\n   ` });\n\n   // Run Claudish with stdin\n   await Bash(`claudish --model x-ai/grok-code-fast-1 --stdin \u003c ${instructionFile}`);\n\n   // Read result\n   const result = await Read({ file_path: resultFile });\n\n   // Return summary only\n   return extractSummary(result);\n   ```\n\n**Key Principles:**\n- ✅ Use file-based patterns to avoid context window pollution\n- ✅ Delegate to sub-agents instead of running directly\n- ✅ Return summaries only (not full conversation transcripts)\n- ✅ Choose appropriate model for task (see `--models` or `--models-top`)\n\n**Resources:**\n- Full AI agent guide: `claudish --help-ai`\n- Skill document: `skills/claudish-usage/SKILL.md` (in repository root)\n- Model integration: `skills/claudish-integration/SKILL.md` (in repository root)\n\n## Usage\n\n### Basic Syntax\n\n```bash\nclaudish [OPTIONS] \u003cclaude-args...\u003e\n```\n\n### Options\n\n\u003e For the exhaustive reference with all details, see [Settings Reference](docs/settings-reference.md).\n\n| Flag | Short | Description | Default |\n|------|-------|-------------|---------|\n| `--model \u003cmodel\u003e` | `-m` | Model to use (`provider@model` syntax) | Interactive selector |\n| `--default-provider \u003cname\u003e` | | Default provider for bare model routing (v7.0.0+) | Auto-detected |\n| `--model-opus \u003cmodel\u003e` | | Model for Opus role (planning, complex tasks) | |\n| `--model-sonnet \u003cmodel\u003e` | | Model for Sonnet role (default coding) | |\n| `--model-haiku \u003cmodel\u003e` | | Model for Haiku role (fast tasks) | |\n| `--model-subagent \u003cmodel\u003e` | | Model for sub-agents (Task tool) | |\n| `--profile \u003cname\u003e` | `-p` | Named profile for model mapping | Default profile |\n| `--op-env \u003cid\u003e` | | Load env vars from a 1Password Environment (highest priority) | |\n| `--interactive` | `-i` | Interactive mode (persistent session) | Auto when no prompt |\n| `--auto-approve` | `-y` | Skip permission prompts | `false` |\n| `--no-auto-approve` | | Explicitly enable permission prompts | |\n| `--dangerous` | | Pass `--dangerouslyDisableSandbox` | `false` |\n| `--port \u003cport\u003e` | | Proxy server port | Random (3000-9000) |\n| `--log-debug` | `-d` | Enable debug logging to `logs/` | `false` |\n| `--log-level \u003clevel\u003e` | | Log verbosity: `debug`, `info`, `minimal` | `info` |\n| `--quiet` | `-q` | Suppress `[claudish]` messages | Default in single-shot |\n| `--verbose` | `-v` | Show `[claudish]` messages | Default in interactive |\n| `--json` | | JSON output for tool integration (implies `--quiet`) | `false` |\n| `--stdin` | | Read prompt from stdin | `false` |\n| `--free` | | Show only free models in selector | `false` |\n| `--monitor` | | Proxy to real Anthropic API and log traffic | `false` |\n| `--summarize-tools` | | Summarize tool descriptions (for local models) | `false` |\n| `--cost-track` | | Enable cost tracking (enables monitor mode) | `false` |\n| `--cost-audit` | | Show cost analysis report | |\n| `--cost-reset` | | Reset accumulated cost statistics | |\n| `--models [query]` | `-s` (`--models-search`) | List all models or fuzzy search | |\n| `--models-top` | | Show curated recommended models | |\n| `--models-refresh` | | Force refresh model cache | |\n| `--init` | | Install Claudish skill in current project | |\n| `--mcp` | | Run as MCP server | |\n| `--gemini-login` | | Login to Gemini Code Assist via OAuth | |\n| `--gemini-logout` | | Clear Gemini OAuth credentials | |\n| `--kimi-login` | | Login to Kimi via OAuth | |\n| `--kimi-logout` | | Clear Kimi OAuth credentials | |\n| `--help-ai` | | Show AI agent usage guide | |\n| `--version` | | Show version | |\n| `--help` | `-h` | Show help message | |\n| `--` | | Everything after passes to Claude Code | |\n\n**Flag passthrough**: Any unrecognized flag is automatically forwarded to Claude Code (e.g., `--agent`, `--effort`, `--permission-mode`).\n\n### Environment Variables\n\nClaudish automatically loads `.env` from the current directory at startup. For the full list, see [Settings Reference](docs/settings-reference.md).\n\n#### API Keys (at least one required for cloud models)\n\n| Variable | Provider | Aliases |\n|----------|----------|---------|\n| `OPENROUTER_API_KEY` | OpenRouter (default backend, 580+ models) | |\n| `GEMINI_API_KEY` | Google Gemini (`g@`, `google@`) | |\n| `OPENAI_API_KEY` | OpenAI (`oai@`) | |\n| `MINIMAX_API_KEY` | MiniMax (`mm@`, `mmax@`) | |\n| `MINIMAX_CODING_API_KEY` | MiniMax Coding Plan (`mmc@`) | |\n| `MOONSHOT_API_KEY` | Kimi/Moonshot (`kimi@`) | `KIMI_API_KEY` |\n| `KIMI_CODING_API_KEY` | Kimi Coding Plan (`kc@`) | Or OAuth via `--kimi-login` |\n| `ZHIPU_API_KEY` | GLM/Zhipu (`glm@`) | `GLM_API_KEY` |\n| `GLM_CODING_API_KEY` | GLM Coding Plan (`gc@`) | `ZAI_CODING_API_KEY` |\n| `ZAI_API_KEY` | Z.AI (`zai@`) | |\n| `OLLAMA_API_KEY` | OllamaCloud (`oc@`) | |\n| `OPENCODE_API_KEY` | OpenCode Zen (`zen@`) — optional for free models | |\n| `LITELLM_API_KEY` | LiteLLM (`ll@`) — requires `LITELLM_BASE_URL` | |\n| `POE_API_KEY` | Poe (`poe@`) | |\n| `VERTEX_API_KEY` | Vertex AI Express (`v@`) | |\n| `VERTEX_PROJECT` | Vertex AI OAuth mode (`v@`) | `GOOGLE_CLOUD_PROJECT` |\n| `ANTHROPIC_API_KEY` | Placeholder (suppresses Claude Code dialog) | |\n\n#### Claudish Settings\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CLAUDISH_MODEL` | Default model (overrides `ANTHROPIC_MODEL`) | Interactive selector |\n| `CLAUDISH_PORT` | Default proxy port | Random (3000-9000) |\n| `CLAUDISH_CONTEXT_WINDOW` | Override context window size (local models) | Auto-detected |\n| `CLAUDISH_MODEL_OPUS` | Model for Opus role | |\n| `CLAUDISH_MODEL_SONNET` | Model for Sonnet role | |\n| `CLAUDISH_MODEL_HAIKU` | Model for Haiku role | |\n| `CLAUDISH_MODEL_SUBAGENT` | Model for sub-agents | |\n| `CLAUDISH_SUMMARIZE_TOOLS` | Summarize tool descriptions (`true`/`1`) | `false` |\n| `CLAUDISH_TELEMETRY` | Override telemetry (`0`/`false`/`off` to disable) | From config |\n| `CLAUDISH_LOCAL_MAX_PARALLEL` | Max concurrent local model requests (1-8) | `1` |\n| `CLAUDISH_LOCAL_QUEUE_ENABLED` | Enable/disable local model queue | `true` |\n| `CLAUDISH_DEFAULT_PROVIDER` | Default provider for bare model routing (v7.0.0+) | Auto-detected |\n| `CLAUDISH_QWEN_NO_THINK` | Disable thinking for Qwen models (`1`) | |\n\n#### Claude Code Compatibility\n\n| Variable | Description |\n|----------|-------------|\n| `ANTHROPIC_MODEL` | Fallback for `CLAUDISH_MODEL` |\n| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Fallback for `CLAUDISH_MODEL_OPUS` |\n| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Fallback for `CLAUDISH_MODEL_SONNET` |\n| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Fallback for `CLAUDISH_MODEL_HAIKU` |\n| `CLAUDE_CODE_SUBAGENT_MODEL` | Fallback for `CLAUDISH_MODEL_SUBAGENT` |\n| `CLAUDE_PATH` | Custom path to Claude Code binary |\n\n#### Custom Endpoints\n\n| Variable | Provider | Default |\n|----------|----------|---------|\n| `GEMINI_BASE_URL` | Gemini API | `https://generativelanguage.googleapis.com` |\n| `OPENAI_BASE_URL` | OpenAI/Azure | `https://api.openai.com` |\n| `MINIMAX_BASE_URL` | MiniMax | `https://api.minimax.io` |\n| `MOONSHOT_BASE_URL` | Kimi/Moonshot | `https://api.moonshot.ai` |\n| `ZHIPU_BASE_URL` | GLM/Zhipu | `https://open.bigmodel.cn` |\n| `ZAI_BASE_URL` | Z.AI | `https://api.z.ai` |\n| `OLLAMACLOUD_BASE_URL` | OllamaCloud | `https://ollama.com` |\n| `OPENCODE_BASE_URL` | OpenCode Zen | `https://opencode.ai/zen` |\n| `LITELLM_BASE_URL` | LiteLLM proxy server | _(required with LITELLM_API_KEY)_ |\n| `OLLAMA_BASE_URL` | Ollama (local) | `http://localhost:11434` |\n| `OLLAMA_HOST` | Alias for `OLLAMA_BASE_URL` | |\n| `LMSTUDIO_BASE_URL` | LM Studio (local) | `http://localhost:1234` |\n| `VLLM_BASE_URL` | vLLM (local) | `http://localhost:8000` |\n| `MLX_BASE_URL` | MLX (local) | `http://127.0.0.1:8080` |\n\n**Priority order**: CLI flags \u003e `CLAUDISH_*` env vars \u003e `ANTHROPIC_*` env vars \u003e profile config \u003e interactive selector.\n\n**Important Notes:**\n- Set `ANTHROPIC_API_KEY=sk-ant-api03-placeholder` (or any value) to suppress the Claude Code login dialog\n- In interactive mode, if no API key is set, you'll be prompted to enter one\n\n### Configuration Files\n\nClaudish uses a two-scope configuration system:\n\n| File | Scope | Purpose |\n|------|-------|---------|\n| `~/.claudish/config.json` | Global | Profiles, telemetry, routing rules (shared across projects) |\n| `.claudish.json` | Local | Project-specific profiles and routing rules (overrides global) |\n| `.env` | Local | Environment variables (auto-loaded at startup) |\n\n**Profile configuration** (`~/.claudish/config.json`):\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"defaultProfile\": \"default\",\n  \"profiles\": {\n    \"default\": {\n      \"name\": \"default\",\n      \"models\": {\n        \"opus\": \"oai@gpt-5.3\",\n        \"sonnet\": \"google@gemini-3-pro\",\n        \"haiku\": \"mm@MiniMax-M2.1\",\n        \"subagent\": \"google@gemini-2.0-flash\"\n      }\n    }\n  },\n  \"routing\": {\n    \"kimi-*\": [\"kc\", \"kimi\", \"openrouter\"],\n    \"glm-*\": [\"gc\", \"glm\"],\n    \"*\": [\"litellm\", \"openrouter\"]\n  }\n}\n```\n\n**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.\n\nManage profiles with:\n\n```bash\nclaudish init [--local|--global]            # Setup wizard\nclaudish profile list [--local|--global]    # List profiles\nclaudish profile add [--local|--global]     # Add profile\nclaudish profile use \u003cname\u003e                 # Set default\nclaudish profile edit \u003cname\u003e                # Edit profile\n```\n\nFor the complete configuration reference, see [Settings Reference](docs/settings-reference.md).\n\n## 1Password Integration\n\nResolve provider API keys from 1Password instead of storing them in plaintext. Claudish reads [secret references](https://developer.1password.com/docs/cli/secret-references/) (`op://vault/item/field`) and resolves them at startup — the secret never lives in your config or shell history.\n\n**Authentication** is automatic, in this order:\n\n1. **`OP_SERVICE_ACCOUNT_TOKEN`** — a [service-account token](https://developer.1password.com/docs/service-accounts/) 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.\n2. **`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.\n\nIf a config value or env var starts with `op://` and neither auth method works, claudish **fails with a clear message** rather than running with a missing key. If no `op://` reference is present, claudish never touches 1Password (zero overhead for non-users).\n\n\u003e **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**.\n\n### Single references\n\nPoint any API key at a 1Password field:\n\n```json\n{\n  \"apiKeys\": {\n    \"OPENROUTER_API_KEY\": \"op://Shared/OpenRouter/credential\",\n    \"OPENAI_API_KEY\": \"op://Shared/OpenAI/api-key\"\n  }\n}\n```\n\nA `${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).\n\n### Glob import — many keys from one item\n\nIf 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:\n\n```json\n{\n  \"onepassword\": [\n    \"op://Jack/AI LLM keys/*/*_API_KEY\"\n  ]\n}\n```\n\nThe glob position mirrors the `op://` path structure:\n\n| Pattern | Imports |\n|---------|---------|\n| `op://Vault/Item/*` | all **top-level** (sectionless) fields |\n| `op://Vault/Item/*_API_KEY` | top-level fields ending in `_API_KEY` |\n| `op://Vault/Item/Section/*` | all fields in `Section` |\n| `op://Vault/Item/*/*_API_KEY` | `*_API_KEY` fields across **all** sections |\n| `op://Vault/Item/M*/*` | all fields in sections starting with `M` |\n\nEach 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.\n\nPreview what a glob would import **without revealing any secret values**:\n\n```bash\nclaudish op --list \"op://Jack/AI LLM keys/*/*_API_KEY\"\n#   OPENROUTER_API_KEY   ✓  (section: Open router)\n#   ANTHROPIC_API_KEY    ✓  (section: Claude)\n#   Customer Key         ✗  skipped (not a valid env var name)\n#   9 importable, 1 skipped\n```\n\nOr run a one-off session with keys loaded inline, no config needed:\n\n```bash\nclaudish op \"op://Jack/AI LLM keys/*/*_API_KEY\" --model openrouter@deepseek/deepseek-r1 \"task\"\n```\n\n### Finding the path\n\nIn 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.\n\n### 1Password Environments\n\n[1Password Environments](https://www.1password.dev/environments) (named sets of env vars) load via `--op-env \u003cid\u003e`, where `\u003cid\u003e` is the Environment ID copied from the desktop app (Developer → View Environments → Manage environment → Copy environment ID):\n\n```bash\nclaudish --op-env \u003cenvironment-id\u003e --model openrouter@... \"task\"\n```\n\nEnvironment 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.\n\n### Zero-code alternative\n\nYou can also wrap claudish with `op run` (no config changes needed), using an env file of `op://` references:\n\n```bash\nop run --env-file=.env -- claudish --model openrouter@... \"task\"\n```\n\n## Model Routing (v4.0.0+)\n\nClaudish uses **`provider@model[:concurrency]`** syntax for explicit routing, plus **smart auto-detection** for native providers:\n\n### New Syntax: `provider@model[:concurrency]`\n\n```bash\n# Explicit provider routing\nclaudish --model google@gemini-2.0-flash \"quick task\"\nclaudish --model openrouter@deepseek/deepseek-r1 \"analysis\"\nclaudish --model oai@gpt-4o \"implement feature\"\nclaudish --model ollama@llama3.2:3 \"code review\"  # 3 concurrent requests\n```\n\n### Provider Shortcuts\n\n| Shortcut | Provider | API Key | Example |\n|----------|----------|---------|---------|\n| `g@`, `google@` | Google Gemini | `GEMINI_API_KEY` | `g@gemini-2.0-flash` |\n| `oai@` | OpenAI Direct | `OPENAI_API_KEY` | `oai@gpt-4o` |\n| `or@`, `openrouter@` | OpenRouter | `OPENROUTER_API_KEY` | `or@deepseek/deepseek-r1` |\n| `mm@`, `mmax@` | MiniMax Direct | `MINIMAX_API_KEY` | `mm@MiniMax-M2.1` |\n| `kimi@`, `moon@` | Kimi Direct | `MOONSHOT_API_KEY` | `kimi@kimi-k2` |\n| `glm@`, `zhipu@` | GLM Direct | `ZHIPU_API_KEY` | `glm@glm-4` |\n| `zai@` | Z.AI Direct | `ZAI_API_KEY` | `zai@glm-4` |\n| `llama@`, `lc@`, `meta@` | OllamaCloud | `OLLAMA_API_KEY` | `llama@llama-3.1-70b` |\n| `oc@` | OllamaCloud | `OLLAMA_API_KEY` | `oc@llama-3.1-70b` |\n| `zen@` | OpenCode Zen (free/paid) | `OPENCODE_API_KEY` _(optional)_ | `zen@gpt-5-nano` |\n| `zgo@`, `zengo@` | OpenCode Zen Go plan | `OPENCODE_API_KEY` | `zgo@glm-5` |\n| `v@`, `vertex@` | Vertex AI | `VERTEX_API_KEY` | `v@gemini-2.5-flash` |\n| `go@` | Gemini CodeAssist | _(OAuth)_ | `go@gemini-2.5-flash` |\n| `poe@` | Poe | `POE_API_KEY` | `poe@GPT-4o` |\n| `ollama@` | Ollama (local) | _(none)_ | `ollama@llama3.2` |\n| `lms@`, `lmstudio@` | LM Studio (local) | _(none)_ | `lms@qwen2.5-coder` |\n| `vllm@` | vLLM (local) | _(none)_ | `vllm@mistral-7b` |\n| `mlx@` | MLX (local) | _(none)_ | `mlx@llama-3.2-3b` |\n\n### Native Model Auto-Detection\n\nWhen no provider is specified, Claudish auto-detects from model name:\n\n| Model Pattern | Routes To | Example |\n|---------------|-----------|---------|\n| `gemini-*`, `google/*` | Google Gemini | `gemini-2.0-flash` |\n| `gpt-*`, `o1-*`, `o3-*` | OpenAI Direct | `gpt-4o` |\n| `llama-*`, `meta-llama/*` | OllamaCloud | `llama-3.1-70b` |\n| `abab-*`, `minimax/*` | MiniMax Direct | `abab-6.5` |\n| `kimi-*`, `moonshot-*` | Kimi Direct | `kimi-k2` |\n| `glm-*`, `zhipu/*` | GLM Direct | `glm-4` |\n| `poe:*` | Poe | `poe:GPT-4o` |\n| `claude-*`, `anthropic/*` | Native Anthropic | `claude-sonnet-4` |\n| **Unknown `vendor/model`** | **Error** | Use `openrouter@vendor/model` |\n\n### Examples\n\n```bash\n# Auto-detected native routing (no prefix needed!)\nclaudish --model gemini-2.0-flash \"quick task\"      # → Google API\nclaudish --model gpt-4o \"implement feature\"          # → OpenAI API\nclaudish --model llama-3.1-70b \"code review\"         # → OllamaCloud\n\n# Explicit provider routing\nclaudish --model google@gemini-2.5-pro \"complex analysis\"\nclaudish --model oai@o1 \"complex reasoning\"\nclaudish --model openrouter@deepseek/deepseek-r1 \"deep analysis\"\n\n# OllamaCloud - cloud-hosted Llama models\nclaudish --model llama@llama-3.1-70b \"code review\"\nclaudish --model oc@llama-3.2-vision \"analyze image\"\n\n# Vertex AI - Google Cloud\nVERTEX_API_KEY=... claudish --model v@gemini-2.5-flash \"task\"\nVERTEX_PROJECT=my-project claudish --model vertex@gemini-2.5-flash \"OAuth mode\"\n\n# Local models with concurrency control\nclaudish --model ollama@llama3.2:3 \"review\"     # 3 concurrent requests\nclaudish --model ollama@llama3.2:0 \"fast\"       # No limit (bypass queue)\n\n# Unknown vendors require explicit OpenRouter\nclaudish --model openrouter@qwen/qwen-2.5 \"task\"\nclaudish --model or@mistralai/mistral-large \"analysis\"\n```\n\n### Default provider (v7.0.0+)\n\nThe routing priority for bare model names (no `provider@` prefix) is configurable. By default, Claudish tries LiteLLM (if configured), then OpenRouter. Override this with `defaultProvider`:\n\n```bash\n# Set default provider globally\nclaudish config set defaultProvider openrouter\n\n# Or via env var\nexport CLAUDISH_DEFAULT_PROVIDER=openrouter\n\n# Or per-invocation\nclaudish --default-provider litellm --model minimax-m2.5 \"task\"\n```\n\nPrecedence: `--default-provider` flag \u003e `CLAUDISH_DEFAULT_PROVIDER` env var \u003e config file `defaultProvider` \u003e legacy LiteLLM auto-promotion \u003e `OPENROUTER_API_KEY` detection \u003e hardcoded `\"openrouter\"`.\n\nExplicit `provider@model` syntax always bypasses `defaultProvider` and routes directly.\n\n### Custom endpoints (v7.0.0+)\n\nRegister your own OpenAI-compatible endpoints in `~/.claudish/config.json`. See [Settings Reference](docs/settings-reference.md) for the full schema.\n\n```json\n{\n  \"customEndpoints\": {\n    \"my-vllm\": {\n      \"kind\": \"simple\",\n      \"url\": \"http://gpu-box:8000/v1\",\n      \"format\": \"openai\",\n      \"apiKey\": \"none\"\n    }\n  },\n  \"defaultProvider\": \"my-vllm\"\n}\n```\n\nThen route to it with: `claudish --model my-vllm@llama3 \"task\"`\n\n### Legacy Syntax (Deprecated)\n\nThe old `prefix/model` syntax still works but shows deprecation warnings:\n\n```bash\n# Old (deprecated)          →  New (recommended)\nclaudish --model g/gemini-pro     →  claudish --model g@gemini-pro\nclaudish --model oai/gpt-4o       →  claudish --model oai@gpt-4o\nclaudish --model ollama/llama3.2  →  claudish --model ollama@llama3.2\n```\n\n## Curated Models\n\nTop recommended models for development (v3.1.1):\n\n| Model | Provider | Best For |\n|-------|----------|----------|\n| `openai/gpt-5.3` | OpenAI | **Default** - Most advanced reasoning |\n| `minimax/minimax-m2.1` | MiniMax | Budget-friendly, fast |\n| `z-ai/glm-4.7` | Z.AI | Balanced performance |\n| `google/gemini-3-pro-preview` | Google | 1M context window |\n| `moonshotai/kimi-k2-thinking` | MoonShot | Extended reasoning |\n| `deepseek/deepseek-v3.2` | DeepSeek | Code specialist |\n| `qwen/qwen3-vl-235b-a22b-thinking` | Alibaba | Vision + reasoning |\n\n**Vertex AI Partner Models (MaaS - Google Cloud billing):**\n\n| Model | Provider | Best For |\n|-------|----------|----------|\n| `vertex/minimax/minimax-m2-maas` | MiniMax | Fast, budget-friendly |\n| `vertex/mistralai/codestral-2` | Mistral | Code specialist |\n| `vertex/deepseek/deepseek-v3-2-maas` | DeepSeek | Deep reasoning |\n| `vertex/qwen/qwen3-coder-480b-a35b-instruct-maas` | Qwen | Agentic coding |\n| `vertex/openai/gpt-oss-120b-maas` | OpenAI | Open-weight reasoning |\n\nList all models:\n\n```bash\nclaudish --models              # List all OpenRouter models\nclaudish --models gemini       # Search for specific models\nclaudish --models-top          # Show curated recommendations\n```\n\n## Claude Code Flag Passthrough (NEW in v5.3.0)\n\nClaudish forwards all unrecognized flags directly to Claude Code. This means any Claude Code flag works with claudish — no wrapper needed:\n\n```bash\n# Use Claude Code agents\nclaudish --model grok --agent code-review \"review auth system\"\n\n# Control effort and permissions\nclaudish --model grok --effort high --permission-mode plan \"design API\"\n\n# Set budget caps\nclaudish --model grok --max-budget-usd 0.50 \"quick fix\"\n\n# Custom system prompts\nclaudish --model grok --append-system-prompt \"Always respond in JSON\" \"list files\"\n\n# Restrict available tools\nclaudish --model grok --allowedTools \"Read,Grep\" \"search for auth bugs\"\n```\n\nClaudish flags (`--model`, `--stdin`, `--quiet`, `-y`, etc.) can appear in **any order** — they are always recognized regardless of position.\n\nUse `--` when a Claude Code flag value starts with `-`:\n```bash\nclaudish --model grok -- --system-prompt \"-verbose logging\" \"task\"\n```\n\n## Vision Proxy (NEW in v5.1.0)\n\n**Every model can now \"see\" images** — even models without native vision support.\n\nWhen you send an image to a non-vision model (like local Ollama models), Claudish automatically:\n\n1. Detects that the model cannot process images\n2. Sends each image to the Anthropic API (Claude Sonnet) for a rich description\n3. Replaces the image block with `[Image Description: ...]` text\n4. Forwards the enriched message to the target model\n\n```\nClaude Code → image + \"what's in this?\" → Claudish\n                                             ↓\n                              ┌──────────────────────────────┐\n                              │ Model supports vision?       │\n                              │  YES → pass image through    │\n                              │  NO  → describe via Claude → │\n                              │        replace with text     │\n                              └──────────────────────────────┘\n                                             ↓\n                                      Target Model\n```\n\n**How it works:**\n- Uses your existing `x-api-key` from Claude Code (no extra configuration)\n- Each image is described in parallel (fast even with multiple images)\n- 30-second timeout per image with graceful fallback to stripping\n- Descriptions include text content, layout, colors, code, diagrams, and UI elements\n\n**Example:**\n\n```bash\n# Local Ollama model (no vision) — images are automatically described\nclaudish --model ollama@llama3.2 \"what's in this screenshot?\"\n\n# Vision-capable model — images pass through unchanged\nclaudish --model g@gemini-2.5-flash \"what's in this screenshot?\"\n```\n\n**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.\n\n## Status Line Display\n\nClaudish automatically shows critical information in the Claude Code status bar - **no setup required!**\n\n**Ultra-Compact Format:** `directory • model-id • $cost • ctx%`\n\n**Visual Design:**\n- 🔵 **Directory** (bright cyan, bold) - Where you are\n- 🟡 **Model ID** (bright yellow) - Actual OpenRouter model ID\n- 🟢 **Cost** (bright green) - Real-time session cost from OpenRouter\n- 🟣 **Context** (bright magenta) - % of context window remaining\n- ⚪ **Separators** (dim) - Visual dividers\n\n**Examples:**\n- `claudish • x-ai/grok-code-fast-1 • $0.003 • 95%` - Using Grok, $0.003 spent, 95% context left\n- `my-project • openai/gpt-5-codex • $0.12 • 67%` - Using GPT-5, $0.12 spent, 67% context left\n- `backend • minimax/minimax-m2 • $0.05 • 82%` - Using MiniMax M2, $0.05 spent, 82% left\n- `test • openrouter/auto • $0.01 • 90%` - Using any custom model, $0.01 spent, 90% left\n\n**Critical Tracking (Live Updates):**\n- 💰 **Cost tracking** - Real-time USD from Claude Code session data\n- 📊 **Context monitoring** - Percentage of model's context window remaining\n- ⚡ **Performance optimized** - Ultra-compact to fit with thinking mode UI\n\n**Thinking Mode Optimized:**\n- ✅ **Ultra-compact** - Directory limited to 15 chars (leaves room for everything)\n- ✅ **Critical first** - Most important info (directory, model) comes first\n- ✅ **Smart truncation** - Long directories shortened with \"...\"\n- ✅ **Space reservation** - Reserves ~40 chars for Claude's thinking mode UI\n- ✅ **Color-coded** - Instant visual scanning\n- ✅ **No overflow** - Fits perfectly even with thinking mode enabled\n\n**Custom Model Support:**\n- ✅ **ANY OpenRouter model** - Not limited to shortlist (e.g., `openrouter/auto`, custom models)\n- ✅ **Actual model IDs** - Shows exact OpenRouter model ID (no translation)\n- ✅ **Context fallback** - Unknown models use 100k context window (safe default)\n- ✅ **Shortlist optimized** - Our recommended models have accurate context sizes\n- ✅ **Future-proof** - Works with new models added to OpenRouter\n\n**How it works:**\n- Each Claudish instance creates a temporary settings file with custom status line\n- Settings use `--settings` flag (doesn't modify global Claude Code config)\n- Status line uses simple bash script with ANSI colors (no external dependencies!)\n- Displays actual OpenRouter model ID from `CLAUDISH_ACTIVE_MODEL_NAME` env var\n- Context tracking uses model-specific sizes for our shortlist, 100k fallback for others\n- Temp files are automatically cleaned up when Claudish exits\n- Each instance is completely isolated - run multiple in parallel!\n\n**Per-instance isolation:**\n- ✅ Doesn't modify `~/.claude/settings.json`\n- ✅ Each instance has its own config\n- ✅ Safe to run multiple Claudish instances in parallel\n- ✅ Standard Claude Code unaffected\n- ✅ Temp files auto-cleanup on exit\n- ✅ No external dependencies (bash only, no jq!)\n\n## Examples\n\n### Basic Usage\n\n```bash\n# Simple prompt\nclaudish \"fix the bug in user.ts\"\n\n# Multi-word prompt\nclaudish \"implement user authentication with JWT tokens\"\n```\n\n### With Specific Model\n\n```bash\n# Auto-detected native routing (model name determines provider)\nclaudish --model gpt-4o \"refactor entire API layer\"           # → OpenAI\nclaudish --model gemini-2.0-flash \"quick fix\"                 # → Google\nclaudish --model llama-3.1-70b \"code review\"                  # → OllamaCloud\n\n# Explicit provider routing (new @ syntax)\nclaudish --model google@gemini-2.5-pro \"complex analysis\"\nclaudish --model oai@o1 \"deep reasoning task\"\nclaudish --model openrouter@deepseek/deepseek-r1 \"analysis\"   # Unknown vendors need explicit OR\n\n# Local models with concurrency control\nclaudish --model ollama@llama3.2 \"code review\"\nclaudish --model ollama@llama3.2:3 \"parallel processing\"      # 3 concurrent\nclaudish --model lmstudio@qwen2.5-coder \"implement dashboard UI\"\n```\n\n### Autonomous Mode\n\nAuto-approve is **enabled by default**. For fully autonomous mode, add `--dangerous`:\n\n```bash\n# Basic usage (auto-approve already enabled)\nclaudish \"delete unused files\"\n\n# Fully autonomous (auto-approve + dangerous sandbox disabled)\nclaudish --dangerous \"install dependencies\"\n\n# Disable auto-approve if you want prompts\nclaudish --no-auto-approve \"make important changes\"\n```\n\n### Custom Port\n\n```bash\n# Use specific port\nclaudish --port 3000 \"analyze codebase\"\n\n# Or set default\nexport CLAUDISH_PORT=3000\nclaudish \"your task\"\n```\n\n### Passing Claude Flags\n\n```bash\n# Verbose mode\nclaudish \"debug issue\" --verbose\n\n# Custom working directory\nclaudish \"analyze code\" --cwd /path/to/project\n\n# Multiple flags\nclaudish --model openai/gpt-5.3-codex \"task\" --verbose --log-debug\n```\n\n### Monitor Mode\n\n**NEW!** Claudish now includes a monitor mode to help you understand how Claude Code works internally.\n\n```bash\n# Enable monitor mode (requires real Anthropic API key)\nclaudish --monitor --log-debug \"implement a feature\"\n```\n\n**What Monitor Mode Does:**\n- ✅ **Proxies to REAL Anthropic API** (not OpenRouter) - Uses your actual Anthropic API key\n- ✅ **Logs ALL traffic** - Captures complete requests and responses\n- ✅ **Both streaming and JSON** - Logs SSE streams and JSON responses\n- ✅ **Debug logs to file** - Saves to `logs/claudish_*.log` when `--log-debug` is used\n- ✅ **Pass-through proxy** - No translation, forwards as-is to Anthropic\n\n**When to use Monitor Mode:**\n- 🔍 Understanding Claude Code's API protocol\n- 🐛 Debugging integration issues\n- 📊 Analyzing Claude Code's behavior\n- 🔬 Research and development\n\n**Requirements:**\n```bash\n# Monitor mode requires a REAL Anthropic API key (not placeholder)\nexport ANTHROPIC_API_KEY='sk-ant-api03-...'\n\n# Use with --log-debug to save logs to file\nclaudish --monitor --log-debug \"your task\"\n\n# Logs are saved to: logs/claudish_TIMESTAMP.log\n```\n\n**Example Output:**\n```\n[Monitor] Server started on http://127.0.0.1:8765\n[Monitor] Mode: Passthrough to real Anthropic API\n[Monitor] All traffic will be logged for analysis\n\n=== [MONITOR] Claude Code → Anthropic API Request ===\n{\n  \"model\": \"claude-sonnet-4.5\",\n  \"messages\": [...],\n  \"max_tokens\": 4096,\n  ...\n}\n=== End Request ===\n\n=== [MONITOR] Anthropic API → Claude Code Response (Streaming) ===\nevent: message_start\ndata: {\"type\":\"message_start\",...}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",...}\n...\n=== End Streaming Response ===\n```\n\n**Note:** Monitor mode charges your Anthropic account (not OpenRouter). Use `--log-debug` flag to save logs for analysis.\n\n### Output Modes\n\nClaudish supports three output modes for different use cases:\n\n#### 1. Quiet Mode (Default in Single-Shot)\n\nClean output with no `[claudish]` logs - perfect for piping to other tools:\n\n```bash\n# Quiet by default in single-shot\nclaudish \"what is 2+2?\"\n# Output: 2 + 2 equals 4.\n\n# Use in pipelines\nclaudish \"list 3 colors\" | grep -i blue\n\n# Redirect to file\nclaudish \"analyze code\" \u003e analysis.txt\n```\n\n#### 2. Verbose Mode\n\nShow all `[claudish]` log messages for debugging:\n\n```bash\n# Verbose mode\nclaudish --verbose \"what is 2+2?\"\n# Output:\n# [claudish] Starting Claude Code with openai/gpt-4o\n# [claudish] Proxy URL: http://127.0.0.1:8797\n# [claudish] Status line: dir • openai/gpt-4o • $cost • ctx%\n# ...\n# 2 + 2 equals 4.\n# [claudish] Shutting down proxy server...\n# [claudish] Done\n\n# Interactive mode is verbose by default\nclaudish --interactive\n```\n\n#### 3. JSON Output Mode\n\nStructured output perfect for automation and tool integration:\n\n```bash\n# JSON output (always quiet)\nclaudish --json \"what is 2+2?\"\n# Output: {\"type\":\"result\",\"result\":\"2 + 2 equals 4.\",\"total_cost_usd\":0.068,\"usage\":{...}}\n\n# Extract just the result with jq\nclaudish --json \"list 3 colors\" | jq -r '.result'\n\n# Get cost and token usage\nclaudish --json \"analyze code\" | jq '{result, cost: .total_cost_usd, tokens: .usage.input_tokens}'\n\n# Use in scripts\nRESULT=$(claudish --json \"check if tests pass\" | jq -r '.result')\necho \"AI says: $RESULT\"\n\n# Track costs across multiple runs\nfor task in task1 task2 task3; do\n  claudish --json \"$task\" | jq -r '\"\\(.total_cost_usd)\"'\ndone | awk '{sum+=$1} END {print \"Total: $\"sum}'\n```\n\n**JSON Output Fields:**\n- `result` - The AI's response text\n- `total_cost_usd` - Total cost in USD\n- `usage.input_tokens` - Input tokens used\n- `usage.output_tokens` - Output tokens used\n- `duration_ms` - Total duration in milliseconds\n- `num_turns` - Number of conversation turns\n- `modelUsage` - Per-model usage breakdown\n\n## How It Works\n\n### Architecture\n\n```\nclaudish \"your prompt\"\n    ↓\n1. Parse arguments (--model, --no-auto-approve, --dangerous, etc.)\n2. Find available port (random or specified)\n3. Start local proxy on http://127.0.0.1:PORT\n4. Spawn: claude --auto-approve --env ANTHROPIC_BASE_URL=http://127.0.0.1:PORT\n5. Proxy translates: Anthropic API → OpenRouter API\n6. Stream output in real-time\n7. Cleanup proxy on exit\n```\n\n### Request Flow\n\n**Normal Mode (OpenRouter):**\n```\nClaude Code → Anthropic API format → Local Proxy → OpenRouter API format → OpenRouter\n                                         ↓\nClaude Code ← Anthropic API format ← Local Proxy ← OpenRouter API format ← OpenRouter\n```\n\n**Monitor Mode (Anthropic Passthrough):**\n```\nClaude Code → Anthropic API format → Local Proxy (logs) → Anthropic API\n                                         ↓\nClaude Code ← Anthropic API format ← Local Proxy (logs) ← Anthropic API\n```\n\n### Parallel Runs\n\nEach `claudish` invocation:\n- Gets a unique random port\n- Starts isolated proxy server\n- Runs independent Claude Code instance\n- Cleans up on exit\n\nThis allows multiple parallel runs:\n\n```bash\n# Terminal 1\nclaudish --model x-ai/grok-code-fast-1 \"task A\"\n\n# Terminal 2\nclaudish --model openai/gpt-5.3-codex \"task B\"\n\n# Terminal 3\nclaudish --model minimax/minimax-m2 \"task C\"\n```\n\n## Extended Thinking Support\n\n**NEW in v1.1.0**: Claudish now fully supports models with extended thinking/reasoning capabilities (Grok, o1, etc.) with complete Anthropic Messages API protocol compliance.\n\n### Thinking Translation Model (v1.5.0)\n\nClaudish includes a sophisticated **Thinking Translation Model** that aligns Claude Code's native thinking budget with the unique requirements of every major AI provider.\n\nWhen you set a thinking budget in Claude (e.g., `budget: 16000`), Claudish automatically translates it:\n\n| Provider | Model | Translation Logic |\n| :--- | :--- | :--- |\n| **OpenAI** | o1, o3 | Maps budget to `reasoning_effort` (minimal/low/medium/high) |\n| **Google** | Gemini 3 | Maps to `thinking_level` (low/high) |\n| **Google** | Gemini 2.x | Passes exact `thinking_budget` (capped at 24k) |\n| **xAI** | Grok 3 Mini | Maps to `reasoning_effort` (low/high) |\n| **Qwen** | Qwen 2.5 | Enables `enable_thinking` + exact budget |\n| **MiniMax** | M2 | Enables `reasoning_split` (interleaved thinking) |\n| **DeepSeek** | R1 | Automatically manages reasoning (params stripped for safety) |\n\nThis ensures you can use standard Claude Code thinking controls with **ANY** supported model, without worrying about API specificities.\n\n### What is Extended Thinking?\n\nSome AI models (like Grok and OpenAI's o1) can show their internal reasoning process before providing the final answer. This \"thinking\" content helps you understand how the model arrived at its conclusion.\n\n### How Claudish Handles Thinking\n\nClaudish implements the Anthropic Messages API's `interleaved-thinking` protocol:\n\n**Thinking Blocks (Hidden):**\n- Contains model's reasoning process\n- Automatically collapsed in Claude Code UI\n- Shows \"Claude is thinking...\" indicator\n- User can expand to view reasoning\n\n**Text Blocks (Visible):**\n- Contains final response\n- Displayed normally\n- Streams incrementally\n\n### Supported Models with Thinking\n\n- ✅ **x-ai/grok-code-fast-1** - Grok's reasoning mode\n- ✅ **openai/gpt-5-codex** - o1 reasoning (when enabled)\n- ✅ **openai/o1-preview** - Full reasoning support\n- ✅ **openai/o1-mini** - Compact reasoning\n- ⚠️ Other models may support reasoning in future\n\n### Technical Details\n\n**Streaming Protocol (V2 - Protocol Compliant):**\n```\n1. message_start\n2. content_block_start (text, index=0)      ← IMMEDIATE! (required)\n3. ping\n4. [If reasoning arrives]\n   - content_block_stop (index=0)           ← Close initial empty block\n   - content_block_start (thinking, index=1) ← Reasoning\n   - thinking_delta events × N\n   - content_block_stop (index=1)\n5. content_block_start (text, index=2)      ← Response\n6. text_delta events × M\n7. content_block_stop (index=2)\n8. message_delta + message_stop\n```\n\n**Critical:** `content_block_start` must be sent immediately after `message_start`, before `ping`. This is required by the Anthropic Messages API protocol for proper UI initialization.\n\n**Key Features:**\n- ✅ Separate thinking and text blocks (proper indices)\n- ✅ `thinking_delta` vs `text_delta` event types\n- ✅ Thinking content hidden by default\n- ✅ Smooth transitions between blocks\n- ✅ Full Claude Code UI compatibility\n\n### UX Benefits\n\n**Before (v1.0.0 - No Thinking Support):**\n- Reasoning visible as regular text\n- Confusing output with internal thoughts\n- No progress indicators\n- \"All at once\" message updates\n\n**After (v1.1.0 - Full Protocol Support):**\n- ✅ Reasoning hidden/collapsed\n- ✅ Clean, professional output\n- ✅ \"Claude is thinking...\" indicator shown\n- ✅ Smooth incremental streaming\n- ✅ Message headers/structure visible\n- ✅ Protocol compliant with Anthropic Messages API\n\n### Documentation\n\nFor complete protocol documentation, see:\n- [STREAMING_PROTOCOL.md](./STREAMING_PROTOCOL.md) - Complete SSE protocol spec\n- [PROTOCOL_FIX_V2.md](./PROTOCOL_FIX_V2.md) - Critical V2 protocol fix (event ordering)\n- [COMPREHENSIVE_UX_ISSUE_ANALYSIS.md](./COMPREHENSIVE_UX_ISSUE_ANALYSIS.md) - Technical analysis\n- [THINKING_BLOCKS_IMPLEMENTATION.md](./THINKING_BLOCKS_IMPLEMENTATION.md) - Implementation summary\n\n## Dynamic Reasoning Support (NEW in v1.4.0)\n\n**Claudish now intelligently adapts to ANY reasoning model!**\n\nNo more hardcoded lists or manual flags. Claudish dynamically queries OpenRouter metadata to enable thinking capabilities for any model that supports them.\n\n### 🧠 Dynamic Thinking Features\n\n1.  **Auto-Detection**:\n    - Automatically checks model capabilities at startup\n    - Enables Extended Thinking UI *only* when supported\n    - Future-proof: Works instantly with new models (e.g., `deepseek-r1` or `minimax-m2`)\n\n2.  **Smart Parameter Mapping**:\n    - **Claude**: Passes token budget directly (e.g., 16k tokens)\n    - **OpenAI (o1/o3)**: Translates budget to `reasoning_effort`\n        - \"ultrathink\" (≥32k) → `high`\n        - \"think hard\" (16k-32k) → `medium`\n        - \"think\" (\u003c16k) → `low`\n    - **Gemini \u0026 Grok**: Preserves thought signatures and XML traces automatically\n\n3.  **Universal Compatibility**:\n    - Use \"ultrathink\" or \"think hard\" prompts with ANY supported model\n    - Claudish handles the translation layer for you\n\n## Context Scaling \u0026 Auto-Compaction\n\n**NEW in v1.2.0**: Claudish now intelligently manages token counting to support ANY context window size (from 128k to 2M+) while preserving Claude Code's native auto-compaction behavior.\n\n### The Challenge\n\nClaude Code naturally assumes a fixed context window (typically 200k tokens for Sonnet).\n- **Small Models (e.g., Grok 128k)**: Claude might overuse context and crash.\n- **Massive Models (e.g., Gemini 2M)**: Claude would compact way too early (at 10% usage), wasting the model's potential.\n\n### The Solution: Token Scaling\n\nClaudish implements a \"Dual-Accounting\" system:\n\n1. **Internal Scaling (For Claude):**\n   - We fetch the *real* context limit from OpenRouter (e.g., 1M tokens).\n   - We scale reported token usage so Claude *thinks* 1M tokens is 200k.\n   - **Result:** Auto-compaction triggers at the correct *percentage* of usage (e.g., 90% full), regardless of the actual limit.\n\n2. **Accurate Reporting (For You):**\n   - The status line displays the **Real Unscaled Usage** and **Real Context %**.\n   - You see specific costs and limits, while Claude remains blissfully unaware and stable.\n\n**Benefits:**\n- ✅ **Works with ANY model** size (128k, 1M, 2M, etc.)\n- ✅ **Unlocks massive context** windows (Claude Code becomes 10x more powerful with Gemini!)\n- ✅ **Prevents crashes** on smaller models (Grok)\n- ✅ **Native behavior** (compaction just works)\n\n\n## Development\n\n### Project Structure\n\n```\nmcp/claudish/\n├── src/\n│   ├── index.ts              # Main entry point\n│   ├── cli.ts                # CLI argument parser\n│   ├── proxy-server.ts       # Hono-based proxy server\n│   ├── transform.ts          # API format translation (from claude-code-proxy)\n│   ├── claude-runner.ts      # Claude CLI runner (creates temp settings)\n│   ├── port-manager.ts       # Port utilities\n│   ├── config.ts             # Constants and defaults\n│   ├── types.ts              # TypeScript types\n│   └── services/\n│       └── vision-proxy.ts   # Image description for non-vision models\n├── tests/                    # Test files\n├── package.json\n├── tsconfig.json\n└── biome.json\n```\n\n### Proxy Implementation\n\nClaudish uses a **Hono-based proxy server** inspired by [claude-code-proxy](https://github.com/kiyo-e/claude-code-proxy):\n\n- **Framework**: [Hono](https://hono.dev/) - Fast, lightweight web framework\n- **API Translation**: Converts Anthropic API format ↔ OpenAI format\n- **Streaming**: Full support for Server-Sent Events (SSE)\n- **Tool Calling**: Handles Claude's tool_use ↔ OpenAI's tool_calls\n- **Battle-tested**: Based on production-ready claude-code-proxy implementation\n\n**Why Hono?**\n- Native Bun support (no adapters needed)\n- Extremely fast and lightweight\n- Middleware support (CORS, logging, etc.)\n- Works across Node.js, Bun, and Cloudflare Workers\n\n### Build \u0026 Test\n\n```bash\n# Install dependencies\nbun install\n\n# Development mode\nbun run dev \"test prompt\"\n\n# Build\nbun run build\n\n# Lint\nbun run lint\n\n# Format\nbun run format\n\n# Type check\nbun run typecheck\n\n# Run tests\nbun test\n```\n\n### Protocol Compliance Testing\n\nClaudish includes a comprehensive snapshot testing system to ensure 1:1 compatibility with the official Claude Code protocol:\n\n```bash\n# Run snapshot tests (13/13 passing ✅)\nbun test tests/snapshot.test.ts\n\n# Full workflow: capture fixtures + run tests\n./tests/snapshot-workflow.sh --full\n\n# Capture new test fixtures from monitor mode\n./tests/snapshot-workflow.sh --capture\n\n# Debug SSE events\nbun tests/debug-snapshot.ts\n```\n\n**What Gets Tested:**\n- ✅ Event sequence (message_start → content_block_start → deltas → stop → message_delta → message_stop)\n- ✅ Content block indices (sequential: 0, 1, 2, ...)\n- ✅ Tool input streaming (fine-grained JSON chunks)\n- ✅ Usage metrics (present in message_start and message_delta)\n- ✅ Stop reasons (always present and valid)\n- ✅ Cache metrics (creation and read tokens)\n\n**Documentation:**\n- [Quick Start Guide](./QUICK_START_TESTING.md) - Get started with testing\n- [Snapshot Testing Guide](./SNAPSHOT_TESTING.md) - Complete testing documentation\n- [Implementation Details](./ai_docs/IMPLEMENTATION_COMPLETE.md) - Technical implementation summary\n- [Protocol Compliance Plan](./ai_docs/PROTOCOL_COMPLIANCE_PLAN.md) - Detailed compliance roadmap\n\n### Install Globally\n\n```bash\n# Link for global use\nbun run install:global\n\n# Now use anywhere\nclaudish \"your task\"\n```\n\n## Troubleshooting\n\n### \"Claude Code CLI is not installed\"\n\nInstall Claude Code:\n\n```bash\nnpm install -g claude-code\n# or visit: https://claude.com/claude-code\n```\n\n### \"OPENROUTER_API_KEY environment variable is required\"\n\nSet your API key:\n\n```bash\nexport OPENROUTER_API_KEY=sk-or-v1-...\n```\n\nOr add to your shell profile (`~/.zshrc`, `~/.bashrc`):\n\n```bash\necho 'export OPENROUTER_API_KEY=sk-or-v1-...' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n### \"No available ports found\"\n\nSpecify a custom port:\n\n```bash\nclaudish --port 3000 \"your task\"\n```\n\nOr increase port range in `src/config.ts`.\n\n### Proxy errors\n\nCheck OpenRouter API status:\n- https://openrouter.ai/status\n\nVerify your API key works:\n- https://openrouter.ai/keys\n\n### Status line not showing model\n\nIf the status line doesn't show the model name:\n\n1. **Check if --settings flag is being passed:**\n   ```bash\n   # Look for this in Claudish output:\n   # [claudish] Instance settings: /tmp/claudish-settings-{timestamp}.json\n   ```\n\n2. **Verify environment variable is set:**\n   ```bash\n   # Should be set automatically by Claudish\n   echo $CLAUDISH_ACTIVE_MODEL_NAME\n   # Should output something like: xAI/Grok-1\n   ```\n\n3. **Test status line command manually:**\n   ```bash\n   export CLAUDISH_ACTIVE_MODEL_NAME=\"xAI/Grok-1\"\n   cat \u003e /dev/null \u0026\u0026 echo \"[$CLAUDISH_ACTIVE_MODEL_NAME] 📁 $(basename \"$(pwd)\")\"\n   # Should output: [xAI/Grok-1] 📁 your-directory-name\n   ```\n\n4. **Check temp settings file:**\n   ```bash\n   # File is created in /tmp/claudish-settings-*.json\n   ls -la /tmp/claudish-settings-*.json 2\u003e/dev/null | tail -1\n   cat /tmp/claudish-settings-*.json | head -1\n   ```\n\n5. **Verify bash is available:**\n   ```bash\n   which bash\n   # Should show path to bash (usually /bin/bash or /usr/bin/bash)\n   ```\n\n**Note:** Temp settings files are automatically cleaned up when Claudish exits. If you see multiple files, you may have crashed instances - they're safe to delete manually.\n\n## Comparison with Claude Code\n\n| Feature | Claude Code | Claudish |\n|---------|-------------|----------|\n| Model | Anthropic models only | Any OpenRouter model |\n| API | Anthropic API | OpenRouter API |\n| Cost | Anthropic pricing | OpenRouter pricing |\n| Setup | API key → direct | API key → proxy → OpenRouter |\n| Speed | Direct connection | ~Same (local proxy) |\n| Features | All Claude Code features | All Claude Code features |\n| Vision | Native (Anthropic models) | Any model (auto-described via Claude) |\n\n**When to use Claudish:**\n- ✅ Want to try different models (Grok, GPT-5, etc.)\n- ✅ Need OpenRouter-specific features\n- ✅ Prefer OpenRouter pricing\n- ✅ Testing model performance\n\n**When to use Claude Code:**\n- ✅ Want latest Anthropic models only\n- ✅ Need official Anthropic support\n- ✅ Simpler setup (no proxy)\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repo\n2. Create feature branch: `git checkout -b feature/amazing`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing`\n5. Open Pull Request\n\n## License\n\nMIT © MadAppGang\n\n## Acknowledgments\n\nClaudish's proxy implementation is based on [claude-code-proxy](https://github.com/kiyo-e/claude-code-proxy) by [@kiyo-e](https://github.com/kiyo-e). We've adapted their excellent Hono-based API translation layer for OpenRouter integration.\n\n**Key contributions from claude-code-proxy:**\n- Anthropic ↔ OpenAI API format translation (`transform.ts`)\n- Streaming response handling with Server-Sent Events\n- Tool calling compatibility layer\n- Clean Hono framework architecture\n\nThank you to the claude-code-proxy team for building a robust, production-ready foundation! 🙏\n\n## Links\n\n- **GitHub**: https://github.com/MadAppGang/claudish\n- **OpenRouter**: https://openrouter.ai\n- **Claude Code**: https://claude.com/claude-code\n- **Bun**: https://bun.sh\n- **Hono**: https://hono.dev\n- **claude-code-proxy**: https://github.com/kiyo-e/claude-code-proxy\n\n---\n\nMade with ❤️ by [MadAppGang](https://madappgang.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadappgang%2Fclaudish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadappgang%2Fclaudish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadappgang%2Fclaudish/lists"}