model-relay plugin
Plugin that switches the model per Claude Code window, routes subagents to other providers and fails over after a 429 limit.
- 111 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The plugin routes all Claude Code traffic through a local process and edits `~/.claude/settings.json` after confirmation.
- After a switch or failover, conversation history and code go to a third-party provider with different data-retention terms.
- Backup provider keys are read from the Claude Code process environment.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/model-relayDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The plugin routes all Claude Code traffic through a local process and edits `~/.claude/settings.json` after confirmation.
- After a switch or failover, conversation history and code go to a third-party provider with different data-retention terms.
- Backup provider keys are read from the Claude Code process environment.
This is third-party code. Review the repository files before installing.
What it does
`model-relay` starts a lightweight local router for Claude Code requests on `127.0.0.1:8950`. The `/provider` command opens a panel above the prompt: the model changes only in the current window and the others stay put. A subagent goes to another provider through `model-relay:<name>`, and the `haiku` alias is redirected globally with `/provider alias haiku <name>`. When Claude returns a 429 limit or a provider fails, `failover.chain` hands the request to a backup provider and pins it to that window only. The local HTTPS proxy mode `/provider rc on` keeps Remote Control working. A provider must accept the Anthropic `/v1/messages` format.
Who it is for. Claude Code users with a subscription and backup endpoints: z.ai, DeepSeek, Kimi, MiniMax, OpenRouter or a gateway on their own machine.
Good fit when
- One terminal window must move to another model without touching the others.
- The Claude limit ran out mid-task and the request goes to a backup provider.
- A search subagent runs on a cheap model while the main chat stays on Opus.
- You need Remote Control together with a custom API address.
Not a fit when
- You need one shared proxy for a whole organization; the README points to LiteLLM.
- A provider speaks only OpenAI Chat Completions and no local translator is set up.
- The network lets traffic out only through a corporate proxy; an upstream proxy is not supported.
Example request
Switch this window to the backup provider and check connectivity with `/provider doctor --ping`.Limitations
Needs Node.js 20+ and Claude Code 2.1.287 or newer. Upgrading from 0.6 or earlier requires moving settings to `~/.claude/model-relay.json` in format 2 and restarting the router; updating the plugin alone is not enough. Switching back to Claude mid-session resends the whole history because prompt caches do not transfer between providers. Backup provider keys are read from the Claude Code process environment, not from an already open shell. The plugin is built for one user on a local machine.
How to disable. Remove the plugin through Claude Code, stop the router and restore the previous values in `~/.claude/settings.json`. Clean `~/.claude/model-relay.json` and provider keys separately.
FAQ
How do I switch only one window?
Type `/provider` and pick a model in the panel above the prompt. The choice applies to the current window; new windows start on Claude.
What happens on a 429 limit?
If `failover.chain` is set, the request goes to a backup provider and stays pinned to that window. An empty chain passes the 429 back unchanged.
Does Remote Control keep working?
Yes, enable the local HTTPS proxy mode with `/provider rc on`. A custom `ANTHROPIC_BASE_URL` alone breaks it.
Does an OpenAI-format provider work?
Only through a local translator: a provider must accept the Anthropic `/v1/messages` format. The translator can be supervised through `providers.<name>.launch`.
How do I verify the setup?
Run `/provider doctor --ping`. It prints `Config OK`, the provider list and the result of a trial request to each one.
Discussion
No questions or reviews yet.
Related
PluginsA local gateway for Claude Code, Codex, OpenCode and other agents: pick model providers, route requests, set fallbacks and read logs
Clother switches Claude Code between providers with one command: Z.AI, Kimi, DeepSeek, OpenRouter and local models.
Hooks read each prompt before the model and ask a free or local model for a draft first, saving Claude subscription quota.
A Claude Code plugin that asks several AI models the same question and shows their answers side by side with a synthesis of agreement and divergence
CLI that picks the agent, model and effort for a task by remaining subscription quota and launches it in a Herdr pane.
A local gateway for Claude Code that sends mapped models to OpenAI, Kimi, DeepSeek or Gemini and passes the rest to Anthropic
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| model-relay (this card) | no | 111 | |
| Claude Code Router | no | 38,127 | a general request router for Claude Code; `model-relay` changes the model per window and handles the 429 limit |
| CC Switch | no | 153,939 | switches provider configurations through an app; `model-relay` works as a plugin inside the Claude Code window |
README in short
The plugin uses no external cloud proxy: the router runs on localhost. Configuration lives in `~/.claude/model-relay.json`, and the window status is written to `model-relay-status/<session id>` for the status line.