### Quick Start CLI Commands

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Basic commands to get started with Claudish, including listing models, running tasks with different providers, and using stdin for large prompts.

```bash
claudish --models --json
```

```bash
claudish --model openai/gpt-5.3 "your task here"
```

```bash
claudish --model g/gemini-2.0-flash "your task here"
```

```bash
claudish --model ollama/llama3.2 "your task here"
```

```bash
echo "your task" | claudish --stdin --model openai/gpt-5.3
```

--------------------------------

### OllamaCloud examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Examples for routing to cloud-hosted Llama models using OllamaCloud shortcuts.

```bash
claudish --model llama@llama-3.1-70b "code review"
```

```bash
claudish --model oc@llama-3.2-vision "analyze image"
```

--------------------------------

### Print Help Guide

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Prints the Claudish AI agent guide to the console.

```bash
# Print this guide
claudish --help-ai
```

--------------------------------

### Output Mode Examples

Source: https://github.com/madappgang/claudish/blob/main/skills/claudish-usage/SKILL.md

Examples of different output modes including quiet, verbose, and JSON.

```bash
claudish --model grok "task"
```

```bash
claudish --verbose "task"
```

```bash
claudish --json "task"
```

--------------------------------

### Install and Run Claudish CLI (Interactive)

Source: https://github.com/madappgang/claudish/blob/main/docs/index.md

Install Claudish globally using npx and run it in interactive mode to select a model and start coding.

```bash
npx claudish@latest
```

--------------------------------

### Recommended Configuration Profiles

Source: https://github.com/madappgang/claudish/blob/main/docs/models/model-mapping.md

Example configurations for cost-optimized development or maximum capability.

```bash
# .env or shell profile
export CLAUDISH_MODEL_OPUS='google/gemini-3-pro-preview'    # $7.00/1M - for complex planning
export CLAUDISH_MODEL_SONNET='x-ai/grok-code-fast-1'        # $0.85/1M - daily driver
export CLAUDISH_MODEL_HAIKU='minimax/minimax-m2'            # $0.60/1M - quick tasks
export CLAUDISH_MODEL_SUBAGENT='minimax/minimax-m2'         # $0.60/1M - parallel workers
```

```bash
export CLAUDISH_MODEL_OPUS='google/gemini-3-pro-preview'    # 1M context
export CLAUDISH_MODEL_SONNET='openai/gpt-5.1-codex'         # Code specialist
export CLAUDISH_MODEL_HAIKU='x-ai/grok-code-fast-1'         # Fast and capable
export CLAUDISH_MODEL_SUBAGENT='x-ai/grok-code-fast-1'
```

--------------------------------

### Install Claudish from source

Source: https://github.com/madappgang/claudish/blob/main/README.md

Clone the repository, install dependencies, build the project, and link it locally for development.

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

--------------------------------

### CLI Flag Examples

Source: https://github.com/madappgang/claudish/blob/main/skills/claudish-usage/SKILL.md

Common usage examples for essential CLI flags.

```bash
--model x-ai/grok-code-fast-1
```

```bash
git diff | claudish --stdin --model grok
```

```bash
claudish --models
```

```bash
claudish --models gemini
```

```bash
claudish --top-models
```

```bash
claudish --json "task"
```

```bash
claudish --help-ai
```

--------------------------------

### Example Monitor Session

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/monitor-mode.md

Demonstrates the output of a monitor session and how to view the resulting log file.

```bash
$ claudish --monitor --debug "list files in the current directory"

[claudish] Monitor mode enabled - proxying to real Anthropic API
[claudish] API key will be extracted from Claude Code's requests
[claudish] Debug logs: logs/claudish_2024-01-15_103042.log

# ... Claude Code runs normally ...

[claudish] Session complete. Check logs for full request/response data.
```

```bash
cat logs/claudish_2024-01-15_103042.log
```

--------------------------------

### Save Help Guide to File

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Saves the Claudish AI agent guide to a markdown file.

```bash
# Save to file
claudish --help-ai > claudish-agent-guide.md
```

--------------------------------

