cd /news/ai-tools/pairing-claude-code-with-local-model… · home › topics › ai-tools › article
[ARTICLE · art-25295] src=kdnuggets.com pub= topic=ai-tools verified=true sentiment=↑ positive

Pairing Claude Code with Local Models

Ollama, LM Studio, and llama.cpp now support native Anthropic Messages API connections, enabling Claude Code to run entirely on local models for code completion, refactoring, and debugging tasks. By setting environment variables like `ANTHROPIC_BASE_URL` and model tier mappings, developers can redirect Claude Code's API calls to local inference servers, eliminating per-token costs and rate limits. The setup requires at least 16 GB RAM and Ollama v0.14.0 or later for Anthropic API compatibility.

read15 min publishedJun 12, 2026

Local models in 2026 are good enough. For the tasks Claude Code handles daily: code completion, refactoring, debugging, codebase explanation; a well-chosen quantized model running locally covers the vast majority of real use cases at zero per-token cost and with no rate limits.

# Introduction #

Agentic coding sessions are expensive. A single Claude Code session — reading files, writing code, running tests, iterating — can burn 10–50x more tokens than a plain chat conversation. At scale, that adds up fast. Add rate limits that can interrupt a long-running workflow mid-session, and the dependency on a third-party API that can change pricing, enforce stricter policies, or go down at any point, and the case for local inference becomes straightforward.

Local models in 2026 are good enough. For the tasks Claude Code handles daily — code completion, refactoring, debugging, codebase explanation — a well-chosen quantized model running locally covers the vast majority of real use cases at zero per-token cost and with no rate limits. This article covers three inference backends (** Ollama**,

, and

LM Studio), the exact environment variables and configuration files to wire each one to Claude Code, a curated table of models worth running, and the troubleshooting fixes for the issues you will actually hit.

llama.cpp

# How Claude Code Connects to Any Local Model #

The mechanism is simpler than most guides make it look. Claude Code sends requests in the Anthropic Messages API format. By default those requests go to Anthropic's servers. Setting ANTHROPIC_BASE_URL

redirects them to any server that speaks the same format, which now includes Ollama, LM Studio, and llama.cpp natively.

According to the official Claude Code environment variables documentation, the variables that matter for this setup are:

ANTHROPIC_BASE_URL

: redirects all API calls from Anthropic's servers to whatever URL you set. Set this to your local inference server address.ANTHROPIC_API_KEY

: the API key sent in the request header. Local servers typically ignore authentication, so this is usually set to a placeholder string like "local" or "** ollama**."ANTHROPIC_AUTH_TOKEN

: an alternative auth header. Some local servers check for this instead of the API key. Set it to the same placeholder.

ANTHROPIC_DEFAULT_SONNET_MODEL

, ANTHROPIC_DEFAULT_HAIKU_MODEL

, and ANTHROPIC_DEFAULT_OPUS_MODEL

: Claude Code internally requests different model tiers depending on the task. These three variables map each tier to your local model's name. Without them, Claude Code sends requests for claude-sonnet-4-20250514

to your local server, which will reject the request because no such model exists locally.

In January 2026, Ollama added native support for the Anthropic Messages API, which was the technical change that made this workflow practical without translation proxies. LM Studio added a native /v1/messages

endpoint in version 0.4.1. llama.cpp has had direct Anthropic API support for longer. All three now speak Claude Code's native protocol.

A clean architecture diagram showing Claude Code, Ollama, LM Studio, and llama.cpp | Image by Author

# Backend 1: Ollama #

Ollama is the right starting point. It handles all the complexity of model management — down weights, quantization, GPU and CPU allocation, and serving — behind a simple command-line interface (CLI). One command to install, one command to pull a model, a few environment variables to configure. It runs as a background service after install, so there is no manual server start required.

Prerequisites

  • macOS, Linux, or Windows (WSL2 recommended on Windows)
  • At least 16 GB RAM for practical use (32 GB recommended)
  • GPU with 8+ GB VRAM for GPU inference, or CPU-only with enough RAM
  • Ollama v0.14.0 or later required for Anthropic Messages API support

Install Ollama:

