                                   Claude Code
                                   Running Locally with Ollama




                                      Complete Setup Guide



  ✓ Zero API Costs Forever

  ✓ Complete Privacy - Code Never Leaves Your Machine

  ✓ All Features: MCP Servers, Tool Use, Multi-turn Conversations

  ✓ Works with Open Source Models




                                       Last Updated: February 04, 2026




Claude Code + Ollama Setup Guide                                         Page 1 of 27
  Table of Contents

             Section                                      Page


             1. Introduction                                 3


             2. What is Claude Code?                         3


             3. Why Run Locally with Ollama?                 4


             4. System Requirements                          5


             5. Step 1: Install Ollama                       6


             6. Step 2: Download Coding Models               7


             7. Step 3: Install Claude Code                  9


             8. Step 4: Configure Environment Variables     10


             9. Step 5: Launch Claude Code                  11


             10. Recommended Models for Coding              12


             11. Using Claude Code Features                 13


             12. Troubleshooting Common Issues              14


             13. Performance Tips                           15


             14. Advanced Configuration                     16




Claude Code + Ollama Setup Guide                                 Page 2 of 27
  1. Introduction
  Claude Code is Anthropic's revolutionary agentic coding tool that lives in your terminal, understands
  your codebase, and helps you code faster through natural language commands. Until recently, using
  Claude Code required an API connection to Anthropic's servers and incurred per-use costs.

  With    Ollama    version   0.14.0   and   later,   everything   changed.   Ollama   now   provides   an
  Anthropic-compatible API, which means you can run Claude Code entirely on your local machine using
  open source models - completely free, forever.

  This guide provides step-by-step instructions to set up Claude Code with Ollama, from installation
  through advanced configuration. By the end, you'll have a fully functional local coding assistant that
  respects your privacy and costs nothing to run.



  2. What is Claude Code?
  Claude Code is an agentic AI coding assistant that can:


         • Read and analyze your entire codebase to understand context

         • Write and modify files directly with your permission

         • Execute commands in your terminal to run tests, install packages, etc.

         • Handle git workflows including commits, branches, and merge conflicts

         • Explain complex code in plain language

         • Debug and fix errors automatically

         • Refactor code to improve quality and performance

         • Use external tools through MCP (Model Context Protocol) servers


  Unlike simple code completion tools, Claude Code is truly agentic - it can break down complex tasks,
  execute multiple steps, and adapt its approach based on results. It's like having an experienced
  developer pair programming with you.




Claude Code + Ollama Setup Guide                                                                 Page 3 of 27
  3. Why Run Locally with Ollama?
  Cost Savings
  Claude Code with Anthropic's API can cost $100-200 per month for regular users. Running locally with
  Ollama is completely free after the initial setup. You only pay for electricity - typically pennies per
  session.


  Complete Privacy
  When running locally, your code never leaves your machine. No data is sent to external servers, no
  metadata is collected, and no code snippets are uploaded. This is crucial for proprietary projects,
  sensitive client work, or regulated industries.


  Offline Capability
  Once models are downloaded, you can code completely offline. Perfect for travel, unstable internet
  connections, or working in secure environments without internet access.


  Learning and Experimentation
  Free local models are ideal for learning, testing ideas, and building prototypes without worrying about
  API costs. Experiment freely, iterate rapidly, and only use paid APIs when you need maximum quality
  for production code.

     ■ Important Note: Local open source models are not as capable as Anthropic's Claude Opus 4.5 or
     Claude Sonnet 4.5. However, they excel at routine tasks: bug fixes, code explanations, refactoring,
     boilerplate generation, and testing. Think of local models as your tireless junior developer, and
     premium models as your senior architect.




Claude Code + Ollama Setup Guide                                                                    Page 4 of 27
  4. System Requirements
  Hardware Requirements

                  Component            Minimum          Recommended                 Ideal

                      RAM                8 GB                 16 GB                 32 GB+


                     Storage           10 GB free           50 GB free         100 GB+ free


                      CPU              Quad-core             8+ cores            12+ cores


                      GPU           None (CPU only)     NVIDIA RTX 3060      NVIDIA RTX 4090



     RAM Guidance: With 8 GB, use small models (1-3B parameters). With 16 GB, use medium models
     (6-13B). With 32 GB+, use large models (20-30B) for best quality.


  Software Requirements
        • Operating System: macOS 13.0+, Windows 10 1809+ (with WSL2), or Linux (Ubuntu 20.04+,
        Debian 10+)

        • Terminal: Bash or Zsh (bash included with macOS/Linux, available in WSL2 for Windows)

        • Node.js: Not required for native installation (recommended method)

        • Internet: Required for initial setup and model downloads, then optional

     ■■ Windows Users: Claude Code works best with WSL2 (Windows Subsystem for Linux). Native
     Windows support is limited. Install Ubuntu from the Microsoft Store and run all commands in WSL2.




