Maintainer of this skill?
by cablate
Per-window model switcher, subagent router, and automatic 429 failover for Claude Code — switch any window with /provider, delegate subagents across models, and keep Remote Control & statuslines working.
# Add to your Claude Code skills
git clone https://github.com/cablate/model-relaySee how model-relay compares with popular alternatives.
model-relay is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by cablate. Per-window model switcher, subagent router, and automatic 429 failover for Claude Code — switch any window with /provider, delegate subagents across models, and keep Remote Control & statuslines working. It has 81 GitHub stars.
model-relay's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/cablate/model-relay" and add it to your Claude Code skills directory (see the Installation section above).
model-relay is primarily written in JavaScript. It is open-source under cablate on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh model-relay against similar tools.
No comments yet. Be the first to share your thoughts!
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
Claude Code binds model settings globally across every terminal window. model-relay runs a lightweight router on localhost (127.0.0.1:8950) so each window and subagent can use the model you want—with zero external cloud proxies.
| When… | Without model-relay |
With model-relay |
|---|---|---|
| You want to switch just one window to another model | Editing settings.json switches every open terminal at once |
Type /provider to switch only the current window from the panel above your prompt (and write its active model to model-relay-status/<session id> for your statusline) |
You want haiku or a specific subagent on another model |
Changing global env vars forces your main Opus/Sonnet chat onto that endpoint too | /provider alias haiku <name> offloads haiku globally, or model-relay:<name> spawns a one-off subagent on that provider with all tools intact |
| Claude hits a 5-hour usage limit (HTTP 429) or a provider hiccups | Your turn fails mid-task until quota resets | Automatic retries and failover.chain hand the request to your backup provider and pin only that window while new windows return to Claude after cooldown |
You use Remote Control (claude.ai/code) from your phone or browser |
Custom ANTHROPIC_BASE_URL blocks Remote Control from connecting |
Local HTTPS proxy mode (/provider rc on) keeps Remote Control working while routing each window independently |
Third-party gateways lose history/tools or reject ToolSearch / cache_control |
message-threads deltas cause mid-chat amnesia, and ToolSearch hides tools or triggers HTTP 400 |
Automatically sends full conversations keeps ToolSearch working, and cleans cache_control per provider on the fly |
model-relay is built for Claude Code users who combine a Claude subscription with backup or specialized endpoints (z.ai, DeepSeek, Kimi, MiniMax, OpenRouter, or a gateway on your own machine). Each provider has to accept Anthropic's /v1/messages format; a service that only speaks OpenAI Chat Completions needs a local translator (see Limitations). If you need a multi-tenant cloud proxy for an entire organization, use LiteLLM instead—model-relay is a single-user localhost daemon.
Requires Node.js 20+ and Claude Code 2.1.287 or later (tested on Node.js 22.23.2 and Claude Code 2.1.306).
⚠️ Upgrading from 0.6 or earlier? Updating the plugin alone is not enough. Version 0.7+ reads only
"format": 2in~/.claude/model-relay.json. Until you migrate your config and restart the router, an old 0.6 router still running in the background keeps running 0.6 code (without 0.7's conversation/tool loss fix or localhost security check), and once that process stops, the plugin will not start a new router until you migrate. Run/provider setup upgrade my model-relay configand Claude does it with you, or follow UPGRADING.md by hand (node tools/setup.mjs migrate, thenmigrate --go, then/provider restart).
claude plugin marketplace add cablate/model-relay
claude plugin install model-relay@model-relay
Set your provider's API key before starting Claude Code. The relay reads it from the environment of Claude Code, so a variable set in a shell that is already running Claude Code is not seen. Make it permanent, for example export BACKUP_API_KEY="your-api-key" in ~/.zshrc (macOS/Linux) or setx BACKUP_API_KEY "your-api-key" (Windows), then open a new terminal.
Open Claude Code and let it set things up with you. Run /reload-plugins first if Claude Code was already open.
/provider setup
Claude runs the setup tool for you, never asks you to paste a key into the chat, and asks before it changes ~/.claude/settings.json. Add what you want, such as /provider setup use deepseek for haiku.
Check that it works.
/provider doctor --ping
You should see Config OK, your provider under Providers, and a ✓ for it under Upstream ping:
Config OK (~/.claude/model-relay.json)
Port: 8950
Providers: backup -> your-model-id
Failover: backup (back to Claude after 10 min) Retry: on
Aliases: none (run "node tools/setup.mjs alias haiku <provider>" to route haiku)
Claude settings: ✓ settings.json ANTHROPIC_BASE_URL=http://127.0.0.1:8950
Router health: ✓ up on 127.0.0.1:8950 (pid 38780, <version>, pinned sessions: 0, 429 failover: idle, proxy off (0 routed / 0 tunnelled))
Upstream ping:
✓ backup (your-model-id) -> answers, first byte after 640 ms
Anything doctor finds is listed with a ⚠ and what fixes it; /provider setup can run those fixes with you. doctor only reports and changes nothing; add --fix (/provider doctor --fix) to let it apply the repairs it can make itself, such as pointing ANTHROPIC_BASE_URL in ~/.claude/settings.json at the relay. doctor --json prints the same findings for an assistant or a script, each with the setup.mjs arguments that fix it (fix) and whether that command changes something you should agree to first (needsConsent).
Nothing goes to a provider unless you say so. A new config keeps haiku and every other request on Claude; the first provider you add becomes the one that takes over on a 429 (failover.chain). To send Claude Code's haiku calls (subagents, WebFetch summaries, internal helpers) to a provider, run node tools/setup.mjs alias haiku <name>.
Setting it up by hand: run /provider init (creates ~/.claude/model-relay.json with no provider yet, so every request still goes to Claude, and points ANTHROPIC_BASE_URL in ~/.claude/settings.json at the relay). Add a provider with node tools/setup.mjs add <name> --preset <preset> --model <model id> --token env:<VAR> (presets lists the built-in ones; --url takes any other Anthropic-compatible address), restart Claude Code, then run /provider doctor --ping.
Where node tools/setup.mjs runs: the node tools/setup.mjs ... commands later in this README are the same tool. They run from the plugin's install directory, which is ~/.claude/plugins/cache/model-relay/model-relay/<version>/ ($CLAUDE_CONFIG_DIR/plugins/cache/model-relay/model-relay/<version>/ when you set CLAUDE_CONFIG_DIR; ls that folder for your version). Elsewhere, use the full path to tools/setup.mjs inside it. The command acts on the config directory in $CLAUDE_CONFIG_DIR, or ~/.claude if unset. /provider setup runs them for you from anywhere.
A key exported later is not seen: env:VAR tokens are read from the router process's own environment, which it inherits from whichever Claude Code session (or setup command) started it. A variable exported after the router started is not seen until the router restarts: stop the router process (doctor prints its pid) and start a new Claude Code session. doctor reads your shell, so it can report the key as set while the router cannot see it.
Updating: run claude plugin update model-relay@model-relay. The plugin then restarts the relay by itself once no request is in flight through it; a relay from 0.6 or earlier cannot report that, so a notice asks you to run /provider restart when no Claude Code window has a reply in progress.
AbovePrompt control panel and provider testType /provider to open a panel right above your prompt input box. It does one thing: pick which model this window uses, one button per row. Once a switch takes, the panel closes and a notice names the model now in use. Click a button, or press ctrl+x tab and then the key shown on it (1–9 to switch, p to test every provider, and r to try Claude again while a 429 cooldown runs). Switching a pinned window back to Claude takes a second press to confirm. The switches every window shares stay folded under Settings [s]: press it to show 429 failover, retry and Remote Control (f / t / x) and the model aliases. They turn on or off without editing JSON: failover and retry apply from the next request, while Remote Control asks first because it rewrites settings.json: turning it on reaches new sessions only, and turn