Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(catalog): document recommendationTier in --models-top --json
Jack Rudenko21d3f59af77a
diff --git a/AI_AGENT_GUIDE.md b/AI_AGENT_GUIDE.mdindex 1d681564..bab8ee49 100644--- a/AI_AGENT_GUIDE.md+++ b/AI_AGENT_GUIDE.md@@ -431,52 +431,75 @@ Claude: [calls compare_models tool with models=["openai/gpt-5.3", "google/gemini### JSON Output (Recommended)```bash-claudish --list-models --json+claudish --models-top --json```-**Output:**+**Output** (abridged; one row shown):```json{- "version": "1.8.0",- "lastUpdated": "2025-11-19",- "source": "https://openrouter.ai/models",+ "contractVersion": 3,+ "generationId": "g-20261016120000000-abcdef12",+ "version": "g-20261016120000000-abcdef12",+ "lastUpdated": "2026-10-16T12:00:00.000Z",+ "generatedAt": "2026-10-16T12:00:00.000Z",+ "recommendationTiers": ["flagship", "cost_efficient", "lightweight", "luxury", "subscription"],"models": [{- "id": "x-ai/grok-code-fast-1",+ "id": "grok-code-fast-1","name": "Grok Code Fast 1","description": "Ultra-fast agentic coding",- "provider": "xAI",- "category": "coding",+ "provider": "x-ai",+ "recommendationTier": "flagship","priority": 1,"pricing": {- "input": "$0.20/1M",- "output": "$1.50/1M",+ "input": "$0.2/1M",+ "output": "$1.5/1M","average": "$0.85/1M"},- "context": "256K",- "supportsTools": true,- "supportsReasoning": true+ "context": "256000"}]}```+`recommendationTier` is one of `flagship`, `cost_efficient`, `lightweight`, `luxury` or+`subscription`; `recommendationTiers` lists the tiers this claudish version knows. `priority` is+the rank within that tier, from 1. A model listed in two tiers is two rows, so dedupe ids+yourself. Only `subscription` rows carry `subscriptions[].command`, the model spec to run.+Prices are `"N/A"` when the catalog has none.++`claudish --list-models --json` prints the full catalog instead; its records carry no+`recommendationTier`.++### Filter with jq++```bash+# Flagship model ids, in rank order+claudish --models-top --json | jq -r '.models | map(select(.recommendationTier == "flagship")) | sort_by(.priority) | .[].id'++# Runnable subscription commands+claudish --models-top --json | jq -r '.models[] | select(.recommendationTier == "subscription") | .subscriptions[]?.command'+```+### Parse in TypeScript```typescript-const { stdout } = await Bash("claudish --list-models --json");+const { stdout } = await Bash("claudish --models-top --json");const data = JSON.parse(stdout);-// Get all model IDs-const modelIds = data.models.map(m => m.id);+// Every recommended model id, once (a model in two tiers is two rows)+const modelIds = [...new Set(data.models.map(m => m.id))];-// Get coding models-const codingModels = data.models.filter(m => m.category === "coding");+// Flagship models, in rank order+const flagshipModels = data.models+ .filter(m => m.recommendationTier === "flagship")+ .sort((a, b) => a.priority - b.priority);-// Get cheapest model-const cheapest = data.models.sort((a, b) =>- parseFloat(a.pricing.average) - parseFloat(b.pricing.average)-)[0];+// Cheapest model by average price ("$0.85/1M"; "N/A" when unpriced)+const price = m => Number.parseFloat(m.pricing.average.replace(/^\$/, ""));+const cheapest = data.models+ .filter(m => !Number.isNaN(price(m)))+ .sort((a, b) => price(a) - price(b))[0];```## JSON Output Formatdiff --git a/CLAUDE.md b/CLAUDE.mdindex 63560378..e70cd0c7 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -74,6 +74,7 @@ negative case: if you are about to type one of those words, stop and use the lef| route candidate | option, hop (before filtering), chain entry | one `(provider, wire id)` pair gathered for a model, BEFORE the credential and availability filters. A candidate is a proposal; a hop is what survived || tier | class, category, rank, level | a provider's routing class: `subscription`, `dynamic-subscription`, `native`, `gateway`, `fallback`. Ordering is by tier first, and only then by vendor and price — except that the two subscription tiers count as one, so a vendor's own dynamic subscription leads another vendor's catalog subscription (`gk@` before `zengo@` for `grok-4.x`) || namespace claim | pattern match, native claim | a dynamic subscription becoming a candidate because its `nativeModelPatterns` match the name. It exists so the availability filter can ASK the account; it is never evidence that the account is served |+| recommendation tier | category, bucket, tier (alone, on a recommendation) | the backend's curated list a model is recommended in: `flagship`, `cost_efficient`, `lightweight`, `luxury`, `subscription`. The projected field is `recommendationTier`; a value claudish does not know is skipped. Bare "tier" is the routing class above |**Providers and routing**diff --git a/docs/models/choosing-models.md b/docs/models/choosing-models.mdindex 39364ab4..7f17664b 100644--- a/docs/models/choosing-models.md+++ b/docs/models/choosing-models.md@@ -46,6 +46,11 @@ claudish --models-top --jsonclaudish --models --json```+In `claudish --models-top --json`, each row's `recommendationTier` names the curated list it+comes from: `flagship`, `cost_efficient`, `lightweight`, `luxury` or `subscription`. A model+listed in two tiers is two rows, and the top-level `recommendationTiers` lists the tiers this+claudish version knows.+---## Understanding the Columnsdiff --git a/docs/settings-reference.md b/docs/settings-reference.mdindex f6f54338..a3c4dcff 100644--- a/docs/settings-reference.md+++ b/docs/settings-reference.md@@ -888,12 +888,13 @@ For local Qwen models, setting `CLAUDISH_QWEN_NO_THINK=1` prepends `/no_think` t|------|---------|---------------------|| `~/.claudish/config.json` | Global settings, profiles, telemetry, routing | Profile/telemetry commands || `~/.claudish/all-models.json` | Full OpenRouter model catalog | Every 2 days; or `--models-refresh` |+| `~/.claudish/recommended-models-cache-v2.json` | Recommended list projection (`--models-top`, MCP `list_models`) | After 24 h; or `--models-refresh` || `~/.claudish/litellm-models-{hash}.json` | LiteLLM model list (one file per unique `LITELLM_BASE_URL`) | On each LiteLLM model list fetch || `~/.claudish/kimi-oauth.json` | Kimi OAuth access + refresh tokens | `claudish --kimi-login` || `.claudish.json` | Local/project config | Profile commands with `--local` || `.env` | Environment variables (auto-loaded at startup) | Manual |-Cache files can be force-refreshed with `claudish --models --models-refresh` or `claudish --models-top --models-refresh`. The `--models-refresh` flag deletes `all-models.json`, `pricing-cache.json`, and all `litellm-models-*.json` files before fetching fresh data.+Cache files can be force-refreshed with `claudish --models --models-refresh` or `claudish --models-top --models-refresh`. The `--models-refresh` flag deletes `all-models.json`, `pricing-cache.json`, `recommended-models-cache-v2.json`, and all `litellm-models-*.json` files before fetching fresh data.---diff --git a/packages/cli/AI_AGENT_GUIDE.md b/packages/cli/AI_AGENT_GUIDE.mdindex 0f566d68..cf132843 100644--- a/packages/cli/AI_AGENT_GUIDE.md+++ b/packages/cli/AI_AGENT_GUIDE.md@@ -437,52 +437,75 @@ Claude: [calls compare_models tool with models=["openai/gpt-5.3", "google/gemini### JSON Output (Recommended)```bash-claudish --models --json+claudish --models-top --json```-**Output:**+**Output** (abridged; one row shown):```json{- "version": "1.8.0",- "lastUpdated": "2025-11-19",- "source": "https://openrouter.ai/models",+ "contractVersion": 3,+ "generationId": "g-20261016120000000-abcdef12",+ "version": "g-20261016120000000-abcdef12",+ "lastUpdated": "2026-10-16T12:00:00.000Z",+ "generatedAt": "2026-10-16T12:00:00.000Z",+ "recommendationTiers": ["flagship", "cost_efficient", "lightweight", "luxury", "subscription"],"models": [{- "id": "x-ai/grok-code-fast-1",+ "id": "grok-code-fast-1","name": "Grok Code Fast 1","description": "Ultra-fast agentic coding",- "provider": "xAI",- "category": "coding",+ "provider": "x-ai",+ "recommendationTier": "flagship","priority": 1,"pricing": {- "input": "$0.20/1M",- "output": "$1.50/1M",+ "input": "$0.2/1M",+ "output": "$1.5/1M","average": "$0.85/1M"},- "context": "256K",- "supportsTools": true,- "supportsReasoning": true+ "context": "256000"}]}```+`recommendationTier` is one of `flagship`, `cost_efficient`, `lightweight`, `luxury` or+`subscription`; `recommendationTiers` lists the tiers this claudish version knows. `priority` is+the rank within that tier, from 1. A model listed in two tiers is two rows, so dedupe ids+yourself. Only `subscription` rows carry `subscriptions[].command`, the model spec to run.+Prices are `"N/A"` when the catalog has none.++`claudish --models --json` prints the full catalog instead; its records carry no+`recommendationTier`.++### Filter with jq++```bash+# Flagship model ids, in rank order+claudish --models-top --json | jq -r '.models | map(select(.recommendationTier == "flagship")) | sort_by(.priority) | .[].id'++# Runnable subscription commands+claudish --models-top --json | jq -r '.models[] | select(.recommendationTier == "subscription") | .subscriptions[]?.command'+```+### Parse in TypeScript```typescript-const { stdout } = await Bash("claudish --models --json");+const { stdout } = await Bash("claudish --models-top --json");const data = JSON.parse(stdout);-// Get all model IDs-const modelIds = data.models.map(m => m.id);+// Every recommended model id, once (a model in two tiers is two rows)+const modelIds = [...new Set(data.models.map(m => m.id))];-// Get coding models-const codingModels = data.models.filter(m => m.category === "coding");+// Flagship models, in rank order+const flagshipModels = data.models+ .filter(m => m.recommendationTier === "flagship")+ .sort((a, b) => a.priority - b.priority);-// Get cheapest model-const cheapest = data.models.sort((a, b) =>- parseFloat(a.pricing.average) - parseFloat(b.pricing.average)-)[0];+// Cheapest model by average price ("$0.85/1M"; "N/A" when unpriced)+const price = m => Number.parseFloat(m.pricing.average.replace(/^\$/, ""));+const cheapest = data.models+ .filter(m => !Number.isNaN(price(m)))+ .sort((a, b) => price(a) - price(b))[0];```## JSON Output Format