claude-lmstudio-router sends your prompt to Claude first and falls back to a model running on your own laptop in LM Studio, and it can also run the Claude Code agent entirely on a local model.
Open-source tools · How-to · Local AI fallback
How to use claude-lmstudio-router: keep working when Claude is unavailable
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/claude-lmstudio-router
Watch the walkthrough
Watch on YouTube: youtu.be/VlADACEG99I
What it is for
Long jobs stop when Claude returns a rate-limit (429) or overload (529) error. Some data should never leave your computer. This repo gives you two small tools for those cases.
router.py is a one-shot command. It tries the Claude API first, retries twice on 429 or 529, and then sends the same prompt to a model served by LM Studio on your machine. Each call is written to router_log.jsonl, so you can see which engine answered.
claude_code_proxy.py is a local translator. Claude Code speaks the Anthropic API and LM Studio speaks the OpenAI API. The proxy converts between them, so the whole Claude Code agent can run on a local model, fully offline.
Who it is for
- People who hit Claude rate limits on long batch jobs and want a draft answer anyway
- Users who must keep some text on their own computer
- Engineers who want to see how an Anthropic-to-OpenAI proxy works
- Getting Claude-quality answers from a local model. Treat fallback output as a draft
- Image or vision work through the proxy. Image blocks are dropped
- Anyone who expects the tools to start LM Studio for them. Neither tool does
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3 | runs both tools | python.org or brew install python. The repo does not state a minimum version |
| LM Studio with a model loaded | the local fallback and the proxy backend | Download from lmstudio.ai, load a model, open the Developer tab and click Start Server (default http://localhost:1234). Model size and RAM depend on the model you pick |
| A tool-calling model | required for the proxy, because Claude Code works through tool calls | The README suggests qwen2.5-coder-7b-instruct, qwen2.5-7b-instruct or llama-3.1-8b-instruct, and larger ones if you have memory. Reasoning-only models often fail |
| anthropic Python package and an ANTHROPIC_API_KEY | for the Claude-first path in router.py | pip install anthropic. Create a key at console.anthropic.com (separate from a claude.ai login, billed per token). Optional if you use --force-local |
| fastapi, uvicorn, httpx | only for the proxy | pip install fastapi uvicorn httpx |
| Claude Code CLI | only if you want the agent to run on the local model | Install Claude Code, then run it through the proxy |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/claude-lmstudio-router.git
cd claude-lmstudio-router
claude # or: geminiInstall
- Clone the repo and create a virtual environment.
git clone https://github.com/herrrickshaw/claude-lmstudio-router.git cd claude-lmstudio-router python3 -m venv .venv source .venv/bin/activate - Install the packages. The repo has no requirements file, so install them by name.
pip install anthropic pip install fastapi uvicorn httpx # proxy only - Set your API key (skip if you will only use --force-local). Never put the key inside router.py.
export ANTHROPIC_API_KEY="your-key-here" - In LM Studio, load a model and click Start Server on the Developer tab.
Quick start: commands and what you should see
See the options.
python -I router.py --helpA usage line and options such as --prompt, --task, --input, --system, --output, --force-local, --force-claude, --local-base-url and --local-model.
Run with no key and no LM Studio, to see an honest failure.
python -I router.py --prompt "Summarize: tariffs"It tries Claude and reports that ANTHROPIC_API_KEY is not set, tries LM Studio and reports that it could not reach http://localhost:1234, then prints FAILED: Both Claude and local LM Studio failed. router_log.jsonl records engine=none, success=false.
See the fallback path against a stand-in server. In the demo, port 1239 was a small canned server, not LM Studio.
python -I router.py --prompt "Summarize: tariffs" --local-base-url http://127.0.0.1:1239/v1Claude is skipped because there is no key, then the output says Answered by: LOCAL with a canned reply. The log line shows engine=local, success=true and the reason for the fallback. With real LM Studio running, the reply would come from your loaded model.
Start the proxy, then check it. The demo used port 8792 through PROXY_PORT. The default is 8787.
python claude_code_proxy.py
curl http://127.0.0.1:8787/healthThe health reply showed the proxy ok, LM Studio ok and the list of loaded models. With LM Studio really off, the proxy returned HTTP 503 and lmstudio: unreachable.
Run Claude Code through the proxy.
export ANTHROPIC_BASE_URL="http://127.0.0.1:8787"
export ANTHROPIC_API_KEY="local"
claudeNot run in the demo. In the demo a Read tool request was translated to OpenAI format for the backend, and the reply came back to Claude Code as an Anthropic tool_use block with stop_reason tool_use.
Ways to use it
| Method | How it works |
|---|---|
| One-shot command | python router.py --prompt "...", or --task plus --input file.txt for a file, --output to save, --force-local or --force-claude to choose the engine. |
| Claude Code on a local model | Start claude_code_proxy.py, set ANTHROPIC_BASE_URL, then run claude. The helper ./run_local_claude_code.sh sets the variables and checks the proxy first. |
| Settings | Environment variables LMSTUDIO_BASE_URL, LMSTUDIO_MODEL, LMSTUDIO_SMALL_MODEL, PROXY_HOST, PROXY_PORT, PROXY_REASONING (drop, think or text), PROXY_LOG and LMSTUDIO_TIMEOUT. The CONFIG block at the top of router.py sets the Claude model and retries. |
| Google Colab | The README links a Colab notebook (notebooks/colab_test.ipynb). The tools talk to a local LM Studio server, so they cannot run inside a hosted chat session. |
| Through an AI assistant | Ask Claude Code or Gemini CLI in the cloned folder to read the README and set up the environment variables for you. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Read README.md and router.py and explain, step by step, when router.py gives up on Claude and calls LM Studio.
- Help me set up LM Studio and router.py on my [Mac or Windows] machine. Give me one command at a time and tell me what I should see.
- Show me how to use router.py with --task and --input to summarise a text file, and how to read router_log.jsonl afterwards.
- Explain how claude_code_proxy.py converts an Anthropic request with tools into an OpenAI request. Which parts are dropped?
- Which local model should I load for the proxy given I have [amount of RAM]? Use the README's rules about tool calling.
- What data stays on my machine with router.py, and what goes to Anthropic? Answer from the README.
Limits and honest caveats
- Local models are weaker and slower than Claude. Treat fallback output as a draft and consider re-running it through Claude later.
- Claude Code needs a tool-calling model. Reasoning-only models often fail to emit tool calls.
- Image blocks are dropped, so there is no vision through the proxy.
- Neither tool starts LM Studio for you. You load the model and click Start Server.
- With router.py, text goes to Anthropic whenever Claude answers. Only the fallback and the proxy path stay fully local.
- No unit tests ship with the repo.
- The demo used a canned stand-in server, not LM Studio. Live model calls were not run, so latency, answer quality and real tool-use loops were not measured.
- The default model name (claude-sonnet-4-6) is set inside router.py. Check that it is still available to your account.
- Pointing ANTHROPIC_BASE_URL at the proxy changes where Claude Code sends all its requests. Unset it to go back to the cloud.
Sources: the claude-lmstudio-router README (read from GitHub) and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
