Utiliser Claude Code avec un modele local sur votre Mac

Claude Code est genial. Mais devrait-il voir vos secrets ?

Si vous avez utilise Claude Code, vous savez que c’est l’un des meilleurs outils de code agentique disponibles. Il lit votre codebase, edite des fichiers, lance les tests et itere jusqu’a ce que le travail soit fait. Mais chaque token passe par l’API d’Anthropic — ce qui signifie que votre code, vos variables d’environnement et tout ce que l’agent touche quitte votre machine.

Maintenant imaginez lui dire : “deploie ca en production.” Il va executer kubectl apply, gh pr merge, terraform apply. Il va lire votre ~/.kube/config, vos credentials AWS, vos fichiers .env. Tout ce contexte part vers une API externe. Etes-vous a l’aise avec ca ?

Et si vous pouviez garder le harnais — l’utilisation d’outils, la planification multi-etapes, la recuperation d’erreurs — mais remplacer le cerveau par un modele local ou rien ne quitte votre machine ?

C’est exactement ce que j’ai construit : claude-code-local-mlx.

Une commande, zero config

uv tool run --from git+https://github.com/GuillaumeBlanchet/claude-code-local-mlx.git claude-local

C’est tout. Au premier lancement :

1. Clone un serveur proxy leger (claude-code-mlx-proxy)
2. Telecharge le modele depuis HuggingFace (en cache apres la premiere fois)
3. Demarre le proxy sur un port local
4. Lance Claude Code pointe vers votre modele local

Aux lancements suivants, si le modele est deja charge, il passe directement a Claude Code. Pas de fichiers de config, pas de Docker, pas de gymnastique avec les variables d’environnement.

Pour l’installer definitivement :

uv tool install git+https://github.com/GuillaumeBlanchet/claude-code-local-mlx.git
claude-local

Pourquoi MLX et pas Ollama ?

Bonne question. Ollama supporte maintenant Claude Code nativement — vous pouvez faire ollama launch claude --model qwen3.5 et ca marche. Si vous voulez la configuration la plus simple possible, Ollama est un bon choix.

Mais cet outil utilise mlx-lm directement, et il y a des raisons mesurables :

	Ollama	mlx-lm (cet outil)
Configuration	Une commande	Une commande
Format de modele	GGUF (llama.cpp)	Safetensors MLX natif
Vitesse d’inference	~112 tok/s	~130 tok/s
Overhead memoire	Plus eleve (HTTP + conversion GGUF)	Plus bas (zero-copy, in-process)
Choix de modeles	Registre Ollama	Tout modele mlx-community/ sur HuggingFace

Benchmark : Qwen3.5-35B sur M4 Max. Source : antekapetanovic.com

La difference de ~15-20% en vitesse vient de l’elimination de la couche HTTP/JSON et de l’utilisation de modeles MLX natifs qui se chargent directement dans la memoire unifiee d’Apple Silicon sans copie. Pour un agent de code qui fait des centaines d’appels par session, ca s’accumule.

Quel modele choisir ?

Le modele par defaut est mlx-community/Qwen3-Coder-Next-8bit, un modele Mixture-of-Experts de 80B avec seulement 3B de parametres actifs par token — rapide et intelligent. Mais il consomme 79 Go de RAM a l’execution (pas les 45 Go que la taille du fichier suggere), donc il faut une machine de 96+ Go.

Voici mes recommandations par palier de RAM, avec la memoire reelle et la vitesse mesurees sur M4 Max :

RAM	Modele	RAM reelle	tok/s	Comparable a
8 Go	Qwen2.5-Coder-3B 4-bit	~3-4 Go	~200	GPT-3.5 Turbo
16 Go	Qwen2.5-Coder-7B 4-bit	~7-8 Go	~90	GPT-4o-mini
24 Go	Gemma-4-26B-A4B 4-bit	~17-20 Go	~110	GPT-4o (code gen)
32 Go	Qwen2.5-Coder-32B 4-bit	~25-30 Go	~14-30	GPT-4o (edition)
48 Go	Qwen3-Coder-Next 4-bit	~40-46 Go	~40-60	Claude Sonnet 4
64 Go	Qwen2.5-Coder-32B 8-bit	~33 Go	~10-14	GPT-4o (sans perte)
96 Go	Qwen3-Coder-Next 8-bit	~79 Go	~35-50	Claude Sonnet 4
128 Go	Devstral-2-123B 4-bit	~72-90 Go	~5-8	GPT-4.1

Pour utiliser un autre modele :

claude-local -m mlx-community/Qwen2.5-Coder-32B-Instruct-4bit

Attention aux estimations de RAM

Ne faites pas confiance a la “taille du fichier modele” comme estimation de RAM. Les poids sur disque ne sont qu’une partie de l’equation. A l’execution, le cache KV (qui grossit avec la longueur du contexte), le tokenizer et l’overhead du framework peuvent ajouter 50-80% en plus. J’ai appris ca a la dure quand Qwen3-Coder-Next-8bit (45 Go sur disque) a consomme 79 Go de RAM reelle sur mon M4 Max.

Le boost du harnais : pourquoi les benchmarks sous-estiment votre modele local

Voici ce que la plupart des gens manquent : les benchmarks de code (Aider, SWE-bench, HumanEval) testent les modeles avec un echafaudage basique — une simple boucle “lire le prompt, generer du code, verifier”. Claude Code est bien plus sophistique : il a l’utilisation d’outils, l’edition iterative de fichiers, l’acces au shell, la planification multi-etapes et la recuperation d’erreurs.

