🧠⚡ Claude Code Local

Claude Code, running on your own Mac. No cloud. No API key. No waiting.

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.

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.py and scripts/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.py reproduces 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.
• 🚀 install.sh, setup.sh and scripts/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 / -Fix to restart your own service that is down or recreate a missing symlink (it never deletes anything), and --report / -Report for a privacy-safe block to paste into a bug report.
• 🎮 launchers/ with the shared launchers/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.

🛑 Hit your Claude usage limit?

Claude Code just said "you've reached your usage limit" and the reset is hours away? Keep working: same Claude Code, same project, but the AI answering runs on your own Mac.

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash

That's it. It even works on a 16 GB MacBook, and gets better the more memory your Mac has.

Once it's running, the local-first family takes it off the keyboard: your browser, your voice, your phone, all on the same machine.

🔋 Out of Claude credits? Keep going.

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 Mac from the lineup below, sized to fit your memory

setup.sh installs it for you. To add it by hand, or to turn on the free cloud models:

echo 'source "$HOME/claude-code-local/scripts/keepgoing-shell.sh"' >> ~/.zshrc   # the "keep going" command
mkdir -p ~/.config/claude-code-local
echo 'OPENROUTER_API_KEY=your-free-key' >> ~/.config/claude-code-local/keepgoing.env   # optional

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.

🤔 What is this, really?

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

💻 What you need

• 🍎 A Mac with Apple Silicon (M1 or newer)
• 🐍 Python 3.12 (setup installs it for you)
• 🤖 Claude Code: npm install -g @anthropic-ai/claude-code

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

💻 On an 8 GB or 16 GB Mac?

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.

🚀 Get started

One command:

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash

Or read the script first:

git clone https://github.com/nicedreamzapp/claude-code-local
cd claude-code-local
bash setup.sh

Setup 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 full kit

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 later

With 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 claude is too old. Update it: npm install -g @anthropic-ai/claude-code

# 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-6

setup.sh installs the server as a symlink back to proxy/server.py in this repo, so if you edit it, just restart the server.

🐧🪟 On Linux or a Windows PC

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 | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.ps1 | iex

You 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 claude-local. The catalog lives in portable/catalog.json.

What it depends on (and how we'd replace it)

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.json and 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.

---

🥊 Pick your AI

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.

🤗 Good builds from other people

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.sh installs) · 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 ·

⚠️ "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.

🎮 Ways to use it

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 and hear it answer in your own voice: Narrative Gemma (guide). Needs a speak command (macOS say works as a stand-in)
📱	Phone	Text your Mac from your iPhone and get answers back (guide). No launcher here: the iMessage scripts live in claude-screen-to-phone

🌊 Use it with Trinidad Head

Trinidad Head is the recommended terminal for running local models, on Mac and PC. It's built from scratch by the same person who made this project, and it makes long local-AI sessions nicer:

• 🪟 Glass windows with a soft neon glow, rounded and easy on the eyes
• 🌈 A different color for every window, so you can tell your local-model windows apart at a glance
• 🔠 Bigger, easy-to-read text
• 💬 Your own prompts stand out in a soft bubble, so you can find what you asked when you scroll back
• 🖱️ Copy and paste just work, even under Claude Code's calm focus view

👉 Get Trinidad Head · project page

🧩 The local-first family

The modes above aren't bolted on. Each one is its own repo that works on its own, and they all run on your hardware. If Claude Code on your own Mac was the part you wanted, this is the rest of it.

	Project	What it does
🌊	Trinidad Head	A terminal for Mac and Windows, written from scratch in Rust, that gives every window its own glow color and puts your own prompts in a bubble so they are easy to find
🎤	NarrateClaude	A hands-free voice loop for Claude Code on macOS, Linux and Windows that turns your speech into text locally with whisper.cpp, types it into claude, and reads the replies aloud with a local Piper voice
🌐	browser-agent	An agent that takes a task in plain English and carries it out in your real Brave browser and your shell, with the model running on your Mac
🚦	browser-broker	A local proxy on Chrome's debug port that gives each AI agent its own tab in your real, logged-in browser, so agents can't grab each other's tabs or yours
📱	claude-screen-to-phone	macOS scripts that let you text commands from your iPhone into a Claude Code session on your Mac and get text, images and video back in iMessage
🖥️	FiaOS	A small self-hosted Python web server that gives you a computer's live screen and a real terminal in any browser, on macOS and Windows
🌙	Moonstone	A local voice control panel that puts every Claude Code session on every machine you own in one browser window, with answers read back to you
🛟	claude-failover

🔒 Your code stays home

Your code never leaves your Mac. No cloud model, no tracking, no "anonymous analytics".

The launchers switch off Claude Code's own background internet traffic with Anthropic's documented settings (thanks @tadrianonet, PR #32):

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
DISABLE_AUTOUPDATER=1
CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Check it yourself: during a session, lsof -a -i -p "$(pgrep -d, -f claude)" lists the network connections of every Claude process, and the only one is localhost:4000.

🧹 We removed LiteLLM after supply-chain concerns and re-checked every dependency. Anything with unexplained network calls didn't ship. The full audit is in the full guide.

☁️ The one exception is your own choice: picking a free cloud model in keep going sends that conversation to OpenRouter.

📚 Want the details?

📖 Full technical guide	Every model table, benchmark, tuning setting and design note
📊 Benchmarks · 🔧 Tool-call reliability	The numbers and how they were measured
🎤 Voice mode · 🌐 Browser agent · 📱 Phone control · 🔌 MCP servers	Everything the launchers can do
🔋 Automatic keep going	Hand a conversation to a free or local model by itself when you hit a usage limit
📁 What's in this repo · 🙏 Credits	The tour and the thank-yous

🧭 Other ways to do this

This isn't the only way to run Claude Code against models you choose, and some of these may fit you better:

• Ollama speaks the Anthropic Messages API natively since v0.14, so Claude Code can point straight at it. The simplest route if you already use Ollama, and it isn't limited to Macs.
• claude-code-router routes Claude Code's requests across many providers and models, local or cloud. Good if you want to mix models per task.
• claude-code-proxy translates Claude Code's requests to OpenAI-style APIs. Handy if your model already sits behind an OpenAI-compatible server.

What this repo adds is an MLX-native server tuned for Apple Silicon and for the tool-call formats local models actually emit.

🤝 Help make it better

Ideas, bug reports, a launcher for a model we don't run: open an issue or a PR, every one gets read. CONTRIBUTING.md has how to run it from the repo and the tests. We especially love hearing from people on older or smaller Macs about which models really fit.

Thank you, contributors: @0xshugo · @asdmoment · @kulveersingh · @tripathiprateek · @tadrianonet · @kevbarns · @KaoCSC · @zwolf25. What each of them fixed is in the full guide.

Built by Matt Macosko in Humboldt, California. Open to work on local AI and Apple Silicon: [email protected]

Nice Dreamz software · YouTube demos · Discord

📜 MIT License, use it however you want. ⭐ Star the repo if it helped you!

Built by Matt Macosko in Humboldt, California. Open to work on local AI and Apple Silicon: [email protected]

Nice Dreamz software · YouTube demos · Discord

📜 MIT License, use it however you want. ⭐ Star the repo if it helped you!