### Vertex AI Partner Model Examples

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Examples demonstrating how to use various partner models available through Vertex AI, including MiniMax, Mistral, DeepSeek, Qwen, and OpenAI OSS.

```bash
claudish --model v/gemini-2.5-flash "task"
```

```bash
claudish --model vertex/minimax/minimax-m2-maas "task"
```

```bash
claudish --model vertex/mistralai/codestral-2 "write code"
```

```bash
claudish --model vertex/deepseek/deepseek-v3-2-maas "analyze"
```

```bash
claudish --model vertex/qwen/qwen3-coder-480b-a35b-instruct-maas "implement"
```

```bash
claudish --model vertex/openai/gpt-oss-120b-maas "reason"
```

--------------------------------

### Example .env File

Source: https://github.com/madappgang/claudish/blob/main/docs/advanced/environment.md

Template for configuring Claudish via a local .env file.

```bash
# Required
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Default model
CLAUDISH_MODEL=x-ai/grok-code-fast-1

# Model mapping (optional)
CLAUDISH_MODEL_OPUS=google/gemini-3-pro-preview
CLAUDISH_MODEL_SONNET=x-ai/grok-code-fast-1
CLAUDISH_MODEL_HAIKU=minimax/minimax-m2
CLAUDISH_MODEL_SUBAGENT=minimax/minimax-m2

# Fixed port (optional)
# CLAUDISH_PORT=3456
```

--------------------------------

### Claudish CLI: Agent Selection Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example demonstrating agent selection with --agent flag, combined with --stdin and --quiet.

```bash
claudish --model grok --agent code-review --stdin --quiet < prompt.md
```

--------------------------------

### Example .env Template

Source: https://github.com/madappgang/claudish/blob/main/docs/advanced/environment.md

A safe-to-commit template for environment variables.

```bash
# .env.example (safe to commit)
OPENROUTER_API_KEY=your-key-here
CLAUDISH_MODEL=x-ai/grok-code-fast-1
```

--------------------------------

### Install Magmux with Go

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/magmux.md

Installs Magmux directly using the Go toolchain. This method is suitable if you have Go installed and prefer not to use a package manager.

```bash
go install github.com/MadAppGang/magmux@latest
```

--------------------------------

### Magmux Pane Layout Examples

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/magmux.md

Demonstrates how Magmux adapts its pane layout based on the number of commands provided. Examples include fullscreen for one pane, side-by-side for two, and a default three-pane layout.

```bash
# 1 pane: fullscreen
magmux -e "claudish --model gemini-3-pro"
```

```bash
# 2 panes: side by side
magmux -e "claudish --model gemini-3-pro" -e "claudish --model grok-code-fast-1"
```

```bash
# 3 panes: default (runs your login shell in each)
magmux
```

--------------------------------

### Claudish CLI: Permission Mode Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example of setting the permission mode to 'plan' for Claudish execution.

```bash
claudish --model grok --permission-mode plan --stdin --quiet < prompt.md
```

--------------------------------

### Get Claudish AI Agent Help

Source: https://github.com/madappgang/claudish/blob/main/README.md

Display the complete AI agent usage guide or save it to a file for offline reference. This provides detailed instructions on advanced agent workflows.

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

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

--------------------------------

### Install Claudish using Bun

Source: https://github.com/madappgang/claudish/blob/main/README.md

Install Claudish globally using the Bun runtime.

```bash
bun install -g claudish
```

--------------------------------

### Install and Run Development Mode

Source: https://github.com/madappgang/claudish/blob/main/README.md

Commands to install project dependencies and run Claudish in development mode with a test prompt.

```bash
# Install dependencies
bun install

# Development mode
bun run dev "test prompt"
```

--------------------------------

### Compare Task Execution Patterns

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/skills/claudish-usage/SKILL.md

Examples showing the difference between simple agent tasks and complex file-based workflows.

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

```typescript
// multi-phase-workflow.md
Phase 1: Use api-architect to design API
Phase 2: Use backend-developer to implement
Phase 3: Use test-architect to add tests
Phase 4: Use senior-code-reviewer to review

then:
claudish --model x-ai/grok-code-fast-1 --stdin < multi-phase-workflow.md
```