curl -fsSL https://ollama.com/install.sh | sh

ollama version

After installation, Ollama starts automatically as a background service on port 11434. You can verify it is running:

curl http://localhost:11434

Pull a coding model:

ollama pull glm-4.7-flash:latest

ollama pull qwen3-coder

ollama pull devstral-small-2:24b

ollama list

// Configuring Claude Code to Use Ollama

Option 1: Shell export (current terminal session only)

export ANTHROPIC_BASE_URL="http://localhost:11434"

export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_AUTH_TOKEN="ollama"

export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash:latest"

claude

Option 2: ~/.claude/settings.json (permanent, applies to all sessions)

This approach survives terminal restarts and applies every time you launch Claude Code. Claude Code reads environment variables from settings.json

at startup so they take effect no matter how claude

was launched.

Create or edit ~/.claude/settings.json

:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_API_KEY": "ollama",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7-flash:latest"
  }
}

Option 3: .env file in project directory (per-project override)

If you want a specific project to use a different model while keeping your global settings on the Anthropic API:

ANTHROPIC_BASE_URL=http://localhost:11434
ANTHROPIC_API_KEY=ollama
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder
ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder
ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder

Verify the connection:

claude


claude --verbose

Full working sequence from scratch:

curl -fsSL https://ollama.com/install.sh | sh          # 1. Install Ollama
ollama pull glm-4.7-flash:latest                       # 2. Pull model (~4 GB)
export ANTHROPIC_BASE_URL="http://localhost:11434"     # 3. Redirect Claude Code
export ANTHROPIC_API_KEY="ollama"                      # 4. Set placeholder auth
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash:latest"
claude                                                  # 5. Launch

# Backend 2: LM Studio #

LM Studio is the right choice if you want a graphical interface for browsing and managing models rather than working entirely in the terminal. Since version 0.4.1, it includes a native Anthropic-compatible /v1/messages endpoint — the same path Claude Code expects — so no translation layer or proxy is needed.

Prerequisites:

  • macOS, Windows, or Linux
  • GPU with 6+ GB VRAM recommended (CPU-only is possible but slow)
  • Download from lmstudio.ai or use the CLI installer for headless servers

Install and configure LM Studio:

curl -fsSL https://releases.lmstudio.ai/cli/install.sh | bash

GUI setup steps:

  • Open LM Studio and search for a coding model (search "qwen coder" or "devstral").
  • Download the model. LM Studio handles quantization selection automatically.
  • Go to the Local Server tab (the<>

icon in the left sidebar). - Set the context size. LM Studio recommends starting with at least 25,000 tokens and increasing for better results.

  • Click Start Server. - Note the port (default: 1234) and copy the model name exactly as shown.

Note: Copy the model identifier exactly. LM Studio displays the exact string you need to pass to

ANTHROPIC_DEFAULT_SONNET_MODEL

. A mismatch here is the most common failure mode.

Configure Claude Code:

export ANTHROPIC_BASE_URL="http://localhost:1234"
export ANTHROPIC_API_KEY="lm-studio"
export ANTHROPIC_AUTH_TOKEN="lm-studio"

export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen2.5-coder-32b-instruct"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen2.5-coder-32b-instruct"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen2.5-coder-32b-instruct"

Or persistently in ~/.claude/settings.json

:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:1234",
    "ANTHROPIC_API_KEY": "lm-studio",
    "ANTHROPIC_AUTH_TOKEN": "lm-studio",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen2.5-coder-32b-instruct",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen2.5-coder-32b-instruct",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen2.5-coder-32b-instruct"
  }
}

How to run:

export ANTHROPIC_BASE_URL="http://localhost:1234"
export ANTHROPIC_API_KEY="lm-studio"
export ANTHROPIC_AUTH_TOKEN="lm-studio"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-model-name-here"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="your-model-name-here"
export ANTHROPIC_DEFAULT_OPUS_MODEL="your-model-name-here"
claude

# Backend 3: llama.cpp #

llama.cpp is the right choice when you need direct control over inference parameters — quantization type, KV cache configuration, batch size, thread count — or when you are running on a server and want the lowest overhead. It has native Anthropic Messages API support, so no proxy or translation layer is needed.

