claudish 2.0.0 → 2.2.0

package/README.md

@@ -19,7 +19,8 @@
 - ✅ **Parallel runs** - Each instance gets isolated proxy
 - ✅ **Autonomous mode** - Bypass all prompts with flags
 - ✅ **Context inheritance** - Runs in current directory with same `.claude` settings
-- ✅ **Multiple models** - 5 prioritized OpenRouter models
+- ✅ **Multiple models** - 10+ prioritized OpenRouter models
+- ✅ **Agent support** - Use Claude Code agents in headless mode with `--agent`
 
 ## Installation
 
@@ -214,7 +215,10 @@ claudish [OPTIONS] <claude-args...>
 | `-d, --debug` | Enable debug logging to file | `false` |
 | `--no-auto-approve` | Disable auto-approve (require prompts) | Auto-approve **enabled** |
 | `--dangerous` | Pass `--dangerouslyDisableSandbox` | `false` |
-| `--list-models` | List available models | - |
+| `--agent <agent>` | Use specific agent (e.g., `frontend:developer`) | - |
+| `--list-models` | List available OpenRouter models | - |
+| `--list-agents` | List available agents in current project | - |
+| `--force-update` | Force refresh model cache | - |
 | `--init` | Install Claudish skill in current project | - |
 | `--help-ai` | Show AI agent usage guide | - |
 | `-h, --help` | Show help message | - |
