otter-assist runs the local model behind Otter Assistant. It listens on a Unix socket tied to your Wayland display, does inference on-device, and can call out for knowledge lookup, web search, weather, or desktop search. The chat window is otter-assistant.
otter-assist, otter-assistant, and otter-assist-data ship in otter-shell-extras, not the base otter-shell metapackage. Install with pikman install otter-shell-extras.
Packages
| Package | Role |
|---|
otter-assist | Daemon (otter-assist) and control CLI (otter-assistctl) |
otter-assist-data | GGUF model plus packaged knowledge indexes under /usr/lib/otter-assist/ |
otter-assistant | XDG toplevel chat client |
/usr/lib/otter-assist/models/ (from otter-assist-data). Indexes land under /usr/lib/otter-assist/indexes/.
Start the daemon
If you use the assistant, start this with your session:
Useful flags:
otter-assist --threads 4
otter-assist --backend cpu
otter-assist --vulkan-device 0
otter-assist --idle-seconds 120
backend = cpu to load the CPU llama library instead, so the daemon never pulls in Vulkan drivers. Thread count defaults to min(cpu_count, 8).
Control CLI
otter-assistctl infer "Rewrite this shorter: Otter Shell is a Zig-based Wayland desktop shell."
otter-assistctl --json infer "Reply with one word: ok"
otter-assistctl chat --file request.json
otter-assistctl status
otter-assistctl unload
infer streams plain token chunks as they arrive. --json infer and chat stream newline-delimited JSON events (message_delta, tool_requested, approval_required, final).
Configuration
Defaults live in ~/.config/otter-shell/otter-assist.conf. Use the Assist tab in otter-settings, or edit the file:
backend = vulkan
vulkan_device = -1
idle_seconds = 120
knowledge_enabled = true
web_enabled = true
web_always_allow = false
weather_enabled = true
desktop_search_enabled = true
desktop_search_always_allow = false
pika_search_url = "https://search.pika-os.com/search?lang=en"
knowledge_index_dir = "/usr/lib/otter-assist/indexes"
max_tool_calls = 4
max_web_searches = 2
| Key | Meaning |
|---|
backend | vulkan (default) or cpu |
vulkan_device | -1 for llama.cpp auto selection; 0 first GPU, 1 second, and so on |
idle_seconds | Unload the idle model after this many seconds (default 120) |
knowledge_enabled | Run packaged knowledge retrieval on JSON chat requests |
web_enabled / web_always_allow | Allow web search; ask for approval unless always-allow is on |
weather_enabled | Open-Meteo weather tool (same path as otter-weather) |
desktop_search_enabled / desktop_search_always_allow | Query otter-search over its socket; blocked unless always-allow or one-shot approval |
pika_search_url | Web search endpoint |
knowledge_index_dir | Packaged index directory |
max_tool_calls / max_web_searches | Tool call budgets per request |
web_enabled and web_always_allow are both true, and the prompt actually needs current or web-backed info. Otherwise you get an approval_required event and no network call. Desktop search returns metadata and content previews only.
Every prompt gets the current UTC date and time, so the model does not invent relative dates. The packaged default model is the v12 full-knowledge LFM2.5 1.2B Q4_0 checkpoint.
Session setup
Add otter-assist to compositor autostart when you use Otter Assistant. See Session setup. Keep otter-search running if you want the desktop search tool.