--------------------------------

### Claudish CLI: Effort and Budget Control Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example showing how to control agent effort and maximum budget using --effort and --max-budget-usd flags.

```bash
claudish --model grok --effort high --max-budget-usd 0.50 --stdin --quiet < prompt.md
```

--------------------------------

### Check and Install screen-256color Terminfo

Source: https://github.com/madappgang/claudish/blob/main/docs/advanced/mtm-to-magmux-migration.md

If panes render garbled text, verify that the 'screen-256color' terminfo is installed. If it's missing, install 'ncurses-term' on Linux or use 'xterm-256color' as a fallback.

```bash
infocmp screen-256color >/dev/null 2>&1 && echo "OK" || echo "MISSING"

# If missing, install ncurses-term (Linux) or use the fallback:
TERM=xterm-256color magmux -g grid.txt -S status.txt
```

--------------------------------

### Equivalent Routing Configuration

Source: https://github.com/madappgang/claudish/blob/main/docs/settings-reference.md

This configuration is equivalent to the previous example, explicitly showing the synthesized catch-all rule.

```json
{
  "routing": {
    "kimi-*": ["kc", "kimi", "or"],
    "*": ["litellm"]
  }
}
```

--------------------------------

### Explicit provider routing examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Use these examples to explicitly specify the provider for your model requests, ensuring requests go to the intended service.

```bash
claudish --model google@gemini-2.5-pro "complex analysis"
```

```bash
claudish --model oai@o1 "complex reasoning"
```

```bash
claudish --model openrouter@deepseek/deepseek-r1 "deep analysis"
```

--------------------------------

### Claudish Profile Configuration Example

Source: https://github.com/madappgang/claudish/blob/main/README.md

Example of a global Claudish configuration file defining default profiles and routing rules. Local `.claudish.json` files can override these rules.

```json
{
  "version": "1.0.0",
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "name": "default",
      "models": {
        "opus": "oai@gpt-5.3",
        "sonnet": "google@gemini-3-pro",
        "haiku": "mm@MiniMax-M2.1",
        "subagent": "google@gemini-2.0-flash"
      }
    }
  },
  "routing": {
    "kimi-*": ["kc", "kimi", "openrouter"],
    "glm-*": ["gc", "glm"],
    "*": ["litellm", "openrouter"]
  }
}
```

--------------------------------

### Default Provider Configuration Example

Source: https://github.com/madappgang/claudish/blob/main/CLAUDE.md

Example JSON configuration for setting the default provider in Claudish.

```json
{
  "defaultProvider": "openrouter",
  "customEndpoints": { ... }
}
```

--------------------------------

### Start MCP Server

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

Initiate the Claudish MCP server using the `--mcp` flag for stdio transport.

```bash
# Start MCP server (stdio transport)
claudish --mcp
```

--------------------------------

### Claudish CLI: System Prompt Passthrough Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example using the '--' separator to pass a system prompt that starts with a hyphen.

```bash
claudish --model grok -- --system-prompt "-v mode" --stdin --quiet < prompt.md
```

--------------------------------

### Claudish CLI: JSON Output Flag Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example of using the --json flag to get structured JSON output from Claudish.

```bash
claudish --json "task"
```

--------------------------------

### Reproduce Advisor Swap Setup and Testing

Source: https://github.com/madappgang/claudish/blob/main/experiments/tool-replacement-proxy-2026-04/research/06-stage2-tool-result-rewrite.md

Commands to set up the environment, run the claudish CLI with advisor swap enabled, and observe the resulting logs for analysis.

```bash
cd /Users/jack/mag/claudish
bun test packages/cli/src/handlers/native-handler-advisor.test.ts  # 18/18

export CLAUDISH_SWAP_ADVISOR=1
export CLAUDISH_SWAP_ADVISOR_LOG=/tmp/advisor-swap.ndjson
export CLAUDISH_SWAP_ADVISOR_DUMP=1
bun run packages/cli/src/index.ts --monitor

# In Claude Code:
/advisor opus
# then:
"Design a distributed rate limiter. Consult the advisor before proposing an approach."

# Observe:
jq -c '{ts, kind, ids: (.ids // null), rewritten: (.rewrittenIds // null)}' /tmp/advisor-swap.ndjson
```

