How to use Code Ollama

This post goes over how to use Code Ollama, a free coding agent that runs in your terminal.

Motivation

Why use Code Ollama?

free (no per-token API cost)
private (local inference)
offline (run without internet)
open models (Gemma, Qwen, DeepSeek, etc.)

Ollama

Install Ollama:

brew install ollama

Start the Ollama server in a separate terminal:

ollama serve

Download gemma4:

ollama pull gemma4

You can also download a model from the TUI using the /models command.

Confirm the model works:

ollama run gemma4 "Hello, world!"

Code Ollama

Run Code Ollama without installing it:

npx code-ollama

Or install the npm package globally:

npm install --global code-ollama

Alternatively, download a standalone executable for Linux, macOS, and Windows from GitHub Releases. Standalone executables do not support certain features.

Check that Code Ollama can connect to Ollama and find the selected model:

code-ollama doctor

Open the terminal user interface (TUI) from a project directory:

cd path/to/project
code-ollama

Code Ollama will ask whether you trust the directory before reading files or running tools. Once the TUI opens, try a prompt:

Explain this project and suggest one small improvement.

Use /models to switch or download models. Press ? to see the keyboard shortcuts and available commands.

Tools and Modes

Code Ollama can use tools to search and read files, edit code, and run shell commands. Press Shift+Tab to cycle through modes:

Safe: runs read-only tools automatically and asks for approval before editing files or running commands
Auto: runs permitted tools without asking for approval
Plan: researches with read-only tools and creates a plan before making changes

One-Off Prompts

Run a prompt without opening the TUI:

code-ollama run gemma4 "Review the changes in this repository"

Add --trust to skip the directory trust prompt:

code-ollama run --trust gemma4 "Review the changes in this repository"

You can also attach images when using a vision-capable model:

code-ollama run gemma4 "Describe this error" --image screenshot.png

Skills

Skills are Markdown instructions that add project or user context to Code Ollama.

Add a project skill at:

.code-ollama/skills/<skill-name>/SKILL.md

Use /skills in the TUI to see which skills are loaded.

MCP

Code Ollama supports Model Context Protocol (MCP) servers, which make additional tools and resources available to the agent.

Configure local or remote MCP servers in:

~/.code-ollama/config.json

Use /mcp in the TUI to inspect configured servers, loaded tools, permissions, and errors. See the Code Ollama documentation for configuration examples.

Resources

Code Ollama is open source and available for macOS, Linux, and Windows through npm and GitHub Releases. Check out the documentation for more information!