Claude Code + Ollama Setup Guide                                                                   Page 5 of 27
  5. Step 1: Install Ollama
  Ollama makes it simple to run large language models locally. It handles model management, provides
  an API server, and now offers Anthropic API compatibility.


  Installation by Platform
  macOS
        Option 1: Download from website (recommended)

  Visit https://ollama.com/download and download the macOS installer

  Open the .dmg file and drag Ollama to Applications


        Option 2: Install with Homebrew

    brew install ollama


  Linux
  Run the official installation script:

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


  Windows (WSL2)
  First, ensure WSL2 is installed:

    wsl --install


  Then install Ubuntu from Microsoft Store, open Ubuntu, and run:

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




  Verify Installation
  After installation, verify Ollama is working:

    ollama --version


  You should see output like: ollama version is 0.15.0




Claude Code + Ollama Setup Guide                                                            Page 6 of 27
  Start Ollama Service
  Start the Ollama API server (keep this terminal window open):

    ollama serve


  You should see: Listening on 127.0.0.1:11434

     ✓ Success: If you see 'Listening on 127.0.0.1:11434', Ollama is running correctly!




Claude Code + Ollama Setup Guide                                                          Page 7 of 27
  6. Step 2: Download Coding Models
  Claude Code requires models with large context windows (at least 64K tokens recommended) and
  tool-calling capabilities. Open a new terminal window (keep ollama serve running) for the following
  commands.


  Quick Start: Best All-Around Model
  For most users, start with GLM-4.7-Flash:

    ollama pull glm-4.7-flash


  This model offers excellent coding ability, 128K context window, tool-calling support, and runs well on
  most systems. Download size: approximately 5 GB. Download time: 5-15 minutes depending on your
  internet speed.




  Alternative Recommended Models

             <b>Model</b>          <b>Size</b> <b>Context</b>
                                                           <b>Best For</b>              <b>Command</b>


             qwen3-coder           ~4 GB      64K         General coding, fast          ollama pull qwen3-coder


             gpt-oss:20b           ~12 GB     128K        High quality, needs 16GB+ RAMollama pull gpt-oss:20b


             gpt-oss:120b          ~70 GB     128K        Maximum quality, needs 64GB+ ollama
                                                                                       RAM pull gpt-oss:120b


             deepseek-coder-v2     ~9 GB      64K         Strong code generation        ollama pull deepseek-coder-v2




     ■ Context Window Importance: Claude Code works best with models that have 64K+ token context
     windows. This allows the model to see more of your codebase at once, leading to better understanding
     and suggestions.




  Configure Context Length (Important!)
  By default, Ollama uses 2048 token context. For coding, you need at least 64000 tokens. Create or edit
  the Ollama configuration:

        macOS/Linux:




Claude Code + Ollama Setup Guide                                                                                   Page 8 of 27
    mkdir -p ~/.ollama
    nano ~/.ollama/config.json


        Add this configuration:

    {
    "num_ctx": 64000
    }


  Save (Ctrl+X, then Y, then Enter) and restart Ollama:

    pkill ollama
    ollama serve




  Verify Downloaded Models
  Check which models you have:

    ollama list




Claude Code + Ollama Setup Guide                          Page 9 of 27
  7. Step 3: Install Claude Code
  Claude Code can be installed using the native installer (recommended) or npm. The native installer
  doesn't require Node.js and provides automatic updates.


  Native Installation (Recommended)
        macOS / Linux / WSL2:

    curl -fsSL https://claude.ai/install.sh | bash


        Windows PowerShell:

    irm https://claude.ai/install.ps1 | iex




  Alternative: npm Installation
  If you prefer npm and have Node.js 18+ installed:

    npm install -g @anthropic-ai/claude-code


     ■■ Warning: Do NOT use sudo npm install as this can cause permission issues. If you get
     EACCES errors, fix npm permissions or use the native installer instead.




  Verify Installation
  Check that Claude Code is installed:

    claude --version


  You should see the version number (e.g., 2.1.12)




  Run Claude Code Doctor
  Verify your installation is healthy:

    claude doctor


  This checks your installation and identifies any issues.



Claude Code + Ollama Setup Guide                                                           Page 10 of 27
     ✓ Success: If 'claude --version' shows a version number, installation was successful!