--------------------------------

### Claudish Basic Prompt Examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Demonstrates how to use Claudish with simple and multi-word prompts for code-related tasks.

```bash
claudish "fix the bug in user.ts"
```

```bash
claudish "implement user authentication with JWT tokens"
```

--------------------------------

### Error Handling Fixes

Source: https://github.com/madappgang/claudish/blob/main/skills/claudish-usage/SKILL.md

Commands to resolve common configuration and installation errors.

```bash
export OPENROUTER_API_KEY='sk-or-v1-...'
```

```bash
npm install -g claudish
```

```bash
bun install -g claudish
```

```bash
claudish --models
```

```bash
claudish --model x-ai/grok-code-fast-1 "task"
```

```bash
claudish --model grok "task"
```

```bash
claudish --port 8080 --model grok "task"
```

--------------------------------

### Provider Routing Syntax Examples

Source: https://github.com/madappgang/claudish/blob/main/docs/settings-reference.md

Illustrates the current syntax for specifying providers and models, including direct API access, OpenRouter, local Ollama with concurrency limits, and LiteLLM proxy.

```shell
google@gemini-3-pro              # Direct Google Gemini API
oai@gpt-5.3                     # Direct OpenAI API
openrouter@deepseek/deepseek-r1  # Explicit OpenRouter with vendor-prefixed model
ollama@llama3.2                  # Local Ollama, sequential (default)
ollama@llama3.2:3                # Local Ollama, allow up to 3 concurrent requests
ollama@llama3.2:0                # Local Ollama, no concurrency limit (bypass queue)
ll@my-model                      # LiteLLM proxy with auto catalog resolution
```

--------------------------------

### Claudish Custom Port Examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Demonstrates how to specify a custom port for Claudish or set a default port using an environment variable.

```bash
# Use specific port
claudish --port 3000 "analyze codebase"
```

```bash
# Or set default
export CLAUDISH_PORT=3000
claudish "your task"
```

--------------------------------

### Get Claudish Version

Source: https://github.com/madappgang/claudish/blob/main/docs/troubleshooting.md

Retrieve the installed version of the Claudish CLI. This is useful when reporting bugs or checking compatibility.

```bash
claudish --version
```

--------------------------------

### Getting Model List with Claudish

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

How to retrieve a list of available models using Claudish, with examples for JSON output and TypeScript parsing.

```APIDOC
## Getting Model List

Claudish provides functionality to list available models, with a recommended JSON output format.

### JSON Output (Recommended)

To get a list of models in JSON format, use the `--list-models --json` flags:

```bash
claudish --list-models --json
```

**Example JSON Output:**

```json
{
  "version": "1.8.0",
  "lastUpdated": "2025-11-19",
  "source": "https://openrouter.ai/models",
  "models": [
    {
      "id": "x-ai/grok-code-fast-1",
      "name": "Grok Code Fast 1",
      "description": "Ultra-fast agentic coding",
      "provider": "xAI",
      "category": "coding",
      "priority": 1,
      "pricing": {
        "input": "$0.20/1M",
        "output": "$1.50/1M",
        "average": "$0.85/1M"
      },
      "context": "256K",
      "supportsTools": true,
      "supportsReasoning": true
    }
  ]
}
```

### Parse in TypeScript

Here's an example of how to parse the JSON output in TypeScript:

```typescript
// Assuming 'Bash' is a function that executes shell commands and returns stdout
const { stdout } = await Bash("claudish --list-models --json");
const data = JSON.parse(stdout);

// Get all model IDs
const modelIds = data.models.map(m => m.id);

// Get coding models
const codingModels = data.models.filter(m => m.category === "coding");

