Skip to content

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.md
index 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 Format
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 39364ab4..7f17664b 100644
--- a/docs/models/choosing-models.md
+++ b/docs/models/choosing-models.md
@@ -46,6 +46,11 @@ claudish --models-top --json
claudish --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 Columns
diff --git a/docs/settings-reference.md b/docs/settings-reference.md
index 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.md
index 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