Want to try an AI coding agent without sending your project to a hosted model? This guide connects Claude Code to a local Ollama model. Commands are provided for Windows CMD, PowerShell, Linux and macOS.
Our test setup: Windows, 8 GB RAM, Ollama, Claude Code and
qwen2.5-coder:1.5b. Results and limitations from this setup are called out separately.
What you’ll do: install the tools → download a model → connect Claude Code → test a real file operation.
[SCREENSHOT 1 — Final terminal setup or a simple diagram: Claude Code → Ollama → local model]
1. Install Ollama
Ollama runs the model locally. Use the command for your operating system, or use the official download page for a manual installer.
Windows — PowerShell (run PowerShell, not CMD):
irm https://ollama.com/install.ps1 | iex Windows — CMD / manual installation:
CMD does not run the PowerShell command above. Download and run the Windows installer from ollama.com/download, then reopen CMD.
macOS or Linux — Terminal:
curl -fsSL https://ollama.com/install.sh | sh Manual installers and Linux-specific instructions: Ollama downloads · Linux manual install.
2. Install Claude Code
Windows — PowerShell:
irm https://claude.ai/install.ps1 | iex macOS / Linux — Terminal:
curl -fsSL https://claude.ai/install.sh | bash Official instructions: Claude Code setup.
3. Verify the commands
Close and reopen the terminal, then run:
ollama --version claude --version If a command is not found, reopen the terminal first. If it still fails, check that the installer completed and that the executable is on your PATH.
4. Download and test the local model
For this experiment, we used a small coding model to fit a computer with 8 GB RAM:
ollama pull qwen2.5:1.5b 
Run the model and ask a simple question to confirm that it responds, then type /bye to exit the model chat.
ollama run qwen2.5:1.5b 
Check installed models with:
ollama list 
The first download needs an internet connection. After the model is downloaded, inference runs on the local machine. Speed and quality depend on your hardware and the model.
5. Connect Claude Code to Ollama
There are two methods. Start with Method A; use Method B only if you need to configure the connection manually. Do not mix the two configurations unnecessarily.
Method A — Ollama launcher (recommended)
ollama launch claude --model qwen2.5-coder:1.5b This uses Ollama’s Claude Code integration and selects the local model. If launch is not recognized, update Ollama using the current installer from ollama.com/download, then reopen the terminal.
Method B — Environment variables (manual setup)
Claude Code can be pointed at Ollama’s local API with environment variables. These variables are not required when Method A works. They are a way to configure the manual connection.
Windows CMD — current window only:
set ANTHROPIC_BASE_URL=http://localhost:11434 set ANTHROPIC_AUTH_TOKEN=ollama set ANTHROPIC_API_KEY= claude --model qwen2.5-coder:1.5b Windows PowerShell — current window only:
$env:ANTHROPIC_BASE_URL = "http://localhost:11434" $env:ANTHROPIC_AUTH_TOKEN = "ollama" $env:ANTHROPIC_API_KEY = "" claude --model qwen2.5-coder:1.5b Linux / macOS — current shell only:
export ANTHROPIC_BASE_URL=http://localhost:11434 export ANTHROPIC_AUTH_TOKEN=ollama export ANTHROPIC_API_KEY="" claude --model qwen2.5-coder:1.5b These commands apply to the terminal session in which you run them. Close that session and the temporary variables disappear.
Do I need to set them every time?
- With
ollama launch claude: usually no manual variable setup is needed. - With
set,$env:orexport: yes, set them again in each new terminal session. - Persistent variables are possible, but are not needed for this tutorial. Avoid
setxunless you deliberately want Windows variables to persist; it affects future sessions, not the current CMD window.
[SCREENSHOT 7 — Manual variables set in one terminal]
6. Test a real file operation
Create an empty test folder and enter it. For example, on Windows:
mkdir local-agent-demo cd local-agent-demo Launch the agent using Method A or Method B, then give it a specific task:
Create
hello.pycontainingprint("Hello from local Ollama"). Show me the file contents and explain how to run it. Do not modify any other files.
After the agent finishes, verify the result yourself.
Windows CMD:
dir type hello.py python hello.py PowerShell:
Get-ChildItem Get-Content .\hello.py python .\hello.py Linux / macOS:
ls -la cat hello.py python3 hello.py Only report success if the file exists and the output matches. Review commands and changes before approving them.
[SCREENSHOT 8 — Agent request and its response]
[SCREENSHOT 9 — File contents and verified program output]
7. Our results and limitations
On our Windows computer with 8 GB RAM, qwen2.5-coder:1.5b was usable for basic chat but did not consistently behave as a reliable coding agent. Some tool calls were malformed, and the workflow was slow. The qwen2.5-coder:7b test was also very slow on this machine.
This is a result from one setup, not a universal benchmark. A small model can answer prompts yet still struggle with an agent’s tools, multi-step tasks and system instructions. Do not claim reliable file creation unless you have verified it.
[SCREENSHOT 10 — A genuine test result, including any error or delay]
8. Quick troubleshooting
-
ollamanot found: reopen the terminal; otherwise reinstall Ollama. -
claudenot found: reopen the terminal and check the official Claude Code installation steps. -
ollama launchnot found: update Ollama. - Connection error: make sure Ollama is running and
http://localhost:11434is the local endpoint in the manual method. - Slow responses / broken tool calls: try a simpler prompt, reduce the task size, and verify the result manually. The model may be too small for reliable agent use.
Conclusion
Ollama makes it possible to experiment with Claude Code using a local model, without a hosted model API for inference. The key lesson from our test is that local execution does not automatically mean fast or reliable agent behaviour. Start small, verify every change, and choose a model that your hardware can handle.