// Get cheapest model based on average pricing
const cheapest = data.models.sort((a, b) =>
  parseFloat(a.pricing.average) - parseFloat(b.pricing.average)
)[0];
```
```

--------------------------------

### Get Node.js Version

Source: https://github.com/madappgang/claudish/blob/main/docs/troubleshooting.md

Check the installed Node.js version. This information is often required when reporting issues with Node.js-based tools like Claudish.

```bash
node --version
```

--------------------------------

### Legacy syntax for provider routing (deprecated)

Source: https://github.com/madappgang/claudish/blob/main/README.md

These examples show the old `prefix/model` syntax, which is deprecated but still functional. The recommended syntax uses `@`.

```bash
# Old (deprecated)          →  New (recommended)
claudish --model g/gemini-pro     →  claudish --model g@gemini-pro
```

```bash
claudish --model oai/gpt-4o       →  claudish --model oai@gpt-4o
```

```bash
claudish --model ollama/llama3.2  →  claudish --model ollama@llama3.2
```

--------------------------------

### Get Task Cost from JSON Output

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Extracts the total cost in USD for a given task from Claudish's JSON output. Requires `jq` to be installed for parsing.

```bash
COST=$(claudish --json "task" | jq -r '.total_cost_usd')
echo "Task cost: \$${COST}"
```

--------------------------------

### Write Task Instructions to File

Source: https://github.com/madappgang/claudish/blob/main/docs/ai-integration/for-agents.md

Create a markdown file containing the task description, focus areas, and output format for the sub-agent.

```bash
# Main agent writes task to file
cat > /tmp/claudish-task-abc123.md << 'EOF'
## Task
Review the authentication module in src/auth/

## Focus Areas
- Security vulnerabilities
- Error handling
- Performance issues

## Output Format
Return a markdown report with findings.
EOF
```

--------------------------------

### Claudish MCP Tool Use Case: Get a Second Opinion

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/mcp-server.md

Example prompt for obtaining a second opinion on code from a specific model using Claudish MCP.

```text
Claude, use GPT-5 Codex to review the error handling in this function
```

--------------------------------

### Configure MCP Server using npx

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Configures an MCP server to use the latest Claudish version via npx, avoiding local installation. Useful for quick setup or testing.

```json
{
  "mcpServers": {
    "claudish": {
      "command": "npx",
      "args": ["claudish@latest", "--mcp"]
    }
  }
}
```

--------------------------------

### Install and Verify Claudish

Source: https://github.com/madappgang/claudish/blob/main/docs/settings-reference.md

Installs Claudish globally and verifies the installation by checking the version.

```bash
# Install / verify
npm install -g claudish
claudish --version
```

--------------------------------

### Access Help Documentation

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/skills/claudish-usage/SKILL.md

Commands to display CLI usage and AI agent guidance.

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

--------------------------------

### Install Magmux with Homebrew

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/magmux.md

Installs Magmux using the Homebrew package manager on macOS. Ensure you have Homebrew installed before running this command.

```bash
brew install MadAppGang/tap/magmux
```

--------------------------------

### Channel Mode Workflow Example

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/mcp-server.md

Illustrates the sequence of operations for managing an asynchronous model session using channel mode, from creation to retrieving output.

```text
1. create_session(model: "google@gemini-2.0-flash", prompt: "Refactor this module")
   → { session_id: "sess_abc123", status: "starting" }

2. <channel event="session_started" session_id="sess_abc123" ...>
   <channel event="tool_executing" tool_count="3" ...>

3. <channel event="input_required" session_id="sess_abc123">
   "Should I keep the old interface for backwards compatibility?"

4. send_input(session_id: "sess_abc123", text: "Yes, keep the old interface")

5. <channel event="completed" session_id="sess_abc123">

6. get_output(session_id: "sess_abc123")
   → { lines: [...], status: "completed" }
```

--------------------------------

### Verify Claudish Installation

Source: https://github.com/madappgang/claudish/blob/main/docs/troubleshooting.md

Check if Claudish is installed and accessible in your system's PATH. This helps confirm the global installation was successful.

```bash
which claudish
```

```bash
claudish --version
```