Claude Code + Ollama Setup Guide                                                             Page 11 of 27
  8. Step 4: Configure Environment Variables
  To use Claude Code with Ollama instead of Anthropic's API, you need to set environment variables that
  point Claude Code to your local Ollama server.


  Quick Setup (Temporary)
  For a quick test, set variables in your current terminal session:

        macOS / Linux / WSL2 (bash/zsh):

    export ANTHROPIC_BASE_URL="http://localhost:11434"
    export ANTHROPIC_AUTH_TOKEN="ollama"
    export ANTHROPIC_API_KEY=""


        Windows PowerShell:

    $env:ANTHROPIC_BASE_URL = "http://localhost:11434"
    $env:ANTHROPIC_AUTH_TOKEN = "ollama"
    $env:ANTHROPIC_API_KEY = ""




  Permanent Setup (Recommended)
  Add environment variables to your shell configuration file:

        For bash (most Linux, WSL2):

    nano ~/.bashrc


        For zsh (macOS default):

    nano ~/.zshrc


        Add these lines at the end of the file:

    # Claude Code with Ollama
    export ANTHROPIC_BASE_URL="http://localhost:11434"
    export ANTHROPIC_AUTH_TOKEN="ollama"
    export ANTHROPIC_API_KEY=""
    export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1


  Save (Ctrl+X, Y, Enter) and reload your configuration:

    source ~/.bashrc # or source ~/.zshrc




Claude Code + Ollama Setup Guide                                                             Page 12 of 27
  Alternative: JSON Configuration
  You can also configure via Claude Code's settings file:

    mkdir -p ~/.claude
    nano ~/.claude/settings.json


        Add this configuration:

    {
    "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
    }
    }


     ■ Environment Variable Explanation:
     • ANTHROPIC_BASE_URL: Points to Ollama's API instead of Anthropic's
     • ANTHROPIC_AUTH_TOKEN: Set to 'ollama' for Ollama authentication
     • ANTHROPIC_API_KEY: Empty string (Ollama doesn't need an API key)
     • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Prevents telemetry for offline use




Claude Code + Ollama Setup Guide                                                      Page 13 of 27
  9. Step 5: Launch Claude Code
  With everything configured, you're ready to launch Claude Code! Make sure Ollama is still running
  (ollama serve in one terminal).


  Using ollama launch (Easiest Method)
  Ollama 0.15+ includes a convenient launch command:

    ollama launch


  This command automatically configures environment variables and launches Claude Code. Select
  'Claude Code' from the menu, choose your model, and you're done!




  Manual Launch
  Navigate to your project directory and launch Claude Code:

    cd /path/to/your/project
    claude --model qwen3-coder


  Replace qwen3-coder with your chosen model name.




  First Run Setup
  On first run, Claude Code may ask for permissions. Since you're using Ollama locally, you can skip
  authentication. Accept file access permissions for your project directory.




  Test Your Setup
  Try a simple command to verify everything works:

     create a hello.py file that prints Hello World


  If Claude Code creates the file successfully, congratulations! Your setup is complete.

     ✓ You're All Set! Claude Code is now running locally with Ollama. Try some commands to explore its
     capabilities!



Claude Code + Ollama Setup Guide                                                                 Page 14 of 27
  Verify Local Operation
  To confirm you're running fully local (not using Anthropic's API), disconnect from the internet and run a
  command. If you get a response, you're successfully running offline!




Claude Code + Ollama Setup Guide                                                                 Page 15 of 27
  10. Recommended Models for Coding
  Different models excel at different tasks and have varying resource requirements. Here's a detailed
  guide to help you choose the right model for your needs.


  For 8 GB RAM Systems
        Best Choice: qwen3-coder (Small version)

  The small version of qwen3-coder fits in 8 GB RAM and provides decent coding assistance for simple
  tasks. Expect slower inference and lower quality compared to larger models.


  For 16 GB RAM Systems
        Best Choice: glm-4.7-flash or qwen3-coder

  Both models offer excellent balance of performance and resource usage. GLM-4.7-Flash has better
  tool-calling support and 128K context, making it ideal for most coding tasks.


  For 32 GB+ RAM Systems
        Best Choice: gpt-oss:20b or deepseek-coder-v2

  These larger models provide significantly better code quality, deeper understanding, and more
  sophisticated solutions. Recommended if you have the resources.


  For 64 GB+ RAM Systems with GPU
        Best Choice: gpt-oss:120b

  The highest quality open source coding model available. Approaches premium API quality for complex
  tasks. Requires substantial hardware (NVIDIA RTX 4090 or better recommended).




  Task-Specific Recommendations

             <b>Task Type</b>       <b>Recommended Model</b> <b>Why</b>

             Quick bug fixes        glm-4.7-flash               Fast responses, tool support


             Code explanations      qwen3-coder                 Good balance, clear output




