@xelauvas/xela-cli 0.2.2 → 0.3.0

package/README.md

@@ -1,27 +1,32 @@
 # Xela CLI
 
-AI coding assistant that works with **any model** — free or paid. Use OpenRouter, Groq, Ollama, DeepSeek, OpenAI, and more. One tool, any brain.
+[![npm](https://img.shields.io/npm/v/@xelauvas/xela-cli)](https://www.npmjs.com/package/@xelauvas/xela-cli)
+[![GitHub stars](https://img.shields.io/github/stars/xelauvas/codeclau?style=social)](https://github.com/xelauvas/codeclau)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Free AI coding assistant for your terminal.** Works with any model — OpenRouter, Groq, Ollama, DeepSeek, OpenAI, and more. Like Cursor/Claude Code, but free and open source.
 
 ```
- ▐▛███▜▌   Xela CLI
-▝▜█████▛▘  AI coding assistant
-  ▘▘ ▝▝    powered by any model
+╲  ╳  ╱   Xela
+╱  ╳  ╲   AI coding assistant
+  XELA    powered by any model
 ```
 
 ## Install
 
-**npm (recommended):**
 ```bash
 npm install -g @xelauvas/xela-cli
 ```
 
-**One-liner:**
+On first run, Xela walks you through setup — pick a provider, paste a key, choose a model. No config files to edit.
+
+**Other install methods:**
+
 ```bash
+# One-liner
 curl -fsSL https://raw.githubusercontent.com/xelauvas/codeclau/main/install.sh | bash
-```
 
-**From source:**
-```bash
+# From source
 git clone https://github.com/xelauvas/codeclau.git /opt/xela
 cd /opt/xela && npm install && npm link
 ```
@@ -29,10 +34,7 @@ cd /opt/xela && npm install && npm link
 ## Quick Start
 
 ```bash
-# First run creates ~/.xela/config — edit it with your API key
-xela
-
-# Interactive mode
+# Interactive setup + launch
 xela
 
 # With a prompt
@@ -41,160 +43,170 @@ xela "fix the login bug in auth.ts"
 # Non-interactive (pipe-friendly)
 xela -p "explain this function"
 
-# Override model on the fly
-xela -m nvidia/nemotron-3-super-120b-a12b:free "review this code"
-```
+# Override model for one session
+xela -m google/gemini-2.5-pro-exp-03-25:free "review this code"
+```
+
+## What It Can Do
+
+- **Edit files** — reads your code, makes changes with your permission
+- **Run commands** — executes shell commands, runs tests, builds projects
+- **Agentic coding** — plans, executes, and iterates on code changes
+- **Multi-file refactoring** — rename, restructure, migrate across your codebase
+- **Web search** — looks up docs, APIs, error messages
+- **MCP support** — extensible via Model Context Protocol servers
+- **Project memory** — run `/init` to create `XELA.md` with project instructions
+- **Auto mode** — let Xela handle permissions automatically for long tasks
+
+## Slash Commands
+
+| Command | Description |
+|---|---|
+| `/init` | Create a `XELA.md` file with project instructions |
+| `/model` | Switch model |
+| `/config` | Open settings |
+| `/help` | Show help |
+| `/clear` | Clear conversation |
+| `/compact` | Compress conversation to save context |
+| `/cost` | Show token usage |
+| `/mcp` | Manage MCP servers |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| `Enter` | Submit prompt |
+| `Escape` | Cancel current request |
+| `Ctrl+C` | Exit |
+| `Tab` | Accept autocomplete |
+| `Shift+Tab` | Toggle auto mode |
+| `Up/Down` | Navigate history |
 
 ## Free Providers
 
-You don't need to pay anything to use Xela. Here are free options:
-
-### OpenRouter (Free Models)
-Sign up at [openrouter.ai](https://openrouter.ai) — no credit card needed.
-
-```bash
-# ~/.xela/config
-XELA_PROVIDER=openrouter
-OPENAI_API_KEY=sk-or-your-key
-OPENAI_MODEL=qwen/qwen3.6-plus-preview:free
-```
+You don't need to pay anything. Here are free options:
 
-Free models available:
-| Model | ID | Context |
-|---|---|---|
-| Qwen 3.6 Plus | `qwen/qwen3.6-plus-preview:free` | 1M |
-| Nemotron 3 Super 120B | `nvidia/nemotron-3-super-120b-a12b:free` | 262K |
-| Step 3.5 Flash | `stepfun/step-3.5-flash:free` | 256K |
-| Nemotron 3 Nano | `nvidia/nemotron-3-nano-30b-a3b:free` | 256K |
+### OpenRouter (recommended)
+Sign up at [openrouter.ai/keys](https://openrouter.ai/keys) — no credit card needed.
 
-### Groq (Free Tier)
-Sign up at [console.groq.com](https://console.groq.com) — blazing fast inference.
+Available free models:
+| Model | ID |
+|---|---|
+| Qwen 3.6 Plus (1M context) | `qwen/qwen3.6-plus-preview:free` |
+| DeepSeek Chat V3 | `deepseek/deepseek-chat-v3-0324:free` |
+| Gemini 2.5 Pro | `google/gemini-2.5-pro-exp-03-25:free` |
+| Llama 4 Maverick | `meta-llama/llama-4-maverick:free` |
+| Nemotron Ultra 253B | `nvidia/llama-3.1-nemotron-ultra-253b:free` |
 
-```bash
-# ~/.xela/config
-XELA_PROVIDER=groq
-OPENAI_API_KEY=gsk_your-key
-OPENAI_MODEL=qwen-qwq-32b
-```
+### Groq (free tier)
+Sign up at [console.groq.com/keys](https://console.groq.com/keys) — blazing fast inference.
 
-### Ollama (Local, Free Forever)
-Install from [ollama.com](https://ollama.com) — runs on your machine.
+### Ollama (local, free forever)
+Install from [ollama.com](https://ollama.com) — runs on your machine, fully private.
 
 ```bash
 ollama pull qwen2.5-coder:7b
-
-# ~/.xela/config
-XELA_PROVIDER=ollama
-OPENAI_API_KEY=ollama
-OPENAI_MODEL=qwen2.5-coder:7b
+# Then pick "ollama" as provider during xela setup
 ```
 
-## Paid Providers
+### Other free tiers
+- **Cerebras** — fast inference, free tier
+- **SambaNova** — free tier available
 
-For better quality and speed:
+## Paid Providers
 
-### OpenRouter (Paid Models)
-```bash
-XELA_PROVIDER=openrouter
-OPENAI_API_KEY=sk-or-your-key
-OPENAI_MODEL=openai/gpt-5.3-codex          # $0.00175/M input
-# OPENAI_MODEL=anthropic/claude-opus-4.6    # $0.005/M input
-# OPENAI_MODEL=google/gemini-3.1-pro-preview # $0.002/M input
-```
+For better quality and higher rate limits:
 
-### DeepSeek
-```bash
-XELA_PROVIDER=deepseek
-OPENAI_API_KEY=sk-your-key
-OPENAI_MODEL=deepseek-chat
-```
-
-### OpenAI Direct
-```bash
-XELA_PROVIDER=openai
-OPENAI_API_KEY=sk-your-key
-OPENAI_MODEL=gpt-4o
-```
+| Provider | Setup |
+|---|---|
+| **DeepSeek** | [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) — very cheap |
+| **OpenAI** | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
+| **OpenRouter** (paid models) | Same key, just pick a paid model |
 
 ## Configuration
 
-Config file: `~/.xela/config` (created on first run)
+Config is stored at `~/.xela/config.json` (created during first-run setup).
 
-```bash
-# ~/.xela/config
-XELA_PROVIDER=openrouter
-OPENAI_API_KEY=sk-or-your-key-here
-OPENAI_MODEL=qwen/qwen3.6-plus-preview:free
-# OPENAI_BASE_URL=  # auto-detected from provider
+```json
+{
+  "provider": "openrouter",
+  "apiKey": "sk-or-v1-...",
+  "model": "qwen/qwen3.6-plus-preview:free",
+  "baseUrl": ""
+}
 ```
 
-### Supported Providers
+### Re-run setup
 
-| Provider | `XELA_PROVIDER` | Key Prefix | Free? |
-|---|---|---|---|
-| OpenRouter | `openrouter` | `sk-or-` | Free models available |
-| Groq | `groq` | `gsk_` | Free tier |
-| Ollama | `ollama` | `ollama` | Free (local) |
-| DeepSeek | `deepseek` | `sk-` | Cheap |
-| OpenAI | `openai` | `sk-` | Paid |
-| Cerebras | `cerebras` | — | Free tier |
-| SambaNova | `sambanova` | — | Free tier |
+```bash
+rm ~/.xela/config.json && xela
+```
 
-### Model Override
+### Change model
 
 ```bash
-# Override for a single session
-xela -m openai/gpt-5.4-pro "architect a microservice"
+# Edit config directly
+nano ~/.xela/config.json
 
-# Or set in config permanently
-nano ~/.xela/config
+# Or override per-session
+xela -m model-id
 ```
 
-## Features
+### Supported Providers
 
-- **Multi-provider** — Switch between any OpenAI-compatible API
-- **Auto-detection** — Detects provider from API key prefix
-- **Free by default** — Works with free models out of the box
-- **Full CLI** — Interactive REPL, non-interactive mode, piping support
-- **Tool use** — File editing, bash commands, web search, and more
-- **Agentic coding** — Plans, executes, and iterates on code changes
-- **MCP support** — Extensible via Model Context Protocol servers
+| Provider | Default Model | Free? |
+|---|---|---|
+| OpenRouter | `qwen/qwen3.6-plus-preview:free` | Free models available |
+| Groq | `qwen-qwq-32b` | Free tier |
+| Ollama | `qwen2.5-coder:7b` | Free (local) |
+| DeepSeek | `deepseek-chat` | Cheap |
+| OpenAI | `gpt-4o` | Paid |
+| Cerebras | `llama-3.3-70b` | Free tier |
+| SambaNova | `Meta-Llama-3.3-70B-Instruct` | Free tier |
 
 ## Self-Hosting Models
 
-For privacy or unlimited usage, run models locally:
+For privacy or unlimited usage, run models locally with Ollama:
 
-### Small Server (16GB RAM, no GPU)
 ```bash
+# Small (16GB RAM, no GPU) — ~10-30 tok/s
 ollama pull qwen2.5-coder:3b
-# ~10-30 tokens/sec on CPU
-```
 
-### GPU Server (24GB+ VRAM)
-```bash
+# GPU (24GB+ VRAM) — ~100 tok/s
 ollama pull qwen2.5-coder:32b
-# 100+ tokens/sec
+
+# Multi-GPU — full power
+ollama pull deepseek-v3.2
 ```
 
-### Multi-GPU Server
+## Project Instructions (XELA.md)
+
+Run `/init` inside any project to generate a `XELA.md` file. This file tells Xela about your project — build commands, architecture, conventions. It's loaded automatically every session.
+
 ```bash
-ollama pull deepseek-v3.2
-# Full power
+cd my-project
+xela
+# then type /init
 ```
 
+Xela also reads `XELA.local.md` for personal project instructions (add it to `.gitignore`).
+
 ## Uninstall
 
 ```bash
-# npm install
+# Remove CLI
 npm uninstall -g @xelauvas/xela-cli
 
-# curl install
-curl -fsSL https://raw.githubusercontent.com/xelauvas/codeclau/main/uninstall.sh | bash
-
-# Config (optional)
+# Remove config (optional)
 rm -rf ~/.xela
 ```
 
+## Links
+
+- **GitHub**: [github.com/xelauvas/codeclau](https://github.com/xelauvas/codeclau)
+- **npm**: [@xelauvas/xela-cli](https://www.npmjs.com/package/@xelauvas/xela-cli)
+- **Issues**: [github.com/xelauvas/codeclau/issues](https://github.com/xelauvas/codeclau/issues)
+
 ## License
 
 MIT

package/bin/xela.js

@@ -165,6 +165,24 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
+// Show star prompt after first few uses
+const STAR_FILE = join(XELA_HOME, '.star-shown');
+const USAGE_FILE = join(XELA_HOME, '.usage-count');
+try {
+  let count = 0;
+  try { count = parseInt(readFileSync(USAGE_FILE, 'utf-8')) || 0; } catch {}
+  count++;
+  writeFileSync(USAGE_FILE, String(count));
+  if (count === 3 && !existsSync(STAR_FILE)) {
+    console.log('');
+    console.log('  \x1b[36m╲  ╳  ╱\x1b[0m  Enjoying Xela? Give it a star!');
+    console.log('  \x1b[36m╱  ╳  ╲\x1b[0m  \x1b[4mhttps://github.com/xelauvas/codeclau\x1b[0m');
+    console.log('  \x1b[36m  XELA \x1b[0m  It helps others discover it too.');
+    console.log('');
+    writeFileSync(STAR_FILE, '1');
+  }
+} catch {}
+
 // Launch node with the TSX loader shim
 try {
   execFileSync(process.execPath, [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelauvas/xela-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Xela — AI coding assistant powered by any model (OpenRouter, Groq, Ollama, DeepSeek, OpenAI)",
   "author": "xelauvas",
   "license": "MIT",
@@ -20,7 +20,7 @@
   ],
   "scripts": {
     "start": "node --import ./src/_shims/register.js ./src/entrypoints/cli.tsx",
-    "postinstall": "echo '\\n  Xela installed! Run: xela\\n  Config: ~/.xela/config\\n'"
+    "postinstall": "echo '\\n  \\x1b[36m╲  ╳  ╱\\x1b[0m  Xela installed!\\n  \\x1b[36m╱  ╳  ╲\\x1b[0m  Run: xela\\n  \\x1b[36m  XELA \\x1b[0m  Star: github.com/xelauvas/codeclau\\n'"
   },
   "dependencies": {
     "@alcalzone/ansi-tokenize": "^0.3.0",

package/src/_shims/openai_adapter.ts

@@ -35,6 +35,7 @@
  *   OPENAI_API_KEY=... OPENAI_BASE_URL=https://api.together.xyz/v1 OPENAI_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo
  */
 import OpenAI from 'openai'
+import { isClaudeModelName } from '../utils/model/providerModels.js'
 
 // Auto-detect provider from API key prefix or base URL
 function detectProvider(): { baseURL?: string; model: string; maxTokens: number } {
@@ -67,6 +68,18 @@ const PROVIDER = detectProvider()
 const MODEL = PROVIDER.model
 const MAX_TOKENS = PROVIDER.maxTokens
 
+/**
+ * Resolve which model to send to the OpenAI-compatible provider.
+ * - Non-Claude names pass through directly (e.g. 'gpt-4o', 'deepseek-chat')
+ * - Claude names/aliases fall back to the provider default
+ * - Null/undefined uses the startup default
+ */
+function resolveModel(paramsModel: string | undefined): string {
+  if (!paramsModel) return MODEL
+  if (isClaudeModelName(paramsModel)) return MODEL
+  return paramsModel
+}
+
 let _openaiClient: OpenAI | null = null
 
 function getOpenAI(): OpenAI {
@@ -188,7 +201,7 @@ function mapStopReason(finishReason: string | null): string {
 async function* createAnthropicStyleStream(params: any, signal?: AbortSignal): AsyncGenerator<any> {
   const openai = getOpenAI()
   // Always use the configured MODEL — internal Claude model names don't exist on OpenAI-compatible providers
-  const model = MODEL
+  const model = resolveModel(params.model)
 
   const openaiMessages: any[] = []
 
@@ -398,7 +411,7 @@ export function createOpenAIBackedAnthropicClient(): any {
       const nonStreamingResult = (async () => {
       const openai = getOpenAI()
       // Always use the configured MODEL
-      const model = MODEL
+      const model = resolveModel(params.model)
 
       const openaiMessages: any[] = []
       if (params.system) {

package/src/commands/model/model.tsx

@@ -14,7 +14,8 @@ import { MODEL_ALIASES } from '../../utils/model/aliases.js';
 import { checkOpus1mAccess, checkSonnet1mAccess } from '../../utils/model/check1mAccess.js';
 import { getDefaultMainLoopModelSetting, isOpus1mMergeEnabled, renderDefaultModelSetting } from '../../utils/model/model.js';
 import { isModelAllowed } from '../../utils/model/modelAllowlist.js';
-import { validateModel } from '../../utils/model/validateModel.js';
+import { validateModel } from '../../utils/model/validateModel.js'
+import { isOpenAIBackend, isClaudeModelName } from '../../utils/model/providerModels.js';
 function ModelPickerWrapper(t0) {
   const $ = _c(17);
   const {
@@ -141,13 +142,30 @@ function SetModelAndClose({
   const model = args === 'default' ? null : args;
   React.useEffect(() => {
     async function handleModelChange(): Promise<void> {
-      if (model && !isModelAllowed(model)) {
+      if (model && !isOpenAIBackend() && !isModelAllowed(model)) {
         onDone(`Model '${model}' is not available. Your organization restricts model selection.`, {
           display: 'system'
         });
         return;
       }
 
+      // Skip validation for default model
+      if (!model) {
+        setModel(null);
+        return;
+      }
+
+      // OpenAI backend: skip all Claude-specific checks, go straight to validation
+      if (isOpenAIBackend()) {
+        const { valid, error: validationError } = await validateModel(model);
+        if (valid) {
+          setModel(model);
+        } else {
+          onDone(validationError || `Model '${model}' not found`, { display: 'system' });
+        }
+        return;
+      }
+
       // @[MODEL LAUNCH]: Update check for 1M access.
       if (model && isOpus1mUnavailable(model)) {
         onDone(`Opus 4.6 with 1M context is not available for your account. Learn more: https://code.claude.com/docs/en/model-config#extended-context-with-1m`, {
@@ -162,12 +180,6 @@ function SetModelAndClose({
         return;
       }
 
-      // Skip validation for default model
-      if (!model) {
-        setModel(null);
-        return;
-      }
-
       // Skip validation for known aliases - they're predefined and should work
       if (isKnownAlias(model)) {
         setModel(model);
@@ -291,6 +303,9 @@ export const call: LocalJSXCommandCall = async (onDone, _context, args) => {
   return <ModelPickerWrapper onDone={onDone} />;
 };
 function renderModelLabel(model: string | null): string {
+  if (isOpenAIBackend() && model && !isClaudeModelName(model)) {
+    return model;
+  }
   const rendered = renderDefaultModelSetting(model ?? getDefaultMainLoopModelSetting());
   return model === null ? `${rendered} (default)` : rendered;
 }

package/src/components/ModelPicker.tsx

@@ -18,6 +18,7 @@ import { Byline } from './design-system/Byline.js';
 import { KeyboardShortcutHint } from './design-system/KeyboardShortcutHint.js';
 import { Pane } from './design-system/Pane.js';
 import { effortLevelToSymbol } from './EffortIndicator.js';
+import { isOpenAIBackend, fetchProviderModels, getOpenAIDefaultModel } from '../utils/model/providerModels.js';
 export type Props = {
   initial: string | null;
   sessionModel?: ModelSetting;
@@ -74,9 +75,38 @@ export function ModelPicker(t0) {
     t3 = $[3];
   }
   const modelOptions = t3;
+
+  const [providerModels, setProviderModels] = useState<Array<{value: string | null, label: string, description: string}>>([]);
+  const [providerLoading, setProviderLoading] = useState(isOpenAIBackend());
+
+  React.useEffect(() => {
+    if (!isOpenAIBackend()) return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const models = await fetchProviderModels();
+        if (cancelled) return;
+        const defaultModel = getOpenAIDefaultModel();
+        const options = [
+          { value: null, label: `Default (${defaultModel})`, description: 'Current default model' },
+          ...models.map(m => ({ value: m.id, label: m.id, description: m.name !== m.id ? m.name : '' })),
+        ];
+        setProviderModels(options);
+      } finally {
+        if (!cancelled) setProviderLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  // When on OpenAI backend and provider models loaded, use them instead of Claude options
+  const effectiveModelOptions = isOpenAIBackend() && providerModels.length > 0
+    ? providerModels
+    : modelOptions;
+
   let t4;
   bb0: {
-    if (initial !== null && !modelOptions.some(opt => opt.value === initial)) {
+    if (initial !== null && !effectiveModelOptions.some(opt => opt.value === initial)) {
       let t5;
       if ($[4] !== initial) {
         t5 = modelDisplayString(initial);
@@ -100,7 +130,7 @@ export function ModelPicker(t0) {
       }
       let t7;
       if ($[9] !== modelOptions || $[10] !== t6) {
-        t7 = [...modelOptions, t6];
+        t7 = [...effectiveModelOptions, t6];
         $[9] = modelOptions;
         $[10] = t6;
         $[11] = t7;
@@ -110,7 +140,7 @@ export function ModelPicker(t0) {
       t4 = t7;
       break bb0;
     }
-    t4 = modelOptions;
+    t4 = effectiveModelOptions;
   }
   const optionsWithInitial = t4;
   let t5;
@@ -265,7 +295,7 @@ export function ModelPicker(t0) {
   } else {
     t15 = $[41];
   }
-  const t16 = headerText ?? "Switch between Claude models. Applies to this session and future Claude Code sessions. For other/previous model names, specify with --model.";
+  const t16 = headerText ?? (providerLoading ? 'Loading models from provider...' : isOpenAIBackend() ? 'Switch between provider models. Select a model or use /model <name> directly.' : "Switch between Claude models. Applies to this session and future Claude Code sessions. For other/previous model names, specify with --model.");
   let t17;
   if ($[42] !== t16) {
     t17 = <Text dimColor={true}>{t16}</Text>;

package/src/utils/model/model.ts

@@ -74,7 +74,8 @@ export function getUserSpecifiedModelSetting(): ModelSetting | undefined {
   }
 
   // Ignore the user-specified model if it's not in the availableModels allowlist.
-  if (specifiedModel && !isModelAllowed(specifiedModel)) {
+  // Skip this check on OpenAI backend — the allowlist is for Claude models only.
+  if (specifiedModel && !process.env.OPENAI_API_KEY && !isModelAllowed(specifiedModel)) {
     return undefined
   }
 
@@ -94,8 +95,12 @@ export function getUserSpecifiedModelSetting(): ModelSetting | undefined {
  * @returns The resolved model name to use
  */
 export function getMainLoopModel(): ModelName {
-  // When using OpenAI backend, return the OpenAI model name directly
+  // When using OpenAI backend, respect user-selected model, fall back to OPENAI_MODEL
   if (process.env.OPENAI_API_KEY) {
+    const model = getUserSpecifiedModelSetting()
+    if (model !== undefined && model !== null) {
+      return model
+    }
     return process.env.OPENAI_MODEL || 'gpt-4o'
   }
   const model = getUserSpecifiedModelSetting()
@@ -160,9 +165,9 @@ export function getRuntimeMainLoopModel(params: {
 }): ModelName {
   const { permissionMode, mainLoopModel, exceeds200kTokens = false } = params
 
-  // When using OpenAI backend, always use the configured model
+  // When using OpenAI backend, use the passed-in model (already resolved by caller)
   if (process.env.OPENAI_API_KEY) {
-    return process.env.OPENAI_MODEL || 'gpt-4o'
+    return mainLoopModel || process.env.OPENAI_MODEL || 'gpt-4o'
   }
 
   // opusplan uses Opus in plan mode without [1m] suffix.

package/src/utils/model/modelOptions.ts

@@ -32,6 +32,7 @@ import {
 } from './model.js'
 import { has1mContext } from '../context.js'
 import { getGlobalConfig } from '../config.js'
+import { isOpenAIBackend, getOpenAIDefaultModel, detectOpenAIProvider } from './providerModels.js'
 
 // @[MODEL LAUNCH]: Update all the available and default model option strings below.
 
@@ -266,6 +267,23 @@ function getOpusPlanOption(): ModelOption {
   }
 }
 
+/**
+ * Build model options from the OpenAI-compatible provider's model list.
+ * Called synchronously with cached data if available, otherwise returns
+ * a minimal default option.
+ */
+function getOpenAIModelOptions(): ModelOption[] {
+  const defaultModel = getOpenAIDefaultModel()
+  const provider = detectOpenAIProvider()
+  const providerLabel = provider === 'unknown' ? 'OpenAI-compatible' : provider.charAt(0).toUpperCase() + provider.slice(1)
+
+  return [{
+    value: null,
+    label: `Default (${defaultModel})`,
+    description: `${providerLabel} default model`,
+  }]
+}
+
 // @[MODEL LAUNCH]: Update the model picker lists below to include/reorder options for the new model.
 // Each user tier (ant, Max/Team Premium, Pro/Team Standard/Enterprise, PAYG 1P, PAYG 3P) has its own list.
 function getModelOptionsBase(fastMode = false): ModelOption[] {
@@ -459,6 +477,9 @@ function getKnownModelOption(model: string): ModelOption | null {
 }
 
 export function getModelOptions(fastMode = false): ModelOption[] {
+  if (isOpenAIBackend()) {
+    return getOpenAIModelOptions()
+  }
   const options = getModelOptionsBase(fastMode)
 
   // Add the custom model from the ANTHROPIC_CUSTOM_MODEL_OPTION env var

package/src/utils/model/providerModels.ts

@@ -0,0 +1,168 @@
+import OpenAI from 'openai'
+import { MODEL_ALIASES } from './aliases.js'
+
+export type ProviderModel = {
+  id: string
+  name: string
+}
+
+export type ProviderName =
+  | 'openai'
+  | 'groq'
+  | 'openrouter'
+  | 'deepseek'
+  | 'mistral'
+  | 'together'
+  | 'ollama'
+  | 'fireworks'
+  | 'moonshot'
+  | 'unknown'
+
+/**
+ * Returns true if the model name is a Claude model name or alias.
+ * These don't exist on OpenAI-compatible providers, so the adapter
+ * should fall back to the provider default.
+ */
+export function isClaudeModelName(model: string): boolean {
+  const lower = model.toLowerCase().trim()
+  if (lower.includes('claude')) return true
+  return (MODEL_ALIASES as readonly string[]).includes(lower)
+}
+
+/**
+ * Detect which OpenAI-compatible provider is configured.
+ */
+export function detectOpenAIProvider(): ProviderName {
+  const key = process.env.OPENAI_API_KEY || ''
+  const baseURL = process.env.OPENAI_BASE_URL || ''
+
+  if (baseURL.includes('groq.com') || key.startsWith('gsk_')) return 'groq'
+  if (baseURL.includes('openrouter.ai') || key.startsWith('sk-or-')) return 'openrouter'
+  if (baseURL.includes('deepseek.com')) return 'deepseek'
+  if (baseURL.includes('mistral.ai')) return 'mistral'
+  if (baseURL.includes('together.xyz')) return 'together'
+  if (baseURL.includes('localhost') || baseURL.includes('127.0.0.1')) return 'ollama'
+  if (baseURL.includes('fireworks.ai')) return 'fireworks'
+  if (baseURL.includes('moonshot.cn') || baseURL.includes('moonshot.ai')) return 'moonshot'
+  if (!baseURL || baseURL.includes('openai.com')) return 'openai'
+  return 'unknown'
+}
+
+const CURATED_MODELS: Record<ProviderName, ProviderModel[]> = {
+  openai: [
+    { id: 'gpt-4o', name: 'GPT-4o' },
+    { id: 'gpt-4o-mini', name: 'GPT-4o Mini' },
+    { id: 'gpt-4.1', name: 'GPT-4.1' },
+    { id: 'gpt-4.1-mini', name: 'GPT-4.1 Mini' },
+    { id: 'o3', name: 'o3' },
+    { id: 'o4-mini', name: 'o4 Mini' },
+  ],
+  groq: [
+    { id: 'llama-3.3-70b-versatile', name: 'Llama 3.3 70B' },
+    { id: 'llama-3.1-8b-instant', name: 'Llama 3.1 8B Instant' },
+    { id: 'gemma2-9b-it', name: 'Gemma 2 9B' },
+    { id: 'mixtral-8x7b-32768', name: 'Mixtral 8x7B' },
+  ],
+  openrouter: [
+    { id: 'google/gemini-2.0-flash-001', name: 'Gemini 2.0 Flash' },
+    { id: 'openai/gpt-4o', name: 'GPT-4o' },
+    { id: 'meta-llama/llama-3.3-70b', name: 'Llama 3.3 70B' },
+  ],
+  deepseek: [
+    { id: 'deepseek-chat', name: 'DeepSeek Chat' },
+    { id: 'deepseek-reasoner', name: 'DeepSeek Reasoner' },
+  ],
+  mistral: [
+    { id: 'mistral-large-latest', name: 'Mistral Large' },
+    { id: 'mistral-small-latest', name: 'Mistral Small' },
+    { id: 'codestral-latest', name: 'Codestral' },
+  ],
+  together: [
+    { id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', name: 'Llama 3.3 70B Turbo' },
+    { id: 'Qwen/Qwen2.5-72B-Instruct-Turbo', name: 'Qwen 2.5 72B Turbo' },
+  ],
+  ollama: [
+    { id: 'llama3.2', name: 'Llama 3.2' },
+    { id: 'qwen2.5-coder', name: 'Qwen 2.5 Coder' },
+    { id: 'deepseek-r1', name: 'DeepSeek R1' },
+    { id: 'mistral', name: 'Mistral' },
+  ],
+  fireworks: [
+    { id: 'accounts/fireworks/models/llama-v3p3-70b-instruct', name: 'Llama 3.3 70B' },
+  ],
+  moonshot: [
+    { id: 'moonshot-v1-32k', name: 'Moonshot V1 32K' },
+    { id: 'moonshot-v1-128k', name: 'Moonshot V1 128K' },
+  ],
+  unknown: [],
+}
+
+export function getCuratedModels(provider: ProviderName): ProviderModel[] {
+  return CURATED_MODELS[provider] ?? []
+}
+
+let cachedModels: ProviderModel[] | null = null
+
+/**
+ * Fetch all available models from the provider via GET /v1/models.
+ * Results are cached in memory for the session.
+ * Returns curated fallback list on failure.
+ */
+export async function fetchProviderModels(): Promise<ProviderModel[]> {
+  if (cachedModels !== null) {
+    return cachedModels
+  }
+
+  const provider = detectOpenAIProvider()
+
+  try {
+    const client = new OpenAI({
+      apiKey: process.env.OPENAI_API_KEY,
+      ...(process.env.OPENAI_BASE_URL ? { baseURL: process.env.OPENAI_BASE_URL } : {}),
+      ...(provider === 'groq' && !process.env.OPENAI_BASE_URL
+        ? { baseURL: 'https://api.groq.com/openai/v1' }
+        : {}),
+      ...(provider === 'openrouter' && !process.env.OPENAI_BASE_URL
+        ? { baseURL: 'https://openrouter.ai/api/v1' }
+        : {}),
+    })
+
+    const response = await client.models.list({}, { timeout: 5000 })
+    const models: ProviderModel[] = []
+
+    for await (const model of response) {
+      models.push({ id: model.id, name: model.id })
+    }
+
+    models.sort((a, b) => a.id.localeCompare(b.id))
+    cachedModels = models
+    return models
+  } catch {
+    const fallback = getCuratedModels(provider)
+    cachedModels = fallback
+    return fallback
+  }
+}
+
+/**
+ * Check if a model ID exists in the cached provider model list.
+ * Returns false if the cache hasn't been populated yet.
+ */
+export function isKnownProviderModel(modelId: string): boolean {
+  if (!cachedModels) return false
+  return cachedModels.some(m => m.id === modelId)
+}
+
+/**
+ * Returns true if the app is using an OpenAI-compatible backend.
+ */
+export function isOpenAIBackend(): boolean {
+  return !!process.env.OPENAI_API_KEY
+}
+
+/**
+ * Get the startup default model for the current OpenAI provider.
+ */
+export function getOpenAIDefaultModel(): string {
+  return process.env.OPENAI_MODEL || 'gpt-4o'
+}

package/src/utils/model/validateModel.ts

@@ -10,6 +10,7 @@ import {
   AuthenticationError,
 } from '@anthropic-ai/sdk'
 import { getModelStrings } from './modelStrings.js'
+import { isOpenAIBackend, isKnownProviderModel, isClaudeModelName } from './providerModels.js'
 
 // Cache valid models to avoid repeated API calls
 const validModelCache = new Map<string, boolean>()
@@ -27,6 +28,24 @@ export async function validateModel(
     return { valid: false, error: 'Model name cannot be empty' }
   }
 
+  // OpenAI-compatible backend: skip Anthropic validation
+  if (isOpenAIBackend()) {
+    // Claude names don't exist on OpenAI providers
+    if (isClaudeModelName(normalizedModel)) {
+      return {
+        valid: false,
+        error: `'${normalizedModel}' is a Claude model name. Use a model name from your provider (e.g. 'gpt-4o', 'deepseek-chat').`,
+      }
+    }
+    // If we already fetched the model list, check against it
+    if (isKnownProviderModel(normalizedModel)) {
+      return { valid: true }
+    }
+    // Otherwise, trust the user — the adapter will try it and the provider
+    // will return an error if it doesn't exist
+    return { valid: true }
+  }
+
   // Check against availableModels allowlist before any API call
   if (!isModelAllowed(normalizedModel)) {
     return {

package/src/_shims/_generated_stubs/_universal_stub.mjs

@@ -1,168 +0,0 @@
-// Universal stub — exports all known names for unresolved modules
-export default {};
-
-// --- Arrays (names ending in S, LIST, TOOLS, etc.) ---
-export const BROWSER_TOOLS = [];
-export const DEFAULT_SESSION_TIMEOUT_MS = [];
-export const RARITY_COLORS = [];
-export const EYES = [];
-export const HATS = [];
-export const RARITIES = [];
-export const RARITY_WEIGHTS = [];
-export const SPECIES = [];
-export const STAT_NAMES = [];
-export const AGENT_PATHS = [];
-export const DEFAULT_GRANT_FLAGS = [];
-export const MEMORY_TYPE_VALUES = [];
-export const SYNC_KEYS = [];
-export const CUSTOMIZATION_SURFACES = [];
-export const FIND_KEYS = [];
-export const OPERATORS = [];
-export const SIMPLE_MOTIONS = [];
-export const TEXT_OBJ_SCOPES = [];
-export const TEXT_OBJ_TYPES = [];
-export const SOURCES = [];
-export const FRAME_INTERVAL_MS = [];
-export const ONE_SHOT_BUILTIN_AGENT_TYPES = [];
-export const REPL_ONLY_TOOLS = [];
-export const SETTING_SOURCES = [];
-export const MDM_SUBPROCESS_TIMEOUT_MS = [];
-
-// --- Functions (is/has/get/set/create/handle...) ---
-export const isBackgroundTask = () => undefined;
-export const isInProcessTeammateTask = () => undefined;
-export const isMcpServerCommandEntry = () => undefined;
-export const isMcpServerNameEntry = () => undefined;
-export const isMcpServerUrlEntry = () => undefined;
-export const isPaneBackend = () => undefined;
-export const isOperatorKey = () => undefined;
-export const isTextObjScopeKey = () => undefined;
-export const isReplModeEnabled = () => undefined;
-export const isSettingSourceEnabled = () => undefined;
-export const getSourceDisplayName = () => undefined;
-export const getSettingSourceName = () => undefined;
-export const getSwarmSocketName = () => undefined;
-export const getSettingSourceDisplayNameLowercase = () => undefined;
-export const getSettingSourceDisplayNameCapitalized = () => undefined;
-export const getEnabledSettingSources = () => undefined;
-export const getMacOSPlistPaths = () => undefined;
-export const getSyntaxTheme = () => undefined;
-export const createClaudeForChromeMcpServer = () => undefined;
-export const createInitialPersistentState = () => undefined;
-export const createInitialVimState = () => undefined;
-export const parseSettingSourcesFlag = () => undefined;
-export const reduceAnsiCodes = () => undefined;
-
-// --- Constants/schemas/values ---
-export const BRIDGE_LOGIN_INSTRUCTION = undefined;
-export const BRIDGE_LOGIN_ERROR = undefined;
-export const axolotl = undefined;
-export const blob = undefined;
-export const cactus = undefined;
-export const capybara = undefined;
-export const cat = undefined;
-export const chonk = undefined;
-export const dragon = undefined;
-export const duck = undefined;
-export const ghost = undefined;
-export const goose = undefined;
-export const mushroom = undefined;
-export const octopus = undefined;
-export const owl = undefined;
-export const penguin = undefined;
-export const rabbit = undefined;
-export const robot = undefined;
-export const snail = undefined;
-export const turtle = undefined;
-export const ElicitRequestSchema = undefined;
-export const ElicitationCompleteNotificationSchema = undefined;
-export const REMOTE_CONTROL_DISCONNECTED_MSG = undefined;
-export const CallToolRequestSchema = undefined;
-export const ListToolsRequestSchema = undefined;
-export const defaultStyle = undefined;
-export const connectResponseSchema = undefined;
-export const CallToolResultSchema = undefined;
-export const ErrorCode = undefined;
-export const ListPromptsResultSchema = undefined;
-export const ListResourcesResultSchema = undefined;
-export const ListRootsRequestSchema = undefined;
-export const ListToolsResultSchema = undefined;
-export const McpError = undefined;
-export const McpJsonConfigSchema = undefined;
-export const McpServerConfigSchema = undefined;
-export const PromptListChangedNotificationSchema = undefined;
-export const ResourceListChangedNotificationSchema = undefined;
-export const ToolListChangedNotificationSchema = undefined;
-export const ConfigScopeSchema = undefined;
-export const PolicyLimitsResponseSchema = undefined;
-export const SettingsSchema = undefined;
-export const RemoteManagedSettingsResponseSchema = undefined;
-export const UserSyncDataSchema = undefined;
-export const TeamMemoryDataSchema = undefined;
-export const TeamMemoryTooManyEntriesSchema = undefined;
-export const HooksSchema = undefined;
-export const appendCappedMessage = undefined;
-export const inputSchema = undefined;
-export const outputSchema = undefined;
-export const gitDiffSchema = undefined;
-export const hunkSchema = undefined;
-export const ReadResourceResultSchema = undefined;
-export const TodoListSchema = undefined;
-export const McpStdioServerConfigSchema = undefined;
-export const DEFAULT_UPLOAD_CONCURRENCY = undefined;
-export const FILE_COUNT_LIMIT = undefined;
-export const OUTPUTS_SUBDIR = undefined;
-export const JSONRPCMessageSchema = undefined;
-export const MAX_VIM_COUNT = undefined;
-export const AGENT_TOOL_NAME = undefined;
-export const LEGACY_AGENT_TOOL_NAME = undefined;
-export const EXIT_PLAN_MODE_V2_TOOL_NAME = undefined;
-export const TEAM_CREATE_TOOL_NAME = undefined;
-export const CLAUDE_FOLDER_PERMISSION_PATTERN = undefined;
-export const FILE_EDIT_TOOL_NAME = undefined;
-export const GLOBAL_CLAUDE_FOLDER_PERMISSION_PATTERN = undefined;
-export const SKILL_TOOL_NAME = undefined;
-export const TEAM_LEAD_NAME = undefined;
-export const TMUX_COMMAND = undefined;
-export const VERIFICATION_AGENT_TYPE = undefined;
-export const TODO_WRITE_TOOL_NAME = undefined;
-export const TASK_CREATE_TOOL_NAME = undefined;
-export const TASK_OUTPUT_TOOL_NAME = undefined;
-export const ENTER_PLAN_MODE_TOOL_NAME = undefined;
-export const NOTEBOOK_EDIT_TOOL_NAME = undefined;
-export const SEND_MESSAGE_TOOL_NAME = undefined;
-export const TASK_GET_TOOL_NAME = undefined;
-export const TASK_LIST_TOOL_NAME = undefined;
-export const TASK_UPDATE_TOOL_NAME = undefined;
-export const ENTER_WORKTREE_TOOL_NAME = undefined;
-export const EXIT_WORKTREE_TOOL_NAME = undefined;
-export const WORKFLOW_TOOL_NAME = undefined;
-export const TEAM_DELETE_TOOL_NAME = undefined;
-export const ContinuousEventPriority = undefined;
-export const DefaultEventPriority = undefined;
-export const DiscreteEventPriority = undefined;
-export const NoEventPriority = undefined;
-export const ConcurrentRoot = undefined;
-export const LegacyRoot = undefined;
-export const REPL_TOOL_NAME = undefined;
-export const EXIT_PLAN_MODE_TOOL_NAME = undefined;
-export const CONFIG_TOOL_NAME = undefined;
-export const FILE_UNEXPECTEDLY_MODIFIED_ERROR = undefined;
-export const TOOL_SEARCH_TOOL_NAME = undefined;
-export const SWARM_SESSION_NAME = undefined;
-export const TEAMMATE_COMMAND_ENV_VAR = undefined;
-export const PLUTIL_ARGS_PREFIX = undefined;
-export const PLUTIL_PATH = undefined;
-export const WINDOWS_REGISTRY_KEY_PATH_HKCU = undefined;
-export const WINDOWS_REGISTRY_KEY_PATH_HKLM = undefined;
-export const WINDOWS_REGISTRY_VALUE_NAME = undefined;
-export const CLAUDE_CODE_SETTINGS_SCHEMA_URL = undefined;
-export const HIDDEN_SESSION_NAME = undefined;
-export const SWARM_VIEW_WINDOW_NAME = undefined;
-export const ColorDiff = undefined;
-export const ColorFile = undefined;
-export const ansiCodesToString = undefined;
-export const diffAnsiCodes = undefined;
-export const styledCharsFromTokens = undefined;
-export const tokenize = undefined;
-export const undoAnsiCodes = undefined;

package/src/_shims/_generated_stubs/text_stub.mjs

@@ -1 +0,0 @@
-export default '';