--------------------------------

### File-Based Instruction Workflow

Source: https://github.com/madappgang/claudish/blob/main/skills/claudish-usage/SKILL.md

Best practice for using file-based inputs to manage context window usage.

```bash
echo "Implement feature X" > /tmp/task.md

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

cat /tmp/result.md
```

--------------------------------

### Checking Claudish Installation

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

Verify if Claudish is installed by attempting to locate it using the 'which' command. If not found, an error is logged, suggesting installation.

```typescript
try {
  await Bash("which claudish");
} catch (error) {
  console.error("Claudish not installed. Install with: npm install -g claudish");
  // Use fallback (embedded Claude models)
}
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/madappgang/claudish/blob/main/README.md

Install the Claude Code CLI globally using npm. Alternatively, visit the provided URL for installation instructions.

```bash
npm install -g claude-code
# or visit: https://claude.com/claude-code
```

--------------------------------

### Check Claude Code CLI Installation

Source: https://github.com/madappgang/claudish/blob/main/docs/troubleshooting.md

Verify if the official Claude Code CLI is installed, as Claudish depends on it. If not installed, instructions to obtain it are provided.

```bash
claude --version
```

--------------------------------

### Install Claudish with npx

Source: https://github.com/madappgang/claudish/blob/main/docs/troubleshooting.md

Use npx to run Claudish without a global installation. This is useful for trying out the latest version or for environments where global installs are restricted.

```bash
npx claudish@latest --version
```

--------------------------------

### Installation Command for Claudish

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

Install the Claudish CLI globally using npm.

```bash
# Installation
npm install -g claudish
```

--------------------------------

### Show Curated Recommendations

Source: https://github.com/madappgang/claudish/blob/main/README.md

Use this command to display the top recommended models for development.

```bash
claudish --top-models          # Show curated recommendations
```

--------------------------------

### Stage 1: Tool Swap Detection Setup

Source: https://github.com/madappgang/claudish/blob/main/experiments/tool-replacement-proxy-2026-04/README.md

Command to set up and run the Claudish monitor in Stage 1, focusing on tool swap detection. Logs are saved to `/tmp/advisor-swap.ndjson`.

```bash
cd /Users/jack/mag/claudish

# Apply the patch (if not already applied):
cp experiments-patch/native-handler-advisor.ts packages/cli/src/handlers/
# Then re-apply the native-handler.ts changes per claudish-patch/native-handler.patch

export CLAUDISH_SWAP_ADVISOR=1
export CLAUDISH_SWAP_ADVISOR_LOG=/tmp/advisor-swap.ndjson
bun run packages/cli/src/index.ts --monitor

# In Claude Code:
/advisor opus
"Design a rate limiter. Consult the advisor."

# Check:
jq -c '{kind, ids: .ids}' /tmp/advisor-swap.ndjson | grep tool_use_for_advisor
# Should show: tool_use_for_advisor with an id → Stage 1 passes
```

--------------------------------

### Full Configuration (Later)

Source: https://github.com/madappgang/claudish/blob/main/experiments/tool-replacement-proxy-2026-04/research/01-advisor-pattern-research.md

Comprehensive configuration for advisor profiles, trigger policies, budgets, and timeouts.

```json
{
  "advisor": {
    "enabled": true,
    "mode": "manual",
    "defaultAdvisor": "gemini",
    "profiles": {
      "architecture": ["gemini"],
      "debug": ["grok"],
      "review": ["gpt"]
    },
    "triggerPolicy": {
      "consultOnLowConfidence": true,
      "consultAfterFailedAttempts": 2,
      "consultBeforeRiskyActions": true
    },
    "budgets": {
      "maxConsultsPerTask": 2,
      "maxConsultsPerSession": 8,
      "maxCostUsdPerSession": 2.0
    },
    "timeouts": { "fastMs": 8000, "deepMs": 25000 }
  }
}
```

--------------------------------

### Install Claudish using Homebrew

Source: https://github.com/madappgang/claudish/blob/main/README.md

Install Claudish on macOS using the Homebrew package manager.

```bash
brew tap MadAppGang/tap && brew install claudish
```

--------------------------------

### Basic Script Usage

Source: https://github.com/madappgang/claudish/blob/main/docs/advanced/automation.md

Demonstrates setting a default model and executing a task via a shell script.

```bash
#!/bin/bash
set -e