Prerequisites:

  • A GGUF-format model file (download from Hugging Face; search for "GGUF" versions of any model)
  • CUDA-capable GPU for GPU inference, or CPU-only for slower inference
  • CMake and a C++ compiler for source builds (on Linux/CUDA, source is recommended)

Install llama.cpp:

brew install llama.cpp

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON          # Enable CUDA acceleration
cmake --build build --config Release   # Build

cmake -B build
cmake --build build --config Release

Download a GGUF model:

pip install huggingface-hub

huggingface-cli download unsloth/GLM-4.7-Flash-GGUF \
  GLM-4.7-Flash-UD-Q4_K_XL.gguf \
  --local-dir ./models/

huggingface-cli download Qwen/Qwen3-Coder-32B-Instruct-GGUF \
  qwen3-coder-32b-instruct-q4_k_m.gguf \
  --local-dir ./models/

Start the llama.cpp server:

llama-server \
  --model ./models/GLM-4.7-Flash-UD-Q4_K_XL.gguf \
  --alias "glm-4.7-flash" \          # This name goes in ANTHROPIC_DEFAULT_SONNET_MODEL
  --port 8001 \
  --ctx-size 131072 \                # 128K context -- important for large codebases
  --flash-attn \                     # Memory-efficient attention, improves speed
  --n-gpu-layers 99                  # Offload all layers to GPU; remove for CPU-only

llama-server \
  --model ./models/GLM-4.7-Flash-UD-Q4_K_XL.gguf \
  --alias "glm-4.7-flash" \
  --port 8001 \
  --ctx-size 32768 \                 # Reduce context size on CPU to keep memory manageable
  --threads 8                        # Match your CPU core count

Key flags explained:

--alias

: the model name string Claude Code will send in requests. SetANTHROPIC_DEFAULT_SONNET_MODEL

to match this exactly.--ctx-size

: context window in tokens.131072 = 128K. Larger is better for codebase analysis but uses more VRAM. Reduce if you get out-of-memory errors.--flash-attn

: Flash Attention reduces peak VRAM by processing attention in smaller blocks. Enable it whenever your build supports it.--n-gpu-layers 99

: offloads all transformer layers to the GPU. The server automatically uses fewer layers if VRAM is tight.

Configure Claude Code:

export ANTHROPIC_BASE_URL="http://localhost:8001"
export ANTHROPIC_API_KEY="llama-cpp"
export ANTHROPIC_AUTH_TOKEN="llama-cpp"

export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash"

How to run:

llama-server \
  --model ./models/GLM-4.7-Flash-UD-Q4_K_XL.gguf \
  --alias "glm-4.7-flash" \
  --port 8001 \
  --ctx-size 131072 \
  --flash-attn \
  --n-gpu-layers 99

export ANTHROPIC_BASE_URL="http://localhost:8001"
export ANTHROPIC_API_KEY="llama-cpp"
export ANTHROPIC_AUTH_TOKEN="llama-cpp"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash"
claude

# The Complete settings.json #

Environment variable exports last only as long as the terminal session. For a durable configuration, use ~/.claude/settings.json

. Claude Code reads variables from this file at startup so they apply no matter how Claude was launched — from the terminal, from a VS Code task, or from a script.

Here is a production-ready settings.json

with all variables explained:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",

    "ANTHROPIC_API_KEY": "ollama",
    "ANTHROPIC_AUTH_TOKEN": "ollama",

    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash:latest",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7-flash:latest",

    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Why CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: "1" matters:

When using Claude Code through non-Anthropic backends, Claude Code adds Anthropic-specific experimental beta flags to request headers — flags that third-party and local servers do not recognize. This causes Error: Unexpected value(s) for the anthropic-beta header

on most local inference servers. Setting this variable to "1"

strips those headers before the request goes out, which eliminates the error without affecting any core Claude Code functionality.

Switching between backends:

If you work with multiple backends — Ollama for daily use, the Anthropic API for complex tasks — the cleanest approach is maintaining separate shell scripts rather than editing settings.json

back and forth:

export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash:latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7-flash:latest"
echo "Claude Code → local Ollama (glm-4.7-flash)"
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_DEFAULT_SONNET_MODEL
unset ANTHROPIC_DEFAULT_HAIKU_MODEL
unset ANTHROPIC_DEFAULT_OPUS_MODEL
echo "Claude Code → Anthropic API"

Source either script in your current session:

source ./use-local.sh
claude

source ./use-anthropic.sh
claude

# Best Local Models for Claude Code in 2026 #

Hardware is the main constraint. For Claude Code with local models to be genuinely usable for coding tasks rather than just a demo, aim for 32 GB of RAM — Apple Silicon unified memory or PC RAM. 16 GB is viable with smaller quantized models and CPU offload, but generation speed will be noticeably slower on multi-step agentic tasks.

Model | VRAM Needed | Context | Strengths | License | Pull Command | |---|---|---|---|---|---| |

ollama pull glm-4.7-flash

devstral-small-2:24bollama pull devstral-small-2:24b

qwen3-coderollama pull qwen3-coder

qwen3.5:27bollama pull qwen3.5:27b

gemma4:26bollama pull gemma4:26b

# Troubleshooting Common Issues #

Connection refused when launching Claude Code: The inference server is not running. This is the most common issue and the easiest to diagnose.

curl http://localhost:11434

curl http://localhost:1234/v1/models

curl http://localhost:8001/health

ollama serve          # Ollama

Model not found or unknown model error: The model name in yourANTHROPIC_DEFAULT_SONNET_MODEL

does not match what the server knows.

ollama list


curl http://localhost:11434/v1/models

Tool calls failing or returning errors: For streaming tool calls, which Claude Code uses when executing functions or scripts, Ollama version 0.14.3-rc1 or later is required. Earlier versions in the 0.14.x series had incomplete streaming tool call support.

ollama version

curl -fsSL https://ollama.com/install.sh | sh

anthropic-beta

header error:You will see:

Error: Unexpected value(s) for the anthropic-beta header

. This happens because Claude Code adds Anthropic-specific experimental beta flags that local servers do not recognize. Fix it by adding this to yoursettings.json

env block:

"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"

Reverting to the Anthropic API:

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_DEFAULT_SONNET_MODEL
unset ANTHROPIC_DEFAULT_HAIKU_MODEL
unset ANTHROPIC_DEFAULT_OPUS_MODEL

echo $ANTHROPIC_API_KEY

Slow generation speed: For agentic Claude Code tasks, generation speed matters because each tool call is a round trip. If speed is inadequate:- Switch to a smaller or more aggressively quantized model (Q4_K_M instead of Q8).

  • Enable --flash-attn

in llama.cpp if not already set. - Reduce context size ( --ctx-size

); larger contexts are slower to prefill. - On Ollama, set OLLAMA_NUM_GPU_LAYERS=99

in your environment to force maximum GPU offload.

# Conclusion #

What used to require fragile adapters and hacks is now a five-step process. Install the inference backend, pull a model, set three environment variables, and Claude Code routes to your local machine instead of Anthropic's API. The configuration takes under five minutes once you have the model downloaded.

The practical result is a coding assistant that costs nothing to run after setup, has no rate limits, keeps your code entirely on your machine, and covers the vast majority of real coding use cases at quality levels that were not available in local models a year ago. Start with Ollama and glm-4.7-flash

— it has the lowest hardware requirement, the most consistent tool-calling support, and the fastest path to a working setup. Once that is running, scale up the model based on your hardware and the quality level you actually need.

is a software engineer and technical writer passionate about leveraging cutting-edge technologies to craft compelling narratives, with a keen eye for detail and a knack for simplifying complex concepts. You can also find Shittu on

Shittu Olumide

source & further reading
kdnuggets.com — original article 3 NumPy Tricks for Numerical Performance Feature Stores from Scratch: A Minimal Working Implementation Local Agentic Programming on the Cheap: Claude Code + Ollama + Gemma4
── more in #ai-tools 4 stories · sorted by recency
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/pairing-claude-code-…] indexed:0 read:15min 2026-06-12 · —