Claude Code + Ollama Setup Guide                                                               Page 16 of 27
             Refactoring           gpt-oss:20b                    Better architecture understanding


             Complex debugging     gpt-oss:20b or 120b            Deep reasoning capability


             Boilerplate code      glm-4.7-flash                  Fast generation, good patterns


             Test generation       qwen3-coder                    Solid coverage, fast




  Switching Models
  You can easily switch models by specifying a different model:

    claude --model gpt-oss:20b




Claude Code + Ollama Setup Guide                                                                      Page 17 of 27
  11. Using Claude Code Features
  Basic Commands
  Once Claude Code is running, you can use natural language:

        • Create a Python script that sorts a list of numbers

        • Explain what this function does (with file selected)

        • Fix the bug in auth.py

        • Refactor this code to use async/await

        • Add error handling to database.py

        • Write unit tests for the user class




  Slash Commands
  Claude Code includes built-in slash commands:

        • /help - Show all available commands

        • /edit [file] - Edit mode for specific file

        • /clear - Clear conversation history

        • /exit - Exit Claude Code

        • /bug - Report a bug to Anthropic

        • /settings - View/modify settings




  Tool Use and MCP Servers
  Claude Code can use external tools through MCP (Model Context Protocol) servers. This allows
  integration with databases, APIs, and other services. Note that tool-calling requires models that support
  it (like glm-4.7-flash, gpt-oss).




  Multi-turn Conversations


Claude Code + Ollama Setup Guide                                                                 Page 18 of 27
  Claude Code maintains context across multiple messages. You can have a back-and-forth conversation
  to refine solutions:

         Create a REST API endpoint

        [Claude creates endpoint]

         Add input validation

        [Claude adds validation]

         Now add error handling

        [Claude adds error handling]




  Edit Mode
  Edit mode allows direct file modifications. Claude Code will show you a diff of proposed changes before
  applying them:

     /edit src/main.py


     Optimize this function for performance




Claude Code + Ollama Setup Guide                                                               Page 19 of 27
  12. Troubleshooting Common Issues
  Issue: Connection Refused
        Symptom: Error connecting to localhost:11434

        Solution:

        • Ensure Ollama is running: ollama serve

        • Check if port 11434 is available: lsof -i :11434

        • Restart Ollama service




  Issue: Model Not Found
        Symptom: 'Model qwen3-coder not found'

        Solution:

        • Verify model is downloaded: ollama list

        • Pull the model: ollama pull qwen3-coder

        • Use exact model name from ollama list




  Issue: Very Slow Responses
        Symptom: Takes minutes to get a response

        Solutions:

        • Switch to a smaller model (glm-4.7-flash instead of gpt-oss:20b)

        • Close other memory-intensive applications

        • Monitor system resources: top or Activity Monitor

        • Consider upgrading RAM if consistently slow




  Issue: Out of Memory
        Symptom: System freezes or Ollama crashes




Claude Code + Ollama Setup Guide                                             Page 20 of 27
        Solutions:

        • Use a smaller model that fits your RAM

        • Reduce context length in ~/.ollama/config.json

        • Use quantized models (they use less memory)




  Issue: Command Not Found: claude
        Symptom: Terminal doesn't recognize 'claude' command

        Solutions:

        • Restart terminal after installation

        • Check PATH: echo $PATH

        • For native install, add to PATH: export PATH="$HOME/.local/bin:$PATH"

        • Run claude doctor for diagnosis




  Issue: Still Using Anthropic API
        Symptom: Getting API key errors or being charged

        Solution:

        • Verify environment variables: echo $ANTHROPIC_BASE_URL

        • Should show: http://localhost:11434

        • Disconnect internet and test - should still work if truly local




Claude Code + Ollama Setup Guide                                                  Page 21 of 27
  13. Performance Tips
  Optimize Inference Speed
        Use GPU Acceleration (NVIDIA only):

  Ollama automatically uses GPU if available. Verify with:

    nvidia-smi


  You should see ollama process using GPU memory.


        Adjust Context Window:

  Larger context = slower inference. If you don't need 64K tokens, reduce it:

    # In ~/.ollama/config.json
    {"num_ctx": 32000} # Faster than 64000


        Use Quantized Models:

  Quantized models (e.g., q8_0, q4_0) are smaller and faster with minimal quality loss:

    ollama pull glm-4.7-flash:q8_0




  Memory Management
        Keep Models Loaded:

  Ollama keeps recently used models in memory. If you frequently switch models, increase keep-alive:

    # In ~/.ollama/config.json
    {"keep_alive": "1h"} # Keep model loaded for 1 hour


        Unload Unused Models:

  Free up memory by stopping Ollama:

    pkill ollama




  Coding Workflow Optimization