# Ensure model is set
export CLAUDISH_MODEL='minimax/minimax-m2'

# Run task
claudish "add error handling to src/api.ts"
```

--------------------------------

### Vertex AI examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Demonstrates how to use Claudish with Google Cloud's Vertex AI, including API key and project configuration.

```bash
VERTEX_API_KEY=... claudish --model v@gemini-2.5-flash "task"
```

```bash
VERTEX_PROJECT=my-project claudish --model vertex@gemini-2.5-flash "OAuth mode"
```

--------------------------------

### Setting Environment Variables and Running Proxy

Source: https://github.com/madappgang/claudish/blob/main/experiments/tool-replacement-proxy-2026-04/poc/README.md

Set the necessary API keys for Anthropic and OpenRouter, then run the tool-loop proxy with real backends. This pseudocode demonstrates the setup for end-to-end validation.

```sh
export ANTHROPIC_API_KEY=sk-ant-...
export OPENROUTER_API_KEY=sk-or-...
bun run 05-tool-loop-proxy.ts  # with real backends
```

--------------------------------

### Reproducing Stage 1 Tool Swap

Source: https://github.com/madappgang/claudish/blob/main/experiments/tool-replacement-proxy-2026-04/research/05-stage1-tool-swap.md

Commands to set up and run the tool swap experiment. Ensure CLAUDISH_SWAP_ADVISOR is set to enable the swap functionality.

```bash
# from claudish repo
export CLAUDISH_SWAP_ADVISOR=1
export CLAUDISH_SWAP_ADVISOR_LOG=/tmp/advisor-swap.ndjson
export CLAUDISH_SWAP_ADVISOR_DUMP=1  # optional — dumps full request bodies
bun run packages/cli/src/index.ts --monitor
# then in Claude Code:
/advisor opus
# then send any prompt asking for design advice
```

--------------------------------

### Install Claudish Globally

Source: https://github.com/madappgang/claudish/blob/main/docs/getting-started/quick-start.md

Install the package globally using npm or Bun for direct command access.

```bash
npm install -g claudish
```

```bash
bun install -g claudish
```

--------------------------------

### Install and Configure Claudish

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

Install the package globally and set the necessary environment variables for API authentication.

```bash
npm install -g claudish
```

```bash
# OpenRouter (100+ models)
export OPENROUTER_API_KEY='sk-or-v1-...'

# OR Gemini direct
export GEMINI_API_KEY='...'

# OR Vertex AI (Express mode)
export VERTEX_API_KEY='...'

# OR Vertex AI (OAuth mode - uses gcloud ADC)
export VERTEX_PROJECT='your-gcp-project-id'
```

```bash
export ANTHROPIC_API_KEY='sk-ant-api03-placeholder'
```

--------------------------------

### Budget Maximizer: MiniMax and OllamaCloud

Source: https://github.com/madappgang/claudish/blob/main/docs/models/model-mapping.md

Use these commands to select the cheapest working models. MiniMax is used directly, while OllamaCloud models are auto-detected.

```bash
claudish --model mm@MiniMax-M2 "prompt"        # MiniMax direct
```

```bash
claudish --model llama-3.1-8b "prompt"          # OllamaCloud (auto-detected)
```

--------------------------------

### Start Claudish Interactive Session

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/interactive-mode.md

Run this command to start an interactive session with the Claudish model selector.

```bash
claudish
```

--------------------------------

### Select Appropriate Models

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/skills/claudish-usage/SKILL.md

Avoid using the default model. Explicitly choose the most appropriate model for your task to optimize performance and cost.

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

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

--------------------------------

### Install Claudish using curl

Source: https://github.com/madappgang/claudish/blob/main/README.md

This command installs Claudish using a shell script for Linux and macOS environments.

```bash
curl -fsSL https://raw.githubusercontent.com/MadAppGang/claudish/main/install.sh | bash
```

--------------------------------

### UI Implementation with Qwen Vision

Source: https://github.com/madappgang/claudish/blob/main/AI_AGENT_GUIDE.md

Employ vision models like Qwen Vision for UI implementation tasks from designs.

```bash
# Vision model for visual tasks
claudish --model qwen/qwen3-vl-235b-a22b-instruct "implement dashboard from design"
```

--------------------------------

### Claudish CLI: Model Flag Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example of using the --model flag to specify the OpenRouter model for Claudish.

```bash
claudish --model x-ai/grok-code-fast-1 "fix null pointer error in user.ts"
```

--------------------------------

### Using MCP Tools from Claude Code

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Illustrates how Claude Code interacts with MCP tools based on user prompts. Shows examples for running prompts, listing models, and comparing models.

```text
User: "Use Grok to review this code"
Claude: [calls run_prompt tool with model="x-ai/grok-code-fast-1"]

