Skip to content

Quickstart

This assumes you ran the installer.

1. Double-click the launcher

Open Claude Local.command on your Desktop. It:

  1. Starts the server with the model setup.sh picked, unless something is already listening on port 4000.
  2. Waits until http://localhost:4000/health answers.
  3. Opens Claude Code with ANTHROPIC_BASE_URL=http://localhost:4000, ANTHROPIC_API_KEY=sk-local and --model claude-sonnet-4-6.

The model name is only a label Claude Code needs; the server answers with whatever model it loaded and echoes the name back. sk-local is a placeholder, the server never checks it.

Ask it something small first, like "list the files in this folder". The first reply is the slowest: the model is loading into memory and the first prompt has to be prefilled. See Troubleshooting if it takes minutes.

2. Or start it from a terminal

# Terminal 1: the server (default model is Gemma 4 31B 4-bit)
bash ~/claude-code-local/scripts/start-mlx-server.sh
# or pick a model:
bash ~/claude-code-local/scripts/start-mlx-server.sh divinetribe/Hermes-4-14B-abliterated-4bit-mlx

# Terminal 2: Claude Code
cd ~/your-project
ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_API_KEY=sk-local \
claude --model claude-sonnet-4-6

The server prints its settings on start, then logs every request to stderr. Launchers send that log to /tmp/mlx-server.log.

3. Check the server

curl -s http://localhost:4000/health

returns JSON like

{"status": "ok", "model": "divinetribe/gemma-4-31b-it-abliterated-4bit-mlx",
 "prefill_size": 512, "rss_gb": 16.9, "mx_active_gb": 16.7,
 "mx_cache_gb": 0.0, "mx_peak_gb": 17.2}

The field names are real; the numbers here are illustrative. mx_peak_gb is the one to watch for memory pressure. A comment in the server explains that ps RSS cannot see Metal buffers, so RSS can look calm right before the Mac starts swapping.

4. Check that nothing leaves the Mac

During a session:

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

This lists the network connections of every Claude process. The README states the only one should be localhost:4000.

TODO-VERIFY: which launchers switch off Claude Code's background traffic

The README says the launchers set four Anthropic environment variables that stop Claude Code's own background traffic (CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_AUTOUPDATER, CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS). In the code, only Claude Chat.command, Claude Agentico.command and the local path of keep going set them. Claude Local.command, Gemma 4 Code.command, Qwen 3.8 Code.command, Narrative Gemma.command and the Desktop launcher generated by setup.sh do not. To be safe, export them yourself:

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 DISABLE_AUTOUPDATER=1 \
       CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

The server itself binds to 127.0.0.1 only, so other machines on your network cannot reach it.

5. Switch models

Every launcher reads MLX_MODEL. If a server with a different model is already running, the launcher stops it and starts the one you asked for:

MLX_MODEL=lmstudio-community/Qwen3.8-27B-MLX-8bit bash ~/claude-code-local/launchers/"Claude Local.command"

(Run it with bash from a terminal. Double-clicking or open does not pass your shell's environment variables to the launcher.)

Or use the model-specific launchers in launchers/: Gemma 4 Code.command, Qwen 3.8 Code.command. A model you have not downloaded yet is pulled from Hugging Face on first launch. All launchers are listed in Configuration.

6. Try the Native Engine

The Native Engine skips Claude Code entirely: one Python file loads the model in-process and runs a small coding agent in your terminal with the same six tools (Bash, Read, Write, Edit, Glob, Grep).

cd ~/your-project
AGENT_MODEL=divinetribe/gemma-4-31b-it-abliterated-4bit-mlx AGENT_DIALECT=prompted \
  ~/.local/mlx-server/bin/python3 ~/claude-code-local/agent/agent.py

Or double-click Gemma 4 Code (Native Engine).command or Qwen 3 Coder (Native Engine).command. Note these two launchers cd to your home folder before starting. Inside the agent, /context shows how full the context window is, /reset clears the conversation and /exit quits.

7. Out of Claude credits? keep going

When cloud Claude runs out mid-task, type exit in Claude Code and then, in the same folder:

keep going

You get a menu of free OpenRouter models (if you added a key) and local models that fit your Mac's memory. Pick one and the same conversation resumes with claude --resume. Details in Configuration.

Note

Picking a free cloud model sends that conversation to OpenRouter. Only the local choices keep it on the Mac.