Troubleshooting
“upstream 404”
The most common cause: the model name in your config doesn’t match anything installed. Run ollama list to see your installed models, then either pull the one you want (ollama pull qwen2.5-coder:7b) or switch with /model from inside Mini-claude.
The header shows “weak tool calling”
Your model advertises the tools capability but emits its calls as text instead of the structured field. Mini-claude recovers many of these via its fallback parser, but multi-step tasks will be flaky. For real agent work, switch to a verified model (mistral:7b, qwen3:8b, llama3.1:8b), see Models. For a reliable project summary regardless, use /audit.
The agent “spins” for a long time on a task
Normal for a local agent: each turn runs the model, and one task chains several tool turns. A 7B on CPU runs slowly, that’s inference, not a bug. Options: a smaller model for simple tasks, a GPU if you can, or /audit, which asks the model for a single synthesis.
“connection refused”
The inference server isn’t running on the URL you configured. Check MINI_CLAUDE_URL (default http://localhost:11434) and confirm Ollama is up:
curl http://localhost:11434/v1/modelsResponses are extremely slow
Local inference on CPU is slow, especially for 7B+ models. For snappier responses, drop to a smaller model (at the cost of tool calling). If you have a GPU, make sure Ollama is detecting it (ollama ps). On the first message after switching models, also factor in cold-load time.
The TUI looks broken / colors are wrong
Your terminal might not advertise truecolor support. Try setting export COLORTERM=truecolor before launching.
Clicking the miniclaude.fr link doesn’t open the browser
You need a modern terminal that supports OSC 8 hyperlinks (iTerm2, recent Terminal.app, WezTerm, Kitty, Alacritty). Try Cmd+click on macOS, Ctrl+click on Linux.
Mouse selection doesn’t work
If you’re on an older build, hold Option (macOS) or Shift (Linux) while selecting to bypass the terminal’s mouse capture. Recent versions of Mini-claude disable mouse capture by default.