User: "What models support vision?"
Claude: [calls search_models tool with query="vision"]

User: "Compare how GPT-5 and Gemini explain this concept"
Claude: [calls compare_models tool with models=["openai/gpt-5.3", "google/gemini-3-pro-preview"]]
```

--------------------------------

### Start Claudish with a Specific Model

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/interactive-mode.md

Use this command to bypass the model selector and start an interactive session with a specified model.

```bash
claudish --model x-ai/grok-code-fast-1
```

--------------------------------

### Build, Lint, Format, and Type Check

Source: https://github.com/madappgang/claudish/blob/main/README.md

Essential commands for building the project, performing code linting, formatting, and type checking.

```bash
# Build
bun run build

# Lint
bun run lint

# Format
bun run format

# Type check
bun run typecheck
```

--------------------------------

### Run Claudish without installing

Source: https://github.com/madappgang/claudish/blob/main/README.md

Execute the latest version of Claudish directly using npx or bunx without a local installation.

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

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

--------------------------------

### Start Claudish with a Custom OpenRouter Model

Source: https://github.com/madappgang/claudish/blob/main/docs/usage/interactive-mode.md

Use this command to start an interactive session with a custom model from OpenRouter, bypassing the selector.

```bash
claudish --model mistralai/mistral-large-2411
```

--------------------------------

### Listing Available Models

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/skills/claudish-usage/SKILL.md

Use this command to see all available models or search for specific ones.

```bash
claudish --models
```

--------------------------------

### Claudish CLI: List Models Flag Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example of using the --list-models flag to display available models in JSON format.

```bash
claudish --list-models --json
```

--------------------------------

### Running Claudish with File-Based Instructions

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/skills/claudish-usage/SKILL.md

Use file-based instructions to avoid context window pollution and manage complex prompts.

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

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

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

--------------------------------

### Claudish CLI: Stdin Flag Example

Source: https://github.com/madappgang/claudish/blob/main/packages/cli/AI_AGENT_GUIDE.md

Example of using the --stdin flag to read prompts from standard input, piped from a file.

```bash
cat task.md | claudish --stdin --model grok
```

--------------------------------

### Verify Model Wiring with Probe

Source: https://github.com/madappgang/claudish/blob/main/CLAUDE.md

Use the --probe command to inspect the full adapter composition, including transport, format adapter, model translator, and stream format overrides.

```bash
claudish --probe minimax-m2.5
# Shows: transport, format adapter, model translator, stream format, overrides
```

--------------------------------

### Claudish CLI Model Routing Examples

Source: https://github.com/madappgang/claudish/blob/main/README.md

Examples of using the Claudish CLI to explicitly route requests to specific providers and models. Concurrency can be specified after a colon.

```bash
claudish --model google@gemini-2.0-flash "quick task"
```

```bash
claudish --model openrouter@deepseek/deepseek-r1 "analysis"
```

```bash
claudish --model oai@gpt-4o "implement feature"
```

```bash
claudish --model ollama@llama3.2:3 "code review"  # 3 concurrent requests
```