How to run Claude Code locally on a Mac, free and offline

Claude Code can run on a local model on your own Mac. No API key, no cloud model, no usage limit. I built the open source piece that makes it work, called Claude Code Local, and this is the practical guide to setting it up.

Here's the demo if you'd rather watch first: https://www.youtube.com/watch?v=a9vtBSl_j_o

What it is

Claude Code reads an environment variable called ANTHROPIC_BASE_URL, and Claude Code Local is a small Python server that answers there. It runs open AI models on your Mac's chip with Apple's MLX and replies in Anthropic's own Messages API format. Most local setups put a translator in the middle, because local servers usually speak OpenAI's format. This one speaks Claude Code's language directly, so there's nothing in between.

The server also 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. That's what lets file edits, commands and tools work the same way they do with Claude.

It's MIT licensed and v1.0.0 just shipped.

What you need

A Mac with Apple Silicon (M1 or newer). Python 3.12, which setup installs for you. Claude Code, which the installer adds if it's missing.

Which model for your RAM

You don't have to pick. Setup looks at your Mac's memory and chooses a model that fits:

On the small Macs, the speeds we measured on an M4 Pro were 22 tokens a second for the 4B model and 92 for the 2B. Both passed our Claude Code test: read a file, fix a bug with Edit, run a script, describe an image. The full numbers and settings are in docs/SMALL-MACS.md.

On the big end, Qwen 3.8 27B passed our Claude Code test (write a file, run it, report) in 38 seconds. We also score models on our open Agent-12 leaderboard, where it got 12/12 easy and 7/8 hard. Those scores come from Agent-12's own harness, not from inside Claude Code, and Claude Code sends the model a lot more per turn.

A local model is not Claude Opus, and I won't pretend it is. Big models on a 64 GB or 96 GB Mac handle real multi step work. On 8 or 16 GB, keep requests to one clear step at a time.

Install it in one line

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

If you'd rather 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 on your own machine.

If you get asked to sign in to a Claude account, your claude is too old. Update it with curl -fsSL https://claude.ai/install.sh | bash.

Doing it by hand comes down to this. Start the server, then launch Claude Code against it:

ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_API_KEY=sk-local \
claude --model claude-sonnet-4-6

The key is just sk-local. The server never checks it.

Hit your limit? Type exit, keep going

Say Claude Code says "5-hour limit reached" or "You've reached your weekly limit", or your API key comes back with "credit balance is too low", and the reset is hours away.

Type exit in Claude Code, then type keep going. You get a short menu, and the same conversation carries on with whichever model you pick. The options are the models on your machine, sized to your memory, or free cloud models from OpenRouter if you add a free key:

mkdir -p ~/.config/claude-code-local
echo 'OPENROUTER_API_KEY=your-free-key' >> ~/.config/claude-code-local/keepgoing.env

The cloud key is optional. Free cloud models can get busy later in the day, and the models on your Mac are always there.

When your limit resets, just run plain claude again. The install never changes it, so it still uses your Claude plan.

You can also make the switch automatic. Add one hook to Claude Code and the moment you hit your limit, a new window opens in the same folder and carries on without a menu. Setup is in docs/AUTO-HANDOFF.md.

Linux and Windows

Off a Mac there's no MLX, so the model runs on llama.cpp instead. The installer looks at your hardware (NVIDIA, AMD, or just your CPU), grabs a pinned llama.cpp build, and picks a vision model that fits. A 24 GB NVIDIA card gets Qwen 3.5 9B at full BF16, for example.

Linux uses the same one liner as the Mac. On Windows, in PowerShell:

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

You need git, Python 3 and Claude Code installed. Then run claude-local on Linux, or double click Claude Local on your Windows Desktop. keep going works there too.

Private and offline

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

Claude Code itself makes some background calls to Anthropic, so the launchers switch them off with Anthropic's documented settings:

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

You can check it yourself. During a session, run:

lsof -a -i -p "$(pgrep -d, -f claude)"

That lists the network connections of every Claude process, and the only one is localhost:4000. Because the model runs on your machine, an Anthropic outage doesn't stop it either.

The one exception is your own choice. If you pick a free cloud model in keep going, that conversation goes to OpenRouter.

Links

The repo: https://github.com/nicedreamzapp/claude-code-local

How to guides and docs: https://nicedreamzapp.github.io/claude-code-local/

The demo: https://www.youtube.com/watch?v=a9vtBSl_j_o

If you run it on an 8 GB or 16 GB Mac, tell us how it goes in issue #57. I especially want to hear from people on older or smaller Macs about which models really fit.