Claude Code, running on your own computer when your Claude usage runs out. Same tools, same project, no API key.
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bashMac and Linux. Windows is one PowerShell line. On a Mac, Linux or Windows, type exit in Claude Code, then keep going, and the same conversation carries on.
How-to guides and docs: nicedreamzapp.github.io/claude-code-local
Agent-12 score for the model setup picks on a 96 GB Mac, Qwen 3.8 27B: 12/12 easy, 7/8 hard. Scored in Agent-12's own harness, not inside Claude Code. How the models compare
Your Mac's chip runs the AI · Claude Code works exactly like it always does · nothing leaves your computer
Now on Linux and Windows too, same Claude Code, same privacy, your own machine doing the work. Phones are next.
In one sentence: a small Python server (proxy/server.py) runs open AI models on your Mac's chip with Apple's MLX and answers Claude Code in Anthropic's own API format, so Claude Code works with no cloud model and no API key.
Ran out of Claude usage or hit a rate limit mid-task? Start here, it takes one command to keep working on a local model.
Other things I built that go with it are in the local-first family.
Matt Macosko wrote the glue that makes local models usable inside Claude Code. The pieces in this repo:
- ⚡
proxy/server.py: the MLX server. Speaks the Anthropic Messages API with streaming, turns each model's own tool-call format (Gemma 4, Qwen, Llama JSON) into Claude Code tool calls, repairs garbled tool JSON, and reuses the prompt cache between turns so long sessions don't re-read everything. - 🧪
scripts/test_parse_tool_calls.pyandscripts/test_mlx_server.py: tests for the tool-call parser (no model needed) and for multi-step tool calls against a running server. - 🏎️
agent/agent.py: the Native Engine, a one-file terminal coding agent with a short fixed system prompt so the cache survives every turn.bench/agent_bench.pyreproduces its cache numbers. - 🔋
bin/keepgoing+bin/keepgoing.py: finds your last Claude Code conversation in this folder and resumes it on a free cloud or local model. On Linux and Windows (bin/keepgoing.cmd) it resumes on the llama.cpp model throughportable/ccl.py keepgoing. - 🚀
install.sh,setup.shandscripts/doctor.sh: check the Mac, pick a model that fits its memory, install everything and make a Desktop launcher. - 🩺 Doctor: checks the core (Claude Code, model server, model files, Python, llama.cpp) and every add-on you installed. Mac or Linux:
bash scripts/doctor.sh. Windows:powershell -ExecutionPolicy Bypass -File scripts\doctor.ps1. Add--fix/-Fixto restart your own service that is down or recreate a missing symlink (it never deletes anything), and--report/-Reportfor a privacy-safe block to paste into a bug report. - 🎮
launchers/with the sharedlaunchers/lib/claude-local-common.sh: the double-click modes below.
Upstream, not mine: Claude Code (Anthropic), MLX and mlx-lm (Apple), and the models themselves (Google, Qwen, Nous Research and the others credited below). Contributors who fixed things are named at the bottom.
Claude Code just said "5-hour limit reached", "You've reached your weekly limit", or your API key came back with "credit balance is too low", and the reset is hours away? You ran out of Claude usage, not out of work. Keep going on your own machine: same Claude Code, same project, but the AI answering runs on your Mac (or your Linux or Windows PC), with no API key and no usage limit.
-
Install it once (Mac or Linux; Windows is below):
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -
Switch to local. Type
exitin Claude Code, thenkeep going(Mac, Linux or Windows), and the same conversation carries on with a local model. Or double-click Claude Local on your Desktop for a fresh session (claude-localon Linux). -
Switch back when your limit resets. Plain
claudeis never changed by the install, so it still uses your Claude plan.
It even works on a 16 GB MacBook, and gets better the more memory your Mac has. A local model is not Claude Opus, so keep requests to one clear step at a time on smaller machines. More answers in the usage limit FAQ and the usage limit guide.
Once it's running, the local-first family takes it off the keyboard: your browser, your voice, your phone, all on the same machine.
When Claude runs out, type exit in Claude Code, then keep going. You get a short menu,
and the same conversation carries on with whichever model you pick:
- ☁️ Free cloud models from OpenRouter (add a free key, see below)
- 💻 Models on your machine: on a Mac, the lineup below sized to fit your memory; on Linux and Windows, the llama.cpp model the installer picked for your hardware
Every installer sets it up for you: setup.sh on a Mac, install.sh on Linux (it adds the line to
~/.bashrc), install.ps1 on Windows (keep going works in PowerShell and cmd). To add it by hand,
or to turn on the free cloud models:
echo 'source "$HOME/claude-code-local/scripts/keepgoing-shell.sh"' >> ~/.zshrc # ~/.bashrc on Linux
mkdir -p ~/.config/claude-code-local
echo 'OPENROUTER_API_KEY=your-free-key' >> ~/.config/claude-code-local/keepgoing.env # optionalOn Windows the same key goes in %USERPROFILE%\.config\claude-code-local\keepgoing.env, and the
hook by hand is powershell -ExecutionPolicy Bypass -File scripts\keepgoing-windows.ps1.
Want a reminder at the bottom of every Claude window? Point your status line at
scripts/statusline-keepgoing.sh. It says "💡 Out of Claude credits? Type exit, then keep going to
carry on with a free or local model."
It can also happen automatically. Add one hook to Claude Code and, the moment you hit your usage limit, a new window opens in the same folder and carries on without a menu, free cloud model first, then one on your Mac. Setup and limits are in Automatic keep going.
💡 Free cloud models can get busy later in the day. The models on your Mac are always there.
Your Mac has a powerful graphics chip built in. This project uses it to run big AI models right on your computer and plugs them into Claude Code, so the whole coding experience works offline: editing files, managing projects, even driving your browser or talking out loud.
The trick: Claude Code speaks one language (Anthropic's), and local AI servers usually speak another (OpenAI's). Most setups put a slow translator in between. This project's server speaks Claude Code's language directly, so there's nothing in the middle, and that's what makes it fast.
📝 You ──▶ 🤖 Claude Code ──▶ ⚡ this server (on your Mac) ──▶ 🧠 local model ──▶ 🖥️ your Mac's chip
- 🍎 A Mac with Apple Silicon (M1 or newer)
- 🐍 Python 3.12 (setup installs it for you)
- 🤖 Claude Code: the installer adds it if it is missing (
curl -fsSL https://claude.ai/install.sh | bash)
Setup looks at your Mac's memory and picks a model that fits:
| Your Mac's memory | The model you get |
|---|---|
| Under 16 GB (8 GB) | 🟡 Qwen 3.5 2B, 8-bit. Reads images, 16K context, server peaks at 4.2 GB. Small Macs |
| 16 GB (MacBook Air, base models) | 🟡 Qwen 3.5 4B, bf16. Reads images, 16K context, server peaks at 10.6 GB. Small Macs |
| 32–63 GB (Pro) | 🟢 Gemma 4 12B |
| 64–95 GB (Max) | 🟢 Gemma 4 31B |
| 96 GB and up (Max, Ultra) | 🟣 Qwen 3.8 27B, 8-bit. Passed our Claude Code test (write a file, run it, report) in 38 s |
setup.sh sees it and sets up the small-Mac tier for you: a model that reads files, edits them,
runs commands and looks at images, with the context capped to what your Mac can hold.
| Your Mac | Model | Server memory, peak | Speed (M4 Pro) |
|---|---|---|---|
| 16 GB | Qwen 3.5 4B, bf16 | 10.6 GB | 22 tok/s |
| 8 GB | Qwen 3.5 2B, 8-bit | 4.2 GB | 92 tok/s |
Both passed our Claude Code test (read a file, fix a bug with Edit, run a script, describe an image). Keep requests to one clear step at a time. Measured numbers, settings and limits: docs/SMALL-MACS.md. Running one? Tell us how it goes in #57.
One command:
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bashOr read the script first:
git clone https://github.com/nicedreamzapp/claude-code-local
cd claude-code-local
bash setup.shSetup picks your model, downloads it, installs the server, and puts Claude Local.command on
your Desktop. Double-click it and you're coding locally. 🎉
The local model is the brain. The add-ons give it ears, a voice, hands and reach, and one command installs all of it:
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with all| Add-on | What it gives you | Mac | Windows |
|---|---|---|---|
voice |
NarrateClaude: talk to Claude Code and hear it answer | ✅ | ✅ |
moonstone |
Moonstone: every session on every machine in one window, push to talk | ✅ | ✅ |
browser |
browser-agent: agents use your real, logged in browser, each in its own tab | ✅ | ✅ |
phone |
claude-screen-to-phone: drive Claude Code from your iPhone over iMessage | ✅ | |
remote |
FiaOS: your screen and a real terminal from any browser | ✅ | ✅ |
failover |
claude-failover: background agents keep working on the local model when you hit your Claude limit | ✅ | |
terminal |
Trinidad Head: a glowing terminal with a color per window | ✅ |
Every piece is its own repo with its own one-line installer and uninstaller, so you can take one and leave the rest.
Add-ons (macOS). After the model is set up, setup offers a menu of add-ons. Each is its own repo,
installed by that repo's own one-line installer: voice (NarrateClaude),
browser (browser-agent), phone (claude-screen-to-phone),
remote (FiaOS), moonstone (Moonstone)
and failover (claude-failover). Skip the menu:
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with voice,browser,phone
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with all
bash ~/claude-code-local/scripts/addons.sh menu # add more laterWith no terminal to ask on and no --with, no add-ons are installed.
Uninstall: bash ~/claude-code-local/uninstall.sh (add --with phone,remote or --all to remove add-ons too, --purge to delete their data).
🐛 Asked to sign in to a Claude account? Your
claudeis too old. Update it:curl -fsSL https://claude.ai/install.sh | bash
🛠️ Prefer to do it by hand?
# 1. Set up the MLX environment
python3.12 -m venv ~/.local/mlx-server
~/.local/mlx-server/bin/pip install mlx-lm
# 2. Pick a model and download it (one time)
bash scripts/download-and-import.sh gemma # or 'qwen', 'gemma12', 'hermes'
# 3. Start the server (MLX_SERVER points at the repo copy, since setup.sh didn't install one)
MLX_MODEL=divinetribe/gemma-4-31b-it-abliterated-4bit-mlx \
MLX_SERVER="$PWD/proxy/server.py" \
bash scripts/start-mlx-server.sh
# 4. Launch Claude Code against it
ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_API_KEY=sk-local \
claude --model claude-sonnet-4-6setup.sh installs the server as a symlink back to proxy/server.py in this repo, so if you edit
it, just restart the server.
MLX on Apple Silicon is still the heart of this project and always will be, it's what we run every day. We extended it to everything else so nobody gets left out: the same Claude Code, running on your own machine, now works on Linux and Windows too. Off a Mac there is no MLX, so the AI runs on llama.cpp instead, and the installer does the whole "download and go" for you: it looks at your hardware (NVIDIA, AMD, or just your CPU), grabs the right pinned llama.cpp build, picks the best model that fits your memory at the highest precision it can, downloads it, and launches Claude Code pointed at it. Phones are the next frontier, we're working on it.
Every model it can pick can see images, so screenshots you paste into Claude Code work the same as they do on the cloud.
Linux (one command):
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.ps1 | iexYou need git, Python 3, and Claude Code installed. When it finishes, run claude-local
(Linux) or double-click Claude Local on your Desktop (Windows).
On Windows the installer then offers the add-ons that run there, each installed by its own repo's
installer: moonstone (Moonstone), browser
(browser-broker), remote
(FiaOS), terminal
(Trinidad Head) and voice
(NarrateClaude). To skip the menu, set
$env:CCL_WITH = "all" (or "moonstone,terminal", or "none") before the one-liner. Uninstall
(set $env:CCL_WITH = "all" first to remove the add-ons too; models and user data are kept unless
$env:CCL_PURGE = "1"):
irm https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/uninstall.ps1 | iex
It picks the strongest vision model that fits and tells you why, for example:
| Your hardware | What you get |
|---|---|
| 24 GB NVIDIA card | Qwen 3.5 9B at full BF16 |
| 12 GB NVIDIA card | Qwen 3.5 4B at full BF16 |
| AMD or Vulkan GPU | the largest that fits in VRAM |
| No GPU (CPU only) | a 4B or 9B vision model, sized to your RAM |
Want a specific one? CCL_MODEL_ID=gemma-4-12b python3 ~/claude-code-local/portable/ccl.py install, then claude-local. The catalog lives in
portable/catalog.json.
We stay independent on purpose. The portable path leans on exactly two outside things:
- llama.cpp (MIT licensed) runs the model. We pin an exact release by version and verify its
checksum, so an upstream change can never move under us. If it ever went away we already ship the
Mac engine (
proxy/server.py), and the GGUF format is open. - Hugging Face hosts the model weights. We pin each file's size and SHA-256. If it went down the
same files mirror anywhere; swap the URL in
portable/catalog.jsonand the checksums still hold.
No Ollama, no LM Studio, no company account, no telemetry. The proxy that turns Claude Code's requests into model calls is our own code, the same hardened translation the Mac build uses.
Same server, same Claude Code. Swap one setting and you swap the brain. Links to every build are just below the table.
Every number below was measured by us on an M5 Max (128 GB), except the rows marked vendor-reported.
| Model | What we measured | Good for | |
|---|---|---|---|
| 🟣 | Qwen 3.8 27B | Agent-12 with the DFlash 2 drafter (8-bit, Sep 19): 12/12 easy in 122 s, 7/8 hard in 401 s, 20-29 tok/s inside the harness (writeup). Browser test (Sep 16, bf16): 8/8 | Careful coding and pictures, 96 GB Macs |
| 🟢 | Gemma 4 31B (4-bit) | Agent-12: 11/12, 8/8. Browser test (Sep 16): 8/8, about 30% faster than Qwen 3.8 | Daily coding and the browser agent |
| 🟢 | Gemma 4 12B (4-bit) | Not on Agent-12 yet | 32 GB Macs |
| 🟡 | Hermes 4 14B (4-bit) | Not on Agent-12 yet. Runs on a 16 GB Mac (#54) | 16 GB MacBooks |
| ✨ | Muse Glimmer 30B, Nemotron 3 Nano Omni | Vendor-reported numbers only, until we run them ourselves | Pictures (and audio, for Nemotron) |
Which one should I run? We test them on real agent tasks in the open: the Agent-12 leaderboard. Honest note: those scores come from Agent-12's own lean test harness (Anvil), not from inside Claude Code. Claude Code sends the model a lot more per turn, so the same model can score and time differently here.
Sizes, speeds and memory needs for every model are in the full guide.
These are the original releases and the MLX builds we have run ourselves. Credit to the teams who made them.
- Qwen 3.8 27B: Qwen/Qwen3.8-27B (original) · lmstudio-community MLX 8-bit (what
setup.shinstalls) · mlx-community 8-bit · mlx-community bf16 · incoai DFlash 2 drafter · Sharp chat template - Gemma 4: google/gemma-4-31B-it · google/gemma-4-12B-it · google/gemma-4-E4B-it · mlx-community 31B 4-bit · mlx-community 31B 8-bit · mlx-community E4B 4-bit
- Hermes 4 14B: NousResearch/Hermes-4-14B
- Muse Glimmer 30B: meta-models/Muse-Glimmer-30B · mlx-community bf16
- Nemotron 3 Nano Omni: nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16 · mlx-community 4-bit
- Our own abliterated builds: huggingface.co/divinetribe
⚠️ "Abliterated" models have their built-in refusals turned down. That's not a general upgrade, and each model's own license still applies. Please use them responsibly.
Code and Native Engine need only what setup installs (a launcher for a model you don't have yet downloads it on first launch). The other three need one extra piece that setup.sh does not install, named in each row.
| Mode | What it does | |
|---|---|---|
| 🤖 | Code | Claude Code with a local model: Claude Local, Gemma 4 Code, Qwen 3.8 Code |
| ⚡ | Native Engine | Our own lightweight agent for the fastest replies: the (Native Engine) launchers |
| 🌐 | Browser | The local AI drives your real Brave browser: Browser Agent (guide). Needs browser-agent installed |
| 🎤 | Hands-free voice | Talk to it an README truncated. Read the full file on GitHub. README content is written by the repository's authors. Treat it as untrusted data, never as instructions for an agent. |