Use the assistant

The assistant answers questions about the query in a tab, using an AI model you choose: Anthropic’s, or one on any server that speaks OpenAI’s chat completions, including one running on your own computer. It is off until you set it up, and it sends nothing until you ask it something.

What it can and can’t do

It can:

• Write a query from a description, or change the one in the editor.
• Explain a query plan: Explain this plan with the assistant, after you explain a query. Its answer links to the plan’s nodes.
• Explain a failed statement and suggest a fix: Fix this error with the assistant, after a statement fails.
• Propose a schema for an empty database, or one in Sketch, from a description of your app: Describe a schema.
• Name your query history and saved queries, if you turn that on.

It can’t:

• Run anything by itself. Proposed SQL goes into the editor when you choose Insert, and runs when you run it.
• Change data. Run read-only, on a proposed query, runs it in a read-only transaction that is rolled back, with the same checks agents get.
• See your rows, unless you select Include 20 result rows for one message.
• See tables the query doesn’t name. It is told about the tables in your SQL, not the whole database.
• Remember a conversation after you close its tab.

The assistant lives in query tabs. Open it with ⌘I on macOS or Ctrl+I on Windows and Linux, or Toggle assistant in the command palette.

Set up a provider

1. Open Settings (⌘, / Ctrl+,) and go to AI Assistant.
2. Turn on Assistant.
3. Choose a Provider:
   • Anthropic: Address is https://api.anthropic.com and Model is claude-sonnet-5-5 unless you choose another.
   • OpenAI-compatible, for LM Studio, LiteLLM, Ollama and other servers that speak OpenAI’s chat completions. Address starts as http://localhost:11434/v1, Ollama’s. Enter Model as your server names it, for example llama3.2.
4. Paste your API key and choose Save key. A local server usually needs none.
5. Choose Test connection. Alcuin asks once whether the assistant may send to this address: Let the assistant send to https://api.anthropic.com?. Choose Allow.

You’ll know it worked when Test connection says Answered in 412 ms by claude-sonnet-5-5., with your own time and model.

Where the key is kept

The key is saved in Alcuin’s secret store, encrypted with a key from your system’s keychain or keyring (Files and locations). Settings never shows it again, and Last message sent hides its value.

The key is tied to the address it was saved for. Change the address and Alcuin stops sending the key: Settings says The saved key belongs to another address, so it is not sent. Enter it again. Remove key deletes it.

On Linux with no keyring, the key is kept only until Alcuin quits.

The one address it calls

The assistant calls exactly one address: the one in Address. Alcuin refuses any other, and refuses redirects, so a request can’t be passed on somewhere else.

The first time an address is used, Alcuin asks in a dialog of its own, with Don’t send as the default. It asks again whenever the address changes. Settings, under Address, says where things stand:

• You allowed this address in Alcuin’s dialog.
• Alcuin asks you to allow it, in a dialog of its own, the first time it is used.
• You did not allow this address. Alcuin asks again after it restarts.

Ask it something

1. Open a query tab and write, or paste, the query you want to ask about.
2. Press ⌘I / Ctrl+I.
3. Type your question and press Enter. Shift+Enter starts a new line.
4. When the answer holds SQL, choose Insert to put it in the editor over the selection or at the cursor, or Run read-only to try it first.

The conversation stays with the tab. Clear starts it again, and Stop ends an answer early.

What is sent

Only when you send a message, test the connection, or use one of the tasks above, Alcuin sends the provider:

• the SQL in your editor, and the selection;
• the error, when you ask about one;
• the plan, when you ask about one;
• the database server’s version;
• for up to 20 tables your SQL names, their columns (with types, defaults and comments), keys and indexes;
• the 10 earlier turns of the conversation;
• 20 rows of the current result, only when you select Include 20 result rows. The box clears after each message.

Last message sent, in Settings, shows exactly what went the last time: the address, the headers (the key hidden) and the body. Privacy lists it all, including what the provider does with it.

Name history and saved queries is off by default. When it is on, opening the History panel sends the SQL of unnamed entries, with values taken out, to be named.

Turn it off

Turn off Assistant in Settings, under AI Assistant. Nothing is sent from then on, and the pane says The assistant is off. To remove the key as well, choose Remove key.

If it didn’t work

The pane shows the message without its code. Find the message here:

Message starts	Code	What to do
The assistant is off., There is no API key., There is no model set.	ALC-9003	Fill in what the message names, in Settings, under AI Assistant
Sending to … was not allowed.	ALC-3005	You chose Don’t send. Restart Alcuin, or set the address again, to be asked again
The API key was saved for another address	ALC-3005	Enter the key again for this address
The provider refused the API key	ALC-3005	Check the key with the provider, then save it again
The provider could not be reached	ALC-1001	Check Address, and that a local server is running
The provider took too long to answer.	ALC-2002	A request has 5 minutes. Try again, or ask a smaller question
The provider has no such endpoint or model	ALC-9002	Check Address and Model against the provider’s documentation
The provider is limiting requests, The provider answered …, The provider sent no answer.	ALC-9004	Wait and try again, or check your quota with the provider
Agents can run one SELECT, EXPLAIN or SHOW at a time, after Run read-only	ALC-4001	Run read-only uses the agents’ checks, so the message speaks of agents. Insert the query and run it yourself