@killingjacky/claude-code-router 2.1.1 → 2.2.1

package/README.md

@@ -195,12 +195,13 @@ Here is a comprehensive example:
     }
   ],
   "Router": {
-    "default": "deepseek,deepseek-chat",
-    "background": "ollama,qwen2.5-coder:latest",
-    "think": "deepseek,deepseek-reasoner",
-    "longContext": "openrouter,google/gemini-2.5-pro-preview",
-    "longContextThreshold": 60000,
-    "webSearch": "gemini,gemini-2.5-flash"
+    "primary": "deepseek,deepseek-chat",
+    "aliases": {
+      "haiku": "ollama,qwen2.5-coder:latest"
+    },
+    "capabilities": {
+      "webSearch": "gemini,gemini-2.5-flash"
+    }
   }
 }
 ```
@@ -243,7 +244,7 @@ ccr model
 This command provides an interactive interface to:
 
 - View current configuration:
-- See all configured models (default, background, think, longContext, webSearch, image)
+- See all configured primary, alias, and capability models
 - Switch models: Quickly change which model is used for each router type
 - Add new models: Add models to existing providers
 - Create new providers: Set up complete provider configurations including:
@@ -314,6 +315,7 @@ The `activate` command sets the following environment variables:
 
 - `ANTHROPIC_AUTH_TOKEN`: API key from your configuration
 - `ANTHROPIC_BASE_URL`: The local router endpoint (default: `http://127.0.0.1:3456`)
+- `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`: Enables Claude Code's `/model` picker to list every configured CCR provider/model pair
 - `NO_PROXY`: Set to `127.0.0.1` to prevent proxy interference
 - `DISABLE_TELEMETRY`: Disables telemetry
 - `DISABLE_COST_WARNINGS`: Disables cost warnings
@@ -321,6 +323,8 @@ The `activate` command sets the following environment variables:
 
 > **Note**: Make sure the Claude Code Router service is running (`ccr start`) before using the activated environment variables. The environment variables are only valid for the current shell session. To make them persistent, you can add `eval "$(ccr activate)"` to your shell configuration file (e.g., `~/.zshrc` or `~/.bashrc`).
 
+After activation, run `/model` in Claude Code to select a configured model directly. Each entry is shown as `provider, model`; CCR routes it to that exact configured provider and model.
+
 #### Providers
 
 The `Providers` array is where you define the different model providers you want to use. Each provider object requires:
@@ -329,8 +333,18 @@ The `Providers` array is where you define the different model providers you want
 - `api_base_url`: The full API endpoint for chat completions.
 - `api_key`: Your API key for the provider.
 - `models`: A list of model names available from this provider.
+- `models_1m` (optional): A list of models that support a 1-million-token context window. Each entry must also be present in `models`; Claude Code then shows it as an additional `[1M]` option. Entries that are not in `models` are ignored for gateway discovery.
 - `transformer` (optional): Specifies transformers to process requests and responses.
 
+For example, this configuration shows `gpt-5.4` in Claude Code both normally and as `gpt-5.4 [1M]`, while `gpt-5.4-mini` is shown only normally:
+
+```json
+{
+  "models": ["gpt-5.4", "gpt-5.4-mini"],
+  "models_1m": ["gpt-5.4"]
+}
+```
+
 #### Transformers
 
 Transformers allow you to modify the request and response payloads to ensure compatibility with different provider APIs.
@@ -439,15 +453,15 @@ You can also create your own transformers and load them via the `transformers` f
 
 #### Router
 
-The `Router` object defines which model to use for different scenarios:
+The `Router` object uses explicit intent and model capabilities:
 
-- `default`: The default model for general tasks.
-- `background`: A model for background tasks. This can be a smaller, local model to save costs.
-- `think`: A model for reasoning-heavy tasks, like Plan Mode.
-- `longContext`: A model for handling long contexts (e.g., > 60K tokens).
-- `longContextThreshold` (optional): The token count threshold for triggering the long context model. Defaults to 60000 if not specified.
-- `webSearch`: Used for handling web search tasks and this requires the model itself to support the feature. If you're using openrouter, you need to add the `:online` suffix after the model name.
-- `image` (beta): Used for handling image-related tasks (supported by CCR’s built-in agent). If the model does not support tool calling, you need to set the `config.forceUseImageAgent` property to `true`.
+- `primary`: The general-purpose model. `default` remains a legacy synonym.
+- `aliases`: Maps Claude Code's `haiku`, `sonnet`, and `opus` model intents to provider models. `background` remains a legacy synonym for `aliases.haiku`.
+- `capabilities.webSearch`: A model for Anthropic web-search requests. `webSearch` remains a legacy synonym.
+- `capabilities.vision`: A vision-capable model for current user images. `image` remains a legacy synonym and CCR's image agent handles historical-image fallback.
+- `subagents`: Maps explicit `<CCR-ROUTE>profile</CCR-ROUTE>` tags in custom subagent system prompts to provider models.
+
+CCR does not route on `thinking` or estimated context length. Claude Code owns adaptive thinking, 200K/1M context selection, and compaction.
 
 - You can also switch models dynamically in Claude Code with the `/model` command:
 `/model provider_name,model_name`
@@ -494,15 +508,48 @@ module.exports = async function router(req, config) {
 
 ##### Subagent Routing
 
-For routing within subagents, you must specify a particular provider and model by including `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` at the **beginning** of the subagent's prompt. This allows you to direct specific subagent tasks to designated models.
+Claude Code custom agents are Markdown files in `~/.claude/agents/` (or
+`.claude/agents/` in a project). Give each agent a native Claude model alias and
+an explicit CCR route profile in its prompt:
+
+```markdown
+---
+name: ccr-explore
+description: Fast, read-only codebase exploration.
+model: haiku
+tools: Read, Glob, Grep
+---
 
-**Example:**
+<CCR-ROUTE>explore</CCR-ROUTE>
 
+Explore the codebase and report concise, evidence-backed findings. Do not modify files.
 ```
-<CCR-SUBAGENT-MODEL>openrouter,anthropic/claude-3.5-sonnet</CCR-SUBAGENT-MODEL>
-Please help me analyze this code snippet for potential optimizations...
+
+Map the profile and give it its own fallback list. Profile fallbacks are
+intentional: `Fallback.subagents.explore` does not implicitly inherit the
+`haiku` alias fallback.
+
+```json
+{
+  "Router": {
+    "subagents": {
+      "explore": "groq,llama-3.3-70b-versatile"
+    }
+  },
+  "Fallback": {
+    "subagents": {
+      "explore": ["openrouter,meta-llama/llama-3.3-70b-instruct"]
+    }
+  }
+}
 ```
 
+Use the agent with `ccr code --agent ccr-explore`, or ask Claude Code to use
+the named agent. CCR removes the route tag before forwarding the request.
+
+`<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` remains available as
+a legacy per-prompt override; it takes precedence over a profile tag.
+
 ## Status Line (Beta)
 To better monitor the status of claude-code-router at runtime, version v1.0.40 includes a built-in statusline tool, which you can enable in the UI.
 ![statusline-config.png](/blog/images/statusline-config.png)