Claude Code + Ollama Setup Guide                                                             Page 22 of 27
        Use the Right Model for the Task:

  Don't use large models for simple tasks. Keep multiple models and switch based on complexity:

        • Simple fixes: glm-4.7-flash (fast)

        • Complex refactoring: gpt-oss:20b (quality)

        Batch Similar Tasks:

  Process multiple related files in one session to leverage context:

     Refactor all utility files in src/utils/




  Disk Space Management
  Models can take significant space. Remove unused models:

    ollama rm model-name


  List all models with sizes:

    ollama list




Claude Code + Ollama Setup Guide                                                             Page 23 of 27
  14. Advanced Configuration
  Using Ollama Cloud Models
  Ollama offers cloud-hosted models with full context length. These aren't free but are often cheaper than
  Anthropic's API:

    ollama pull glm-4.7:cloud


  Cloud models run at full context length without local hardware requirements. Free tier available with
  generous limits.




  Custom Model Configuration
  Create a Modelfile to customize system prompts, temperature, and other parameters:

    nano Modelfile


    FROM qwen3-coder
    PARAMETER temperature 0.7
    PARAMETER top_p 0.9
    SYSTEM You are an expert Python developer focused on clean, efficient code.


  Create the custom model:

    ollama create my-coding-assistant -f Modelfile


  Use your custom model:

    claude --model my-coding-assistant




  Multiple Ollama Instances
  Run multiple Ollama servers on different ports for different models:

    OLLAMA_HOST=127.0.0.1:11435 ollama serve


  Then configure Claude Code to use the specific port:

    ANTHROPIC_BASE_URL=http://localhost:11435 claude --model qwen3-coder




Claude Code + Ollama Setup Guide                                                                Page 24 of 27
  Remote Ollama Server
  Run Ollama on a powerful remote server and connect from your laptop:

        On server:

    OLLAMA_HOST=0.0.0.0:11434 ollama serve


        On laptop:

    export ANTHROPIC_BASE_URL="http://server-ip:11434"


     ■■ Security Warning: Only expose Ollama on trusted networks. Use SSH tunneling or VPN for
     secure connections.




  Hybrid Workflow: Local + Cloud
  Use local models for iteration and premium APIs for production:

        1. Develop and test with local Ollama models (free, fast iteration)

        2. Final review/production code with Claude Opus 4.5 (premium quality)

  Switch between local and API:

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

    # Anthropic API
    unset ANTHROPIC_BASE_URL
    export ANTHROPIC_API_KEY="your-api-key"




Claude Code + Ollama Setup Guide                                                             Page 25 of 27
  Conclusion
  Congratulations! You've successfully set up Claude Code to run locally with Ollama. You now have a
  powerful, free, private coding assistant that works entirely on your machine.




  What You've Achieved
        • Zero ongoing costs - No API fees, ever

        • Complete privacy - Your code stays on your machine

        • Offline capability - Work anywhere, anytime

        • Full features - All Claude Code capabilities available




  Next Steps
        1. Experiment with different models to find your favorite

        2. Try complex tasks to understand capabilities and limitations

        3. Configure shortcuts and aliases for common workflows

        4. Join the community - Claude Developers Discord for tips and support

        5. Contribute back - Share your learnings and help others




  Important Reminders
        • Local models are excellent for routine tasks but may struggle with very complex problems

        • Keep Ollama updated: ollama update

        • Monitor resource usage and adjust model size to your hardware

        • Consider a hybrid approach: local for development, premium API for production



     ■ Happy Coding! You're now equipped to code faster, learn more, and build amazing things with your
     free local AI assistant. The future of development is here, and it runs on your machine.




Claude Code + Ollama Setup Guide                                                                Page 26 of 27
                                               For questions, issues, or feedback:

                              • Claude Code GitHub: https://github.com/anthropics/claude-code

                                        • Ollama Documentation: https://ollama.com/docs

                                     • Claude Developers Discord: https://discord.gg/claude



                                   This guide is community-maintained. Contributions welcome!




Claude Code + Ollama Setup Guide                                                                Page 27 of 27
