Claude Code Ollama Agents

Custom Claude Code subagents that delegate code generation, review, testing, explanation, vision analysis, and audio transcription to local Ollama models — saving Claude tokens and keeping work on-device.

Why

Claude Code is great for orchestration, but every line of code it writes costs tokens. These agents offload the actual generation to a local Ollama model (e.g. Qwen 3.5 35B) running on your machine. Claude plans and reviews; Ollama writes.

Unlike an MCP server, these agents stream output visibly in your terminal — you see every token as it's generated, along with speed and token counts.

The Agents

Agent	Purpose	Default Model
ollama-coder	Writes new code, fixes bugs, refactors	qwen3.5:35b-a3b
ollama-reviewer	Code review, security audits	qwen3.5:35b-a3b
ollama-tester	Generates unit/integration tests	qwen2.5-coder:32b
ollama-explainer	Explains code and architecture	qwen3.5:35b-a3b
ollama-vision	Analyzes images/screenshots/UI	qwen2.5vl:7b
ollama-transcribe	Transcribes audio to text	whisper-large-v3-turbo (via mlx-whisper)

Requirements

• Claude Code
• Ollama running on localhost:11434
• Python 3.9+
• For transcription: mlx-whisper (macOS, Apple Silicon)

Pull the models you need:

ollama pull qwen3.5:35b-a3b      # general code tasks
ollama pull qwen2.5-coder:32b    # coding-focused
ollama pull qwen2.5vl:7b         # vision

Install

Clone this repo and run the install script:

git clone https://github.com/PratikHotchandani22/claude-ollama-agents.git
cd claude-ollama-agents
./install.sh

The install script copies the agents to ~/.claude/agents/ and the helper scripts to ~/.claude/scripts/.

Manual install

mkdir -p ~/.claude/agents ~/.claude/scripts
cp agents/*.md ~/.claude/agents/
cp scripts/*.py ~/.claude/scripts/

Usage

Once installed, Claude Code auto-discovers the agents in every project. You can:

• Let Claude delegate automatically (add a rule in your ~/.claude/CLAUDE.md — see below)
• Invoke explicitly: "Use the ollama-coder agent to write a palindrome function"
• @-mention: @ollama-coder write a ...

Recommended: add to your global CLAUDE.md

Add this to ~/.claude/CLAUDE.md so Claude always delegates code tasks:

## Local-First Code Generation

Delegate ALL code writing tasks to local Ollama agents. Never write code directly (>5 lines).

- Writing/fixing/refactoring code → Agent: `ollama-coder`
- Code review → Agent: `ollama-reviewer`
- Writing tests → Agent: `ollama-tester`
- Explaining code → Agent: `ollama-explainer`
- Image/UI analysis → Agent: `ollama-vision`
- Audio transcription → Agent: `ollama-transcribe`

Bypass with "use claude directly" for a one-off task.

How It Works

Each agent runs as a Claude Code subagent (its own context window). When invoked:

1. The agent reads any files needed for context
2. It calls a helper script (scripts/ollama_stream.py or scripts/ollama_vision.py)
3. The script streams the Ollama response token-by-token to stdout
4. The agent captures the output, reviews it, and writes code to files via the Edit/Write tools

Token usage is tracked locally in ~/.claude/scripts/agent_token_stats.json.

Helper Scripts

ollama_stream.py

Streams text generation from Ollama with visible token output.

python3 ~/.claude/scripts/ollama_stream.py \
  --model "qwen3.5:35b-a3b" \
  --file /path/to/context.js \
  --prompt "Write a function that does X" \
  --stats --agent ollama-coder

ollama_vision.py

Streams vision analysis for images.

python3 ~/.claude/scripts/ollama_vision.py \
  --image /path/to/screenshot.png \
  --prompt "Identify visual bugs in this UI" \
  --stats --agent ollama-vision

Customizing

Each agent is a Markdown file with YAML frontmatter. Edit ~/.claude/agents/ollama-*.md to:

• Change the default model
• Adjust the system prompt
• Restrict/expand tool access

See Claude Code subagents docs for details.

License

MIT