nicedreamzapp/claude-code-local

Claude Code Local – Run Anthropic‑style coding AI on your Mac

What it is

• A tiny Python server that talks the same Anthropic Messages API that Claude Code expects, but runs local LLMs on Apple‑Silicon Macs via the MLX runtime.
• The server translates the tool‑call format of models like Gemma 4, Qwen 3.8 or Llama‑JSON into the format Claude Code understands, caches prompts, and streams responses back to the editor.

Why you might care

• No cloud, no API key, and your source files never leave the machine – great for privacy‑sensitive coding.
• Works on a 16 GB MacBook and scales up to the 128 GB M‑series, automatically picking a model that fits your RAM.
• Provides a drop‑in replacement for Claude Code’s default cloud backend, so the UI and workflow stay exactly the same.

Key components

Component	Role
proxy/server.py	The MLX‑based inference server; implements Anthropic‑compatible endpoints, handles streaming, tool‑call conversion, and prompt‑cache reuse.
agent/agent.py	A lightweight “Native Engine” – a one‑file terminal coding agent that uses a short system prompt to keep the cache alive across turns.
bin/keepgoing*	Finds the last Claude Code session and lets you continue it with a free cloud model or another local model when you run out of Claude credits.
install.sh, setup.sh, scripts/doctor.sh	Detect your Mac’s memory, download the appropriate model (Gemma 4 E4B, Hermes 4, Gemma 12/31B, Qwen 3.8, etc.), install the MLX Python environment, and create a desktop launcher.
launchers/	Double‑clickable scripts that start Claude Code pointing at the local server, plus variants for the Native Engine, browser‑driven agent, voice mode, and phone control.

How it works (high‑level flow)

Your editor (Claude Code) → HTTP request to http://localhost:4000 (this repo’s server) →
MLX runtime executes the selected model on the Apple GPU → response streamed back to Claude Code

The server speaks Claude Code’s API directly, avoiding the slower “OpenAI‑style” translators used by many other local‑AI setups.

Getting started

1. Run the one‑liner installer:

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

2. The script picks a model based on your RAM, downloads it, and drops a Claude Local.command shortcut on your Desktop.
3. Double‑click the shortcut, launch Claude Code as usual, and the AI responses will now be generated locally.

Supported models (chosen automatically, but you can swap them):

• Qwen 3.8 27B – best for 96 GB+ Macs, 8‑bit MLX build.
• Gemma 4 31B – fast on 64‑95 GB Macs.
• Gemma 4 12B – fits 32‑63 GB Macs.
• Hermes 4 14B – runs on 16 GB Macs.
• Community‑provided builds (Muse Glimmer, Nemotron 3 Nano Omni) are listed for reference.

Extending the setup

• Use the Native Engine launcher for a super‑fast terminal‑only coding assistant.
• Combine with the author’s other repos (Trinidad Head terminal, browser‑agent, voice‑mode, phone control) for a full “local‑first” AI workstation.
• If you prefer a different local server, the README notes alternatives like Ollama, claude‑code‑router, or claude‑code‑proxy.

Privacy & security

• All traffic is confined to localhost; lsof shows only the local port in use.
• The project disables Claude Code’s background telemetry and marketplace auto‑install via environment flags.
• No external dependencies make network calls except when you deliberately choose a free cloud model via the keep‑going menu.

License

• MIT – you can freely modify, redistribute, or embed the server in your own workflows.

Bottom line Claude Code Local gives you the same Claude Code coding‑assistant experience while keeping the heavy LLM inference on‑device, leveraging Apple Silicon’s GPU via MLX. It’s a practical, privacy‑first bridge between Anthropic‑style tooling and the growing ecosystem of open‑source local models.