Claude Code Local: Run Claude Code on Apple Silicon
nicedreamzapp/claude-code-local
Claude Code Local turns your Mac's GPU into the backend for Claude Code, replacing Anthropic's cloud API with an MLX-native server that speaks the same protocol, no proxy in between. Reach for it if you've hit a usage limit, need an air-gapped setup for NDA or healthcare work, or want the monthly bill gone. Skip it if you need Claude-level reasoning every time — cloud Sonnet is still a bit faster.
Bypass Claude Code Usage Limits
Claude Code's usage limits cut you off mid-task with a reset timer that can be hours away, and there's no way to keep working in the same terminal and project without either waiting or paying for a second subscription. Claude Code Local exists specifically for that moment: point the same `claude` CLI at a local MLX server instead of Anthropic's API, and the session keeps running on whichever model your Mac can host — from a 14B model on a 16 GB MacBook up to a 122B model on a Mac with more RAM.
What is Claude Code Local?
Claude Code Local is an open-source, MLX-native server that lets Claude Code run against large language models on your own Apple Silicon Mac instead of Anthropic's cloud. It speaks the Anthropic API directly — no OpenAI-format proxy in between — and ships with a swappable lineup of local models: Gemma, Llama, Qwen, and DeepSeek.
Key Capabilities and Model Lineup
- ✓Native Anthropic API server (`proxy/server.py`, about 1,000 lines) — no OpenAI-format translation layer, which the README credits with cutting a real Claude Code task from 133 seconds to 17.6 seconds.
- ✓A five-model lineup you swap with one env var: Hermes 4 14B, Gemma 4 31B, Llama 3.3 70B, Qwen 3.5 122B, and DeepSeek V4 Flash via the separate `ds4` engine.
- ✓Tool-call translation for three formats — Gemma 4 native, Llama 3.3 raw JSON, and HuggingFace `<tool_call>` JSON — converted to and from Anthropic `tool_use` blocks, with garbled-output recovery.
- ✓Prompt-cache reuse across requests plus a 'Code mode' that swaps Claude Code's ~10K-token harness prompt for a ~150-token one, which the README says gives a 28x prompt reduction.
- ✓DeepSeek V4 Flash support through antirez's `ds4` engine, with 1M-token context and an on-disk KV cache that persists across restarts.
- ✓Four launch modes beyond plain coding: a browser agent that drives Brave via Chrome DevTools, a hands-free voice loop through the separate NarrateClaude project, and an iMessage bridge via claude-screen-to-phone.
Quick Start and Installation
The documented path is a one-line curl install: `curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash`. If you'd rather read the script first, clone the repo and run `bash setup.sh` instead — it detects your Mac's RAM, picks a model from the lineup, downloads it, installs the MLX server, and drops a `Claude Local.command` launcher on your Desktop that you double-click to start coding. The manual path is also documented: create a Python 3.12 virtualenv, `pip install mlx-lm`, run `scripts/download-and-import.sh` with a model name, start the server with `scripts/start-mlx-server.sh`, then launch `claude` with `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` pointed at localhost. You'll also need Claude Code itself (`npm install -g @anthropic-ai/claude-code`) — the README notes older CLI versions will prompt you to sign in because they don't support the `--bare` flag the launchers pass.
Running Different AI Modes
Each mode is a double-clickable launcher in the repo's `launchers/` folder rather than a flag you pass. Code mode runs Claude Code itself against a local model with launchers like `Claude Local.command`, `Gemma 4 Code.command`, or `Llama 70B.command` — same CLI, no API key. Browser mode (`Browser Agent.command`) has the local model drive a real Brave browser through Chrome DevTools. Voice mode (`Narrative Gemma.command`) runs a hands-free loop where you speak and hear replies in a cloned voice via the separate NarrateClaude project. Phone mode routes iMessage in and text, image, or video out through shell scripts under `~/.claude/imessage-*.sh`, built on the claude-screen-to-phone project. Switching models takes one environment variable: `MLX_MODEL`. No reinstall needed.
Privacy and Performance Advantages
- ✓Nothing leaves the Mac: the README lists zero outbound calls audited across server.py, the browser agent, mlx-lm, MLX itself, and model weights at runtime — verifiable yourself with `lsof -i -P` while the server runs.
- ✓Removing the proxy layer is the actual speed win, not just a claim: the README's own benchmark goes from 133 seconds to 17.6 seconds for the same task once the OpenAI-format translation step is gone.
- ✓$0 monthly cost once a model is downloaded, against the $20-100+ the README cites for Claude Sonnet or Opus subscriptions.
- ✓Works with no wifi at all — useful for NDA review or a flight, per the README's stated scenarios.
Considerations for Local AI
- △The README says cloud Sonnet still edges out the local setup on raw speed (about 80 tok/s vs. 65 tok/s for the fastest local model), and it's upfront that local models aren't at Claude's level.
- △The bigger models need serious hardware — Qwen 3.5 122B and Llama 3.3 70B both want 96 GB+ of RAM, and DeepSeek V4 Flash needs 128 GB; the 16 GB entry point only gets you Hermes 4 14B.
- △The bundled models are 'abliterated' builds that suppress refusal behavior, which the README explicitly flags as something to use responsibly and not a general capability upgrade — plus you're still bound by each model's upstream license (Llama 3.3, Gemma, Hermes/Qwen3).
- △Local tool-calling took real engineering to get reliable (KV cache tuning, lower temperature, retry logic) — the README reports 98/98 tests passing across 7 runs after those fixes, which implies it wasn't reliable before them.
- △First-time setup means downloading 18-75 GB of model weights per the README, so it's not a quick trial on a slow connection.
Proxy-Based Local AI Alternatives
Frequently Asked Questions
Claude Code Local works fully offline once the model is downloaded — the README reports zero outbound network calls for the server, the browser agent, MLX, and model weights, verifiable by running `lsof -i -P` while it's active.
Claude Code Local needs Apple Silicon and Python 3.12+; the README's table starts at a 16 GB MacBook Air or base M1-M4 for Hermes 4 14B, scales to 32-48 GB for Gemma 4 12B, 64-95 GB for Gemma 4 31B, and 96 GB+ for Qwen 3.5 122B, Llama 3.3 70B, or DeepSeek.
Claude Code Local keeps every request on-device: the MLX server runs on localhost:4000, the README's audit table lists zero outbound calls for server.py, the browser agent, mlx-lm, and MLX, and its launchers set four Anthropic environment variables to disable Claude Code's own telemetry, autoupdater, and marketplace auto-install.
The README's own numbers put cloud Claude Sonnet slightly ahead on raw speed (about 80 tok/s versus the local setup's 65 tok/s) but at $20-100+ a month versus $0 for Claude Code Local, and only the local setup works with no internet connection at all.
After tuning the KV cache, lowering temperature from 0.7 to 0.2, and adding garbled-JSON recovery and retry logic, the README reports Claude Code Local passing 98 of 98 tool-calling tests across 7 consecutive runs, including a multi-step file-management scenario that used to loop infinitely.
Claude Code Local ships five models you switch between with one environment variable: Hermes 4 14B, Gemma 4 31B, Llama 3.3 70B, Qwen 3.5 122B, and DeepSeek V4 Flash, run through the separate `ds4` engine with 1M-token context.
Best use cases
- •Working past a Claude Code usage-limit wall without waiting for the reset timer or buying a second subscription.
- •NDA-bound or client legal review where code and documents can't leave the machine — the README frames this as a built-for scenario, with an example of a 70B model auditing a document over Wi-Fi that's physically off.
- •Coding on a plane or anywhere without a connection, since the whole loop runs on-device.
- •Cutting the recurring API bill to $0 for day-to-day coding once the initial model download is done.
- •Healthcare, legal, or finance workflows where an audit trail of zero outbound calls matters more than squeezing out the last bit of model quality.
Who should try it — and who should skip
Try Claude Code Local if you're on Apple Silicon, already use Claude Code day to day, and either keep hitting usage limits or need to keep code off the network for NDA, legal, or healthcare work — the setup script does the model selection for you, and even a 16 GB MacBook Air gets a usable model. Skip it if you're on Windows or Linux, need the strongest possible reasoning on every task and are fine paying for it, or don't want to manage 18-75 GB model downloads and RAM budgeting yourself.
Related repositories
Still deciding about claude-code-local?
One click hands the question to an AI along with this page — see what it says about claude-code-local.