@@ -263,6 +267,28 @@ List models anytime with:
 claudish --list-models
 ```
 
+## Agent Support (NEW in v2.1.0)
+
+Run specialized agents in headless mode with direct agent selection:
+
+```bash
+# Use frontend developer agent
+claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "create a React button component"
+
+# Use API architect agent
+claudish --model openai/gpt-5-codex --agent api-architect "design REST API for user management"
+
+# Discover available agents in your project
+claudish --list-agents
+```
+
+**Agent Features:**
+
+- ✅ **Direct agent selection** - No need to ask Claude to use an agent
+- ✅ **Automatic prefixing** - Adds `@agent-` automatically (`frontend:developer` → `@agent-frontend:developer`)
+- ✅ **Project-specific agents** - Works with any agents installed in `.claude/agents/`
+- ✅ **Agent discovery** - List all available agents with `--list-agents`
+
 ## Status Line Display
 
 Claudish automatically shows critical information in the Claude Code status bar - **no setup required!**

package/dist/index.js

@@ -186,7 +186,14 @@ async function runClaudeWithProxy(config, proxyUrl) {
     if (config.jsonOutput) {
       claudeArgs.push("--output-format", "json");
     }
-    claudeArgs.push(...config.claudeArgs);
+    if (config.agent && config.claudeArgs.length > 0) {
+      const modifiedArgs = [...config.claudeArgs];
+      const agentId = config.agent.startsWith("@agent-") ? config.agent : `@agent-${config.agent}`;
+      modifiedArgs[0] = `Use the ${agentId} agent to: ${modifiedArgs[0]}`;
+      claudeArgs.push(...modifiedArgs);
+    } else {
+      claudeArgs.push(...config.claudeArgs);
+    }
   }
   const env = {
     ...process.env,
@@ -331,7 +338,7 @@ function getAvailableModels() {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync, copyFileSync } from "node:fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, existsSync as existsSync2, mkdirSync, copyFileSync } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { dirname as dirname2, join as join3 } from "node:path";
 var __filename3 = fileURLToPath2(import.meta.url);
@@ -626,7 +633,7 @@ async function updateModelsFromOpenRouter() {
       source: "https://openrouter.ai/models?categories=programming&fmt=cards&order=top-weekly",
       models: recommendations
     };
-    writeFileSync2(MODELS_JSON_PATH, JSON.stringify(updatedData, null, 2), "utf-8");
+    writeFileSync3(MODELS_JSON_PATH, JSON.stringify(updatedData, null, 2), "utf-8");
     console.error(`✅ Updated ${recommendations.length} models (last updated: ${updatedData.lastUpdated})`);
   } catch (error) {
     console.error(`❌ Failed to update models: ${error instanceof Error ? error.message : String(error)}`);
@@ -684,6 +691,10 @@ OPTIONS:
   --help-ai                Show AI agent usage guide (file-based patterns, sub-agents)
   --init                   Install Claudish skill in current project (.claude/skills/)
 
+CUSTOM MODELS:
+  Claudish accepts ANY valid OpenRouter model ID, even if not in --list-models
+  Example: claudish --model your_provider/custom-model-123 "task"
+
 MODES:
   • Interactive mode (default): Shows model selector, starts persistent session
   • Single-shot mode: Runs one task in headless mode and exits (requires --model)
@@ -1072,7 +1083,7 @@ async function selectModelInteractively() {
 }
 
 // src/logger.ts
-import { writeFileSync as writeFileSync3, appendFile, existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
+import { writeFileSync as writeFileSync4, appendFile, existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
 import { join as join4 } from "path";
 var logFilePath = null;
 var logLevel = "info";
@@ -1103,7 +1114,7 @@ function scheduleFlush() {
       flushTimer = null;
     }
     if (logFilePath && logBuffer.length > 0) {
-      writeFileSync3(logFilePath, logBuffer.join(""), { flag: "a" });
+      writeFileSync4(logFilePath, logBuffer.join(""), { flag: "a" });
       logBuffer = [];
     }
   });
@@ -1124,7 +1135,7 @@ function initLogger(debugMode, level = "info") {
   }
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-").split("T").join("_").slice(0, -5);
   logFilePath = join4(logsDir, `claudish_${timestamp}.log`);
-  writeFileSync3(logFilePath, `Claudish Debug Log - ${new Date().toISOString()}
+  writeFileSync4(logFilePath, `Claudish Debug Log - ${new Date().toISOString()}
 Log Level: ${level}
 ${"=".repeat(80)}
 
@@ -3359,7 +3370,7 @@ var serve = (options, listeningListener) => {
 };
 
 // src/proxy-server.ts
-import { writeFileSync as writeFileSync4 } from "node:fs";
+import { writeFileSync as writeFileSync5 } from "node:fs";
 
 // src/transform.ts
 function removeUriFormat(schema) {
@@ -4147,7 +4158,7 @@ data: ${JSON.stringify(data)}
                 total_tokens: cumulativeInputTokens + cumulativeOutputTokens,
                 updated_at: Date.now()
               };
-              writeFileSync4(tokenFilePath, JSON.stringify(tokenData), "utf-8");
+              writeFileSync5(tokenFilePath, JSON.stringify(tokenData), "utf-8");
             } catch (error) {
               if (isLoggingEnabled()) {
                 log(`[Proxy] Failed to write token file: ${error}`);

package/package.json

@@ -1,12 +1,29 @@
 {
   "name": "claudish",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "CLI tool to run Claude Code with any OpenRouter model (Grok, GPT-5, MiniMax, etc.) via local Anthropic API-compatible proxy",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
     "claudish": "dist/index.js"
   },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "dev:grok": "bun run src/index.ts --interactive --model x-ai/grok-code-fast-1",
+    "dev:grok:debug": "bun run src/index.ts --interactive --debug --log-level info --model x-ai/grok-code-fast-1",
+    "dev:info": "bun run src/index.ts --interactive --monitor",
+    "extract-models": "bun run scripts/extract-models.ts",
+    "build": "bun run extract-models && bun build src/index.ts --outdir dist --target node && chmod +x dist/index.js",
+    "link": "npm link",
+    "unlink": "npm unlink -g claudish",
+    "install-global": "bun run build && npm link",
+    "kill-all": "pkill -f 'bun.*claudish' || pkill -f 'claude.*claudish-settings' || echo 'No claudish processes found'",
+    "test": "bun test ./tests/comprehensive-model-test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "postinstall": "node scripts/postinstall.cjs"
+  },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
     "hono": "^4.10.6"
@@ -37,22 +54,5 @@
     "ai"
   ],
   "author": "Jack Rudenko <i@madappgang.com>",
-  "license": "MIT",
-  "scripts": {
-    "dev": "bun run src/index.ts",
-    "dev:grok": "bun run src/index.ts --interactive --model x-ai/grok-code-fast-1",
-    "dev:grok:debug": "bun run src/index.ts --interactive --debug --log-level info --model x-ai/grok-code-fast-1",
-    "dev:info": "bun run src/index.ts --interactive --monitor",
-    "extract-models": "bun run scripts/extract-models.ts",
-    "build": "bun run extract-models && bun build src/index.ts --outdir dist --target node && chmod +x dist/index.js",
-    "link": "npm link",
-    "unlink": "npm unlink -g claudish",
-    "install-global": "bun run build && npm link",
-    "kill-all": "pkill -f 'bun.*claudish' || pkill -f 'claude.*claudish-settings' || echo 'No claudish processes found'",
-    "test": "bun test ./tests/comprehensive-model-test.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
-    "format": "biome format --write .",
-    "postinstall": "node scripts/postinstall.cjs"
-  }
-}
+  "license": "MIT"
+}

package/recommended-models.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.1.5",
-  "lastUpdated": "2025-11-19",
+  "version": "2.1.0",
+  "lastUpdated": "2025-11-20",
   "source": "https://openrouter.ai/models?categories=programming&fmt=cards&order=top-weekly",
   "models": [
     {
@@ -24,13 +24,55 @@
       "isModerated": false,
       "recommended": true
     },
+    {
+      "id": "openai/gpt-5.1-codex",
+      "name": "OpenAI: GPT-5.1-Codex",
+      "description": "GPT-5.1-Codex is a specialized version of GPT-5.1 optimized for software engineering and coding workflows. It is designed for both interactive development sessions and long, independent execution of complex engineering tasks. The model supports building projects from scratch, feature development, debugging, large-scale refactoring, and code review. Compared to GPT-5.1, Codex is more steerable, adheres closely to developer instructions, and produces cleaner, higher-quality code outputs. Reasoning effort can be adjusted with the `reasoning.effort` parameter. Read the [docs here](https://openrouter.ai/docs/use-cases/reasoning-tokens#reasoning-effort-level)\n\nCodex integrates into developer environments including the CLI, IDE extensions, GitHub, and cloud tasks. It adapts reasoning effort dynamically—providing fast responses for small tasks while sustaining extended multi-hour runs for large projects. The model is trained to perform structured code reviews, catching critical flaws by reasoning over dependencies and validating behavior against tests. It also supports multimodal inputs such as images or screenshots for UI development and integrates tool use for search, dependency installation, and environment setup. Codex is intended specifically for agentic coding applications.",
+      "provider": "Openai",
+      "category": "vision",
+      "priority": 2,
+      "pricing": {
+        "input": "$1.25/1M",
+        "output": "$10.00/1M",
+        "average": "$5.63/1M"
+      },
+      "context": "400K",
+      "maxOutputTokens": 128000,
+      "modality": "text+image->text",
+      "supportsTools": true,
+      "supportsReasoning": true,
+      "supportsVision": true,
+      "isModerated": true,
+      "recommended": true
+    },
+    {
+      "id": "moonshotai/kimi-k2-thinking",
+      "name": "MoonshotAI: Kimi K2 Thinking",
+      "description": "Kimi K2 Thinking is Moonshot AI’s most advanced open reasoning model to date, extending the K2 series into agentic, long-horizon reasoning. Built on the trillion-parameter Mixture-of-Experts (MoE) architecture introduced in Kimi K2, it activates 32 billion parameters per forward pass and supports 256 k-token context windows. The model is optimized for persistent step-by-step thought, dynamic tool invocation, and complex reasoning workflows that span hundreds of turns. It interleaves step-by-step reasoning with tool use, enabling autonomous research, coding, and writing that can persist for hundreds of sequential actions without drift.\n\nIt sets new open-source benchmarks on HLE, BrowseComp, SWE-Multilingual, and LiveCodeBench, while maintaining stable multi-agent behavior through 200–300 tool calls. Built on a large-scale MoE architecture with MuonClip optimization, it combines strong reasoning depth with high inference efficiency for demanding agentic and analytical tasks.",
+      "provider": "Moonshotai",
+      "category": "reasoning",
+      "priority": 3,
+      "pricing": {
+        "input": "$0.50/1M",
+        "output": "$2.50/1M",
+        "average": "$1.50/1M"
+      },
+      "context": "262K",
+      "maxOutputTokens": 262144,
+      "modality": "text->text",
+      "supportsTools": true,
+      "supportsReasoning": true,
+      "supportsVision": false,
+      "isModerated": false,
+      "recommended": true
+    },
     {
       "id": "google/gemini-2.5-flash",
       "name": "Google: Gemini 2.5 Flash",
       "description": "Gemini 2.5 Flash is Google's state-of-the-art workhorse model, specifically designed for advanced reasoning, coding, mathematics, and scientific tasks. It includes built-in \"thinking\" capabilities, enabling it to provide responses with greater accuracy and nuanced context handling. \n\nAdditionally, Gemini 2.5 Flash is configurable through the \"max tokens for reasoning\" parameter, as described in the documentation (https://openrouter.ai/docs/use-cases/reasoning-tokens#max-tokens-for-reasoning).",
       "provider": "Google",
       "category": "reasoning",
-      "priority": 2,
+      "priority": 4,
       "pricing": {
         "input": "$0.30/1M",
         "output": "$2.50/1M",
@@ -51,7 +93,7 @@
       "description": "MiniMax-M2 is a compact, high-efficiency large language model optimized for end-to-end coding and agentic workflows. With 10 billion activated parameters (230 billion total), it delivers near-frontier intelligence across general reasoning, tool use, and multi-step task execution while maintaining low latency and deployment efficiency.\n\nThe model excels in code generation, multi-file editing, compile-run-fix loops, and test-validated repair, showing strong results on SWE-Bench Verified, Multi-SWE-Bench, and Terminal-Bench. It also performs competitively in agentic evaluations such as BrowseComp and GAIA, effectively handling long-horizon planning, retrieval, and recovery from execution errors.\n\nBenchmarked by [Artificial Analysis](https://artificialanalysis.ai/models/minimax-m2), MiniMax-M2 ranks among the top open-source models for composite intelligence, spanning mathematics, science, and instruction-following. Its small activation footprint enables fast inference, high concurrency, and improved unit economics, making it well-suited for large-scale agents, developer assistants, and reasoning-driven applications that require responsiveness and cost efficiency.\n\nTo avoid degrading this model's performance, MiniMax highly recommends preserving reasoning between turns. Learn more about using reasoning_details to pass back reasoning in our [docs](https://openrouter.ai/docs/use-cases/reasoning-tokens#preserving-reasoning-blocks).",
       "provider": "Minimax",
       "category": "reasoning",
-      "priority": 3,
+      "priority": 5,
       "pricing": {
         "input": "$0.26/1M",
         "output": "$1.02/1M",
@@ -72,7 +114,7 @@
       "description": "Compared with GLM-4.5, this generation brings several key improvements:\n\nLonger context window: The context window has been expanded from 128K to 200K tokens, enabling the model to handle more complex agentic tasks.\nSuperior coding performance: The model achieves higher scores on code benchmarks and demonstrates better real-world performance in applications such as Claude Code、Cline、Roo Code and Kilo Code, including improvements in generating visually polished front-end pages.\nAdvanced reasoning: GLM-4.6 shows a clear improvement in reasoning performance and supports tool use during inference, leading to stronger overall capability.\nMore capable agents: GLM-4.6 exhibits stronger performance in tool using and search-based agents, and integrates more effectively within agent frameworks.\nRefined writing: Better aligns with human preferences in style and readability, and performs more naturally in role-playing scenarios.",
       "provider": "Z-ai",
       "category": "reasoning",
-      "priority": 4,
+      "priority": 6,
       "pricing": {
         "input": "$0.40/1M",
         "output": "$1.75/1M",
@@ -93,7 +135,7 @@
       "description": "GPT-5 is OpenAI’s most advanced model, offering major improvements in reasoning, code quality, and user experience. It is optimized for complex tasks that require step-by-step reasoning, instruction following, and accuracy in high-stakes use cases. It supports test-time routing features and advanced prompt understanding, including user-specified intent like \"think hard about this.\" Improvements include reductions in hallucination, sycophancy, and better performance in coding, writing, and health-related tasks.",
       "provider": "Openai",
       "category": "reasoning",
-      "priority": 5,
+      "priority": 7,
       "pricing": {
         "input": "$1.25/1M",
         "output": "$10.00/1M",
@@ -108,13 +150,34 @@
       "isModerated": true,
       "recommended": true
     },
+    {
+      "id": "google/gemini-3-pro-preview",
+      "name": "Google: Gemini 3 Pro Preview",
+      "description": "Gemini 3 Pro is Google’s flagship frontier model for high-precision multimodal reasoning, combining strong performance across text, image, video, audio, and code with a 1M-token context window. Reasoning Details must be preserved when using multi-turn tool calling, see our docs here: https://openrouter.ai/docs/use-cases/reasoning-tokens#preserving-reasoning-blocks. It delivers state-of-the-art benchmark results in general reasoning, STEM problem solving, factual QA, and multimodal understanding, including leading scores on LMArena, GPQA Diamond, MathArena Apex, MMMU-Pro, and Video-MMMU. Interactions emphasize depth and interpretability: the model is designed to infer intent with minimal prompting and produce direct, insight-focused responses.\n\nBuilt for advanced development and agentic workflows, Gemini 3 Pro provides robust tool-calling, long-horizon planning stability, and strong zero-shot generation for complex UI, visualization, and coding tasks. It excels at agentic coding (SWE-Bench Verified, Terminal-Bench 2.0), multimodal analysis, and structured long-form tasks such as research synthesis, planning, and interactive learning experiences. Suitable applications include autonomous agents, coding assistants, multimodal analytics, scientific reasoning, and high-context information processing.",
+      "provider": "Google",
+      "category": "vision",
+      "priority": 8,
+      "pricing": {
+        "input": "$2.00/1M",
+        "output": "$12.00/1M",
+        "average": "$7.00/1M"
+      },
+      "context": "1048K",
+      "maxOutputTokens": 65536,
+      "modality": "text+image->text",
+      "supportsTools": true,
+      "supportsReasoning": true,
+      "supportsVision": true,
+      "isModerated": false,
+      "recommended": true
+    },
     {
       "id": "qwen/qwen3-vl-235b-a22b-instruct",
       "name": "Qwen: Qwen3 VL 235B A22B Instruct",
       "description": "Qwen3-VL-235B-A22B Instruct is an open-weight multimodal model that unifies strong text generation with visual understanding across images and video. The Instruct model targets general vision-language use (VQA, document parsing, chart/table extraction, multilingual OCR). The series emphasizes robust perception (recognition of diverse real-world and synthetic categories), spatial understanding (2D/3D grounding), and long-form visual comprehension, with competitive results on public multimodal benchmarks for both perception and reasoning.\n\nBeyond analysis, Qwen3-VL supports agentic interaction and tool use: it can follow complex instructions over multi-image, multi-turn dialogues; align text to video timelines for precise temporal queries; and operate GUI elements for automation tasks. The models also enable visual coding workflows—turning sketches or mockups into code and assisting with UI debugging—while maintaining strong text-only performance comparable to the flagship Qwen3 language models. This makes Qwen3-VL suitable for production scenarios spanning document AI, multilingual OCR, software/UI assistance, spatial/embodied tasks, and research on vision-language agents.",
       "provider": "Qwen",
       "category": "vision",
-      "priority": 6,
+      "priority": 9,
       "pricing": {
         "input": "$0.21/1M",
         "output": "$1.90/1M",
@@ -135,7 +198,7 @@
       "description": "openrouter/polaris-alpha (metadata pending - not yet available in API)",
       "provider": "Openrouter",
       "category": "programming",
-      "priority": 7,
+      "priority": 10,
       "pricing": {
         "input": "N/A",
         "output": "N/A",

package/skills/claudish-usage/SKILL.md

@@ -282,6 +282,54 @@ claudish --list-models
 claudish --list-models --force-update
 ```
 
+## NEW: Direct Agent Selection (v2.1.0)
+
+**Use `--agent` flag to invoke agents directly without the file-based pattern:**
+
+```bash
+# Use specific agent (prepends @agent- automatically)
+claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "implement React component"
+
+# Claude receives: "Use the @agent-frontend:developer agent to: implement React component"
+
+# List available agents in project
+claudish --list-agents
+```
+
+**When to use `--agent` vs file-based pattern:**
+
+**Use `--agent` when:**
+- Single, simple task that needs agent specialization
+- Direct conversation with one agent
+- Testing agent behavior
+- CLI convenience
+
+**Use file-based pattern when:**
+- Complex multi-step workflows
+- Multiple agents needed
+- Large codebases
+- Production tasks requiring review
+- Need isolation from main conversation
+
+**Example comparisons:**
+
+**Simple task (use `--agent`):**
+```bash
+claudish --model x-ai/grok-code-fast-1 --agent frontend:developer "create button component"
+```
+
+**Complex task (use file-based):**
+```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
+```
+
 ## Best Practice: File-Based Sub-Agent Pattern
 
 ### ⚠️ CRITICAL: Don't Run Claudish Directly from Main Conversation
@@ -938,6 +986,110 @@ const { stdout } = await Bash("claudish --list-models --json");
 const models = JSON.parse(stdout).models.map(m => m.id);
 ```
 
+### ✅ Do Accept Custom Models From Users
+
+**Problem:** User provides a custom model ID that's not in --list-models
+
+**Wrong (rejecting custom models):**
+```typescript
+const availableModels = ["x-ai/grok-code-fast-1", "openai/gpt-5"];
+const userModel = "custom/provider/model-123";
+
+if (!availableModels.includes(userModel)) {
+  throw new Error("Model not in my shortlist"); // ❌ DON'T DO THIS
+}
+```
+
+**Right (accept any valid model ID):**
+```typescript
+// Claudish accepts ANY valid OpenRouter model ID, even if not in --list-models
+const userModel = "custom/provider/model-123";
+
+// Validate it's a non-empty string with provider format
+if (!userModel.includes("/")) {
+  console.warn("Model should be in format: provider/model-name");
+}
+
+// Use it directly - Claudish will validate with OpenRouter
+await Bash(`claudish --model ${userModel} "task"`);
+```
+
+**Why:** Users may have access to:
+- Beta/experimental models
+- Private/custom fine-tuned models
+- Newly released models not yet in rankings
+- Regional/enterprise models
+- Cost-saving alternatives
+
+**Always accept user-provided model IDs** unless they're clearly invalid (empty, wrong format).
+
+### ✅ Do Handle User-Preferred Models
+
+**Scenario:** User says "use my custom model X" and expects it to be remembered
+
+**Solution 1: Environment Variable (Recommended)**
+```typescript
+// Set for the session
+process.env.CLAUDISH_MODEL = userPreferredModel;
+
+// Or set permanently in user's shell profile
+await Bash(`echo 'export CLAUDISH_MODEL="${userPreferredModel}"' >> ~/.zshrc`);
+```
+
+**Solution 2: Session Cache**
+```typescript
+// Store in a temporary session file
+const sessionFile = "/tmp/claudish-user-preferences.json";
+const prefs = {
+  preferredModel: userPreferredModel,
+  lastUsed: new Date().toISOString()
+};
+await Write({ file_path: sessionFile, content: JSON.stringify(prefs, null, 2) });
+
+// Load in subsequent commands
+const { stdout } = await Read({ file_path: sessionFile });
+const prefs = JSON.parse(stdout);
+const model = prefs.preferredModel || defaultModel;
+```
+
+**Solution 3: Prompt Once, Remember for Session**
+```typescript
+// In a multi-step workflow, ask once
+if (!process.env.CLAUDISH_MODEL) {
+  const { stdout } = await Bash("claudish --list-models --json");
+  const models = JSON.parse(stdout).models;
+
+  const response = await AskUserQuestion({
+    question: "Select model (or enter custom model ID):",
+    options: models.map((m, i) => ({ label: m.name, value: m.id })).concat([
+      { label: "Enter custom model...", value: "custom" }
+    ])
+  });
+
+  if (response === "custom") {
+    const customModel = await AskUserQuestion({
+      question: "Enter OpenRouter model ID (format: provider/model):"
+    });
+    process.env.CLAUDISH_MODEL = customModel;
+  } else {
+    process.env.CLAUDISH_MODEL = response;
+  }
+}
+
+// Use the selected model for all subsequent calls
+const model = process.env.CLAUDISH_MODEL;
+await Bash(`claudish --model ${model} "task 1"`);
+await Bash(`claudish --model ${model} "task 2"`);
+```
+
+**Guidance for Agents:**
+1. ✅ **Accept any model ID** user provides (unless obviously malformed)
+2. ✅ **Don't filter** based on your "shortlist" - let Claudish handle validation
+3. ✅ **Offer to set CLAUDISH_MODEL** environment variable for session persistence
+4. ✅ **Explain** that --list-models shows curated recommendations, not all possibilities
+5. ✅ **Validate format** (should contain "/") but not restrict to known models
+6. ❌ **Never reject** a user's custom model with "not in my shortlist"
+
 ### ❌ Don't Skip Error Handling
 
 **Wrong:**