Connect an AI provider

The chat assistant and the planning agent both run on a language model that you choose. Four providers are supported, and you can switch between them at any time:

With Ollama, nothing ever leaves your computer and there is no per-request cost. Cloud providers are metered by the provider, and the app sends them only the chat messages and planning briefs you type — never your database.

Setting up

The easiest path is the LLM Setup Wizard, which opens on first start and can be reopened any time from the settings gear menu. Pick a provider card, choose a Model, enter an API key if the provider needs one, and press Test connection (or Save key & test) to verify before saving.

The same options live in Settings → Chat, where each provider remembers its own model, key and options — so switching back and forth is cheap.

A note on keys: once saved, a key is never displayed again — you'll only see a masked placeholder like •••••••••••••••• (saved). Leave the field untouched to keep the existing key, or type to replace it. Keys are stored locally on your machine and are used directly from it; there is no middleman server.

Setting up Ollama

1. Install Ollama and make sure it's running.
2. Pull a model, for example: ollama pull qwen2.5:7b
3. In the wizard or Settings → Chat, select the Ollama card and test the connection.

Small local models are slower and less polished than the big cloud models, but they are free, private and completely offline — and shadow-planner includes reliability aids specifically tuned for them.

Switching providers

The chat drawer header always shows which provider and model are active (for example Ollama · qwen2.5:7b · scoped to scenario). Once two or more providers are configured, the header becomes a Switch AI provider button — one click switches the whole app, including the planning agent, and drops a divider into the transcript so you can see where the switch happened.

Tuning

• Reasoning effort — per provider, in the chat settings under the model selection: from off to max. Higher effort can improve tricky answers at the cost of latency (on local models you'll notice a longer pause before the first token). Models that don't support it simply ignore the setting — the app tells you.
• Critique pass — by default a second AI pass reviews each reply before you see it. Turn it off in the chat settings if you prefer lower latency over the extra check.
• Token budget — if a large AI-drafted plan hits the output limit, raise the budget in Settings (the error message points you to the exact setting) or shorten the brief.