La recherche montre que le harnais compte plus que le modele a la frontiere :

Etude	Echafaudage basique	Echafaudage optimise	Gain
Claude Opus 4.5 sur CORE-Bench	42%	78% (avec Claude Code)	+36 pts
Agent LangChain	52.8%	66.5%	+14 pts
SWE-bench Pro	~1 pt entre modeles	~22 pts entre harnais	Harnais >> Modele

Source : Particula

Donc un Qwen2.5-Coder-32B qui benchmark comme GPT-4o en isolation ? Avec le harnais agentique de Claude Code, il peut performer plus pres de Claude Sonnet 4 en pratique. Le modele fournit l’intelligence ; le harnais la multiplie.

Comment ca marche sous le capot

Claude Code  ──  Anthropic Messages API  ──>  mlx-proxy  ──  Inference MLX  ──>  Modele local
  (CLI)      <──     /v1/messages        ──  (port 18808) <──    tokens     ──  (GPU Apple)

Claude Code necessite l’API Anthropic Messages (/v1/messages). Les modeles locaux ne parlent pas ce protocole. Le proxy fait le pont : il accepte les requetes au format Anthropic, les traduit en appels MLX, et renvoie les reponses dans le format attendu.

L’outil gere tout le cycle de vie :

• Clone le depot proxy
• Met a jour les dependances (le depot upstream peut figer d’anciennes versions de mlx-lm)
• Patche le proxy pour accepter le mode de reflexion "adaptive" de Claude Code
• Demarre le proxy, attend le endpoint sante, puis exec dans Claude Code avec les bonnes variables d’environnement
• Reutilise un proxy existant s’il est deja fonctionnel (pas de rechargement de modele aux lancements suivants)

Conseils pratiques

Arreter le proxy quand vous avez fini :

claude-local --kill

Forcer un redemarrage (ex: pour changer de modele) :

claude-local --restart -m mlx-community/Gemma-4-26b-a4b-it-4bit

Mode proxy seul (si vous voulez utiliser Claude Code separement) :

claude-local --server
# Puis dans un autre terminal :
ANTHROPIC_BASE_URL=http://127.0.0.1:18808 claude

Consulter les logs si ca casse :

cat ~/.local/state/claude-mlx-proxy.log

Le cas d’usage decisif : le DevOps sans fuiter vos secrets

C’est le cas d’usage qui m’a convaincu de construire cet outil.

Quand Claude Code execute un kubectl get pods, un gh pr create ou un terraform plan, la sortie complete — incluant les noms de clusters, les namespaces, les configurations de ressources et les messages d’erreur — est envoyee a l’API comme contexte. Quand il lit votre .env pour comprendre un deploiement, vos URLs de base de donnees, cles API et credentials cloud sont dans la conversation. Quand il se connecte a votre environnement de staging, la sortie de session traverse le reseau.

Avec un modele local, rien de tout ca ne quitte votre machine. Le modele tourne sur votre GPU, le proxy tourne sur localhost, et vos secrets restent dans votre RAM. Vous pouvez laisser l’agent faire kubectl apply -f deployment.yaml sans vous soucier du contexte qu’il envoie a un serveur tiers.

Et voici le point cle : vous n’avez pas besoin d’une intelligence de classe GPT-4 pour les taches DevOps. Executer gh pr merge, kubectl rollout restart ou docker compose up ne demande pas un raisonnement profond. Un modele 7B peut suivre des instructions, lire la sortie de commandes et reessayer en cas d’erreur. Meme les plus petits modeles du tableau ci-dessus peuvent gerer :

• Les workflows gh — creer des PRs, merger, verifier les checks
• Les operations kubectl — deployer, scaler, verifier l’etat des pods, lire les logs
• docker compose — demarrer les services, verifier la sante, rebuilder
• terraform / tofu — planifier, appliquer, lire l’etat
• Le debogage CI/CD — lire les logs de build, corriger le YAML, relancer les pipelines

Pour ces taches, pas besoin d’un modele frontiere. Un Qwen3-Coder-Next de 80B tournant localement sur un Mac 96 Go offre des performances de classe Claude Sonnet 4 a ~40 tok/s — et avec un budget plus serre, meme un modele 32B sur un MacBook Pro 32 Go gere bien les workflows DevOps. Dans tous les cas, infiniment plus securitaire que d’envoyer vos credentials cloud a travers une API externe.

L’argument securite en une phrase

Si votre agent IA peut faire kubectl exec dans votre cluster de production, vous ne voulez probablement pas que son cerveau soit heberge par un tiers.

Conclusion

Utiliser Claude Code avec un modele local, ce n’est pas juste pour economiser — c’est une question de securite. Vos secrets, vos credentials cloud, l’etat de votre infrastructure — rien de tout ca n’a besoin de quitter votre machine pour qu’un agent IA soit utile.

L’ecart de qualite des modeles se reduit rapidement. Un Qwen3-Coder-Next bien harnache sur un MacBook Pro performe dans la meme ligue que des modeles commerciaux qui coutent des centaines de dollars par mois. Et avec la memoire unifiee d’Apple Silicon qui donne un avantage structurel a MLX, votre Mac est en train de devenir discretement l’une des meilleures machines de developpement IA que vous puissiez acheter.

Essayez :

uv tool run --from git+https://github.com/GuillaumeBlanchet/claude-code-local-mlx.git claude-local

Le depot est sur github.com/GuillaumeBlanchet/claude-code-local-mlx. Les PRs sont bienvenues.