Claude Controller

claude-controller

A backend/model switcher for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). One command picks your inference backend, sets the right environment, and launches Claude Code — no manual `export` juggling, no stale env vars between sessions.

Architecture


`claude-controller` sits between you and Claude Code. It resolves dynamic model facts from the Ollama API, merges them with curated compatibility knowledge, pre-flight checks the target endpoint, then hands off to Claude Code with a clean environment. After your session, `cc-health` and `cc-diagnose` analyse what happened.

Repository structure

claude-controller/
├── claude-controller.sh      # main entry point — interactive picker, env manager, launcher
├── ollama_resolver.py        # queries Ollama API live for installed models, num_ctx, architecture
├── model_profiles.json       # curated compatibility knowledge: tool_compat, known_issues
├── README.md
├── docs/
│   └── architecture.svg      # system architecture diagram
└── tools/
    ├── cc-health             # post-session JSONL analyser — flags anomalies and failure patterns
    └── cc-diagnose           # Ollama performance diagnostic — VRAM, tok/s, GPU offload

Installation

# Clone or copy the repo, then make scripts executable
chmod +x claude-controller.sh tools/cc-health tools/cc-diagnose

# Optional: symlink to PATH
ln -sf "$(pwd)/claude-controller.sh"  ~/.local/bin/claude-controller
ln -sf "$(pwd)/tools/cc-health"       ~/.local/bin/cc-health
ln -sf "$(pwd)/tools/cc-diagnose"     ~/.local/bin/cc-diagnose

**Prerequisites:** Claude Code CLI, Python 3, `nc`/`ss`/`lsof`, `curl`

For Ollama backend: [install Ollama](https://ollama.com) and pull at least one model.

For OpenAI or Gemini backends, install LiteLLM:

pip install 'litellm[proxy]' --break-system-packages

Quick start

claude-controller

Pick a backend, pick a mod