> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/ui-settings/ai-help/assistant.md). # Assistant Configure Ask CrossWatch, a AI assistant for diagnosing your installation. Ask the built-in AI assistant what is happening or what went wrong. It looks at CrossWatch and explains syncs, scrobbling, connections, and settings. {% hint style="info" %} CrossWatch does not include an AI model. Connect a cloud provider with your API key, or a free local model on your network. No AI provider yet? Ask CrossWatch still answers how-to questions from this wiki. See [Without an AI provider](#without-an-ai-provider). {% endhint %} ### How it works You ask a question. CrossWatch sends it to your AI model with read-only tools. The model uses those tools to inspect CrossWatch, then writes an answer. ``` Your question ↓ CrossWatch ←→ read-only tools (health, logs, events, settings) ↓ Your AI model ↓ Answer, with what it looked at and suggested actions ``` The assistant can only read. It can suggest actions as cards. Cards run only after you click **Run**. The assistant never changes settings or deletes anything. It is available only to administrators. ### What it can look at * **Health** — provider connections, the Watcher, the scheduler, and the last sync result. * **Last sync** — the run summary and items it could not resolve. * **Logs** — sync, Watcher, and debug logs, searched and read line by line. * **Events** — what each sync or scrobble did, per item. Audit events are excluded. * **Analyzer** — items that differ between both sides of a pair. * **Settings** — sync pairs and configuration, with secrets removed. * **Watcher** — routes, sinks, and what is playing now. * **Anime mapping** and **captures** — status and saved captures. * **This wiki** — for how-to questions. Answers link to the page used. * **CrossWatch source code** — only when the wiki has no answer. Every answer ends with **Looked at**, so you can see its sources. When the assistant reads wiki pages, links appear under **Wiki**. ### Without an AI provider Without an AI provider, Ask CrossWatch answers from this wiki only. It is good for how-to questions, such as how to add a pair or set up notifications. {% hint style="warning" %} Without an AI provider, the assistant cannot look at your logs, events or settings. Add an AI provider for full help. {% endhint %} * A **Limited help** notice at the top shows that only the wiki is used. **Set up AI provider** takes you to the settings. * Answers link to the wiki pages they used, under **Wiki**. * Up to three follow-up questions appear under **Ask next**. Click one to ask it. * A follow-up question also sends your earlier question, so the answer stays on topic. * Analyze and Explain with AI buttons, action cards, and the topic picker are not available. * An answer can take 10 to 15 seconds. Nothing goes to the wiki until you send a question or click a suggestion. Opening CrossWatch or the assistant sends nothing. To turn this off: 1. Open **Settings → UI Settings → Security**. 2. Find **AI help** and the **Assistant in CrossWatch** panel. 3. Set **Without an AI provider** to **Turn Ask CrossWatch off**. The sparkle button is then greyed out until you set up an AI provider. ### Before you begin You need one of these: | Provider | Where it runs | Key | Address | | ------------- | ------------- | ----------------------- | ----------------------------- | | OpenAI | Cloud | Paid developer key | Filled in | | Google Gemini | Cloud | Key with a free tier | Filled in | | OpenRouter | Cloud | One key for many models | Filled in | | Ollama | Your network | None | `http://COMPUTER-IP:11434/v1` | | LM Studio | Your network | None | `http://COMPUTER-IP:1234/v1` | | Other | Anywhere | Depends | Any OpenAI-style API | {% hint style="warning" %} A ChatGPT, Gemini, or Claude subscription does not include an API key. Create a developer key on the provider's developer page. For Google Gemini, use Google AI Studio. {% endhint %} The model must support tool calling. Most current cloud models do. Small and lite models work, but larger models give better answers. ### Configure the assistant 1. Sign in with an administrator account. 2. Open **Settings → UI Settings → Security**. 3. Find **AI help** and the **Assistant in CrossWatch** panel. 4. Pick your **AI provider**. 5. Paste your **API key**, or enter the **Address** for a local model. 6. Click **Load models** and pick a **Model** from the list. 7. Click **Save and turn on**. The badge at the top of the panel changes to **On**, with the model name. Without an AI provider it shows **Wiki only**. You can also type the model name yourself if the provider does not list models. ### Local models Local models keep everything on your network and cost nothing. Use the network address of the computer running the model: ``` http://192.168.1.20:11434/v1 ``` #### Ollama 1. Install a tool-capable model, such as `ollama pull qwen2.5:7b` or `ollama pull llama3.1:8b`. 2. Set `OLLAMA_HOST=0.0.0.0` so other computers can reach it. 3. Restart Ollama. 4. In CrossWatch, pick **Ollama** and enter `http://COMPUTER-IP:11434/v1`. #### LM Studio 1. Load a model that supports tools. 2. Start the local server and allow it to serve on your local network. 3. In CrossWatch, pick **LM Studio** and enter `http://COMPUTER-IP:1234/v1`. {% hint style="info" %} Small local models give weaker answers than cloud models. Try a cloud provider first if answers are not useful. {% endhint %} ### Ask a question Open the assistant from: * The **sparkle button** in the top bar. * **About → Ask CrossWatch**. * **Ask a question** in the assistant settings. The sparkle button is only greyed out when no AI provider is set up and wiki answers are turned off. Type a question, or click a suggestion. Use the picker next to **Send** to focus on **Syncing**, **Scrobbling**, **Connections**, or **Settings**. Ask follow-up questions in the same conversation. Click **New chat** to start over. The assistant replies in the language you write in. ### Analyze and Explain with AI Some pages have a button that asks the assistant about what you are looking at. * **Analyze** in the log panel on the Main page and the **Logs** page. * **Explain with AI** on Analyzer findings, in item details, or on a System health error or warning. * **Explain with AI** on Interactive Sync reports with problems, and on reviews that remove items or have conflicts. These buttons only show when an AI provider is set up and something needs explaining. ### Buttons in answers An answer can end with buttons that take you to the right place: * **Open logs**, **Open events** or **Open analyzer** * **Open connections**, **Open sync pairs**, **Open scrobbler** or **Open scheduling** * **Run sync** **Run sync** asks for confirmation first. It does nothing while a sync is already running. Clicking a button is always your action, never the assistant's. ### Action cards When it helps, the assistant suggests an action as a card under the answer: | Card | What it does | | ------------------------------------ | ------------------------------------------------------ | | **Run sync: SOURCE → TARGET** | Syncs that pair | | **Create capture: provider feature** | Saves a capture, for example before a risky change | | **Update anime mapping** | Downloads the latest anime mapping data | | **Test all connections** | Checks every connection again and shows why one failed | Click **Run** to start it, or **Dismiss** to skip it. The card then shows progress and the result. * Nothing runs until you click **Run**. Each card runs only once. * CrossWatch checks every card against your setup. The assistant can only suggest existing pairs, providers, and features. * A sync card never stops a running sync. It reports that a sync is busy instead. * A capture card shows progress. The capture appears under **Captures** like any other. Restoring captures, deleting items, and changing settings are never offered. Do those yourself in CrossWatch. ### Turn off or change provider Click **Turn off** in assistant settings. The settings are kept. Ask CrossWatch then answers from the wiki only, unless wiki answers are turned off. When you switch to a provider with a different address and save, the saved key is removed. Paste the key for the new provider. Turning the assistant off keeps the key. To remove it, switch to a provider with a different address and save. ### Privacy With a cloud provider, your question goes to that provider. So do the log lines, events, and settings the assistant needs to answer it. CrossWatch removes secrets first. Tokens, passwords, API keys, webhook addresses, and sign-in settings are never sent. Audit events, including who did what from which address, are never sent. Wiki searches go to GitBook, which hosts this wiki. Only search terms are sent, with secrets removed. Without an AI provider, your question goes to GitBook, with secrets removed. Nothing else from your CrossWatch is sent. {% hint style="info" %} A local model keeps everything on your network. {% endhint %} ### Troubleshooting * **Sparkle button greyed out** — no AI provider is set up and wiki answers are turned off. Set up an AI provider, or set **Without an AI provider** to **Answer from the CrossWatch wiki**, in **Settings → UI Settings → Security → AI help**. * **No sparkle button** — the assistant is only available to administrators. * **Limited help notice** — no AI provider is set up, so answers come from the wiki only. Set up an AI provider for full help. * **Could not reach the CrossWatch wiki** — CrossWatch has no internet access, or your network blocks it. Allow access to `wiki.crosswatch.app`, or set up a local model. * **The wiki had no answer to that** — ask it differently, or search the wiki yourself. * **The AI provider answered HTTP 401** — the API key is wrong or expired. Paste it again. * **The AI provider answered HTTP 429 or 503** — the provider is busy. CrossWatch already retried twice. Try again later or pick another model. * **The AI provider could not be reached** — check the address. For local models, use the computer's network address, not `localhost`. * **The AI provider address redirects somewhere else** — enter the final address. CrossWatch does not follow redirects. * **The model returned no text** — small models sometimes stop early. Ask again, or pick a larger model. * **That took too long** — a question can take at most five minutes. Ask something narrower. * **The assistant is busy with another question** — two questions can run at the same time. Wait for one to finish. * **Load models finds nothing** — type the model name yourself. * **The answer is wrong** — answers come from your AI model or the wiki and can be wrong. Check the **Looked at** line and linked pages. * **A sync is already running** on a card — wait for the running sync to finish, then ask again. * **A card failed** — the card shows the reason. Fix it, or open the page where you normally manage it. ### Security The assistant looks at CrossWatch with the same read-only tools as [MCP Connect AI](/crosswatch/settings/ui-settings/ai-help/mcp-connect-ai.md). Action cards run with your session, through the same checks as buttons elsewhere in CrossWatch. The assistant never runs them itself. The API key is stored encrypted, like other secrets. It is never sent back to the browser. Only links to this wiki and the CrossWatch GitHub repository are clickable in answers. CrossWatch limits each question to five minutes and eight lookup rounds. It runs at most two questions at once, caps provider-answer size, and does not follow redirects. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.crosswatch.app/crosswatch/settings/ui-settings/ai-help/assistant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.