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 llama3.2:3b) or switch with /model from inside mini-claude.
“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. Drop to llama3.2:1b or qwen2.5:0.5b for snappier responses. If you have a GPU, make sure Ollama is detecting it (ollama ps).
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.