This page describes Calíope 1.5, the version we are building right now. 1.4 is finished and in App Review, and the store serves 1.3 on the Mac and 1.2 on iPad. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Tap AI in the workspace navigation bar. Type your request in the text area at the bottom — for example: "Give me the 10 customers with the most purchases last month".
The assistant generates the corresponding SQL and displays it in a code panel. With a provider ready — cloud ones need your key; Apple Intelligence and Ollama need none — responses are generated by the language model.
Choose the assistant's provider: Apple Intelligence needs no key; the cloud ones do.
Where it is: AI Assistant › Settings (gear)
Tap the gear icon in the AI Assistant header to open the settings panel. That is where you choose the provider: Apple Intelligence runs on the device itself and needs no key and no account; cloud providers ask for your API key and also let you pick a model.
The panel is drawn according to what the chosen provider needs. If it asks for no key, the key row is not there: it is not missing, it is not needed.
With a provider that does ask for a key and none saved yet, the assistant runs in demo mode, with sample responses based on pattern matching.
Keywords: api key, openai, gemini, configure, model, GPT, settings, apple intelligence, no key, on-device
The system model, on your device: no key, no cost, and nothing leaves for the internet.
Where it is: Calíope › Preferences › AI Assistant
Apple Intelligence is the system language model. It runs on the device itself: it needs no key and no account, it has no cost, and your question never leaves for the internet.
Two things are needed for it to show up in the picker: a compatible device, and Apple Intelligence turned on in System Settings. If either is missing, the picker does not offer it — it is not shown dimmed, it is simply absent, and the assistant keeps working with the cloud providers.
It does well on short requests: explaining an error, writing a query over one or two tables, recalling a piece of syntax. It does not do well on large schemas: its window is small, and when the schema does not fit the assistant says so in the conversation and proposes what to do.
That is where the Send schema to the model switch comes in, in that same panel and also in Preferences › AI Assistant. On, the table, column and foreign-key names of the active database are sent — never rows. Off, nothing of the schema is sent: name the tables in your question.
Recommendation: if the query is about a few tables, name them and turn the switch off. It is one more line to type, and with Apple Intelligence it is also what keeps the schema from overflowing.
Keywords: apple intelligence, on-device, no key, privacy, context window, schema, does not fit
A server for open models that runs wherever you say. No key and no per-query cost.
Where it is: Calíope › Preferences › AI Assistant
Ollama is a program that runs open language models on your own Mac. Install it from ollama.com and fetch a model with ollama pull <name> — for example ollama pull qwen2.5-coder. Calíope talks to it like to any other provider: no key and no cost per query.
What to write in the address. The default — http://127.0.0.1:11434 — works when Ollama runs on the same Mac. From the iPad or the iPhone you write the Mac's address on your network (http://192.168.x.x:11434), and there is a step that gets forgotten: by default Ollama only listens to itself. To let it accept connections from the network, start it with OLLAMA_HOST=0.0.0.0 ollama serve.
What travels. Your question and, with the Send schema to the model switch on, the table, column and foreign-key names of the active database — never rows. And it only reaches that address: on the same Mac it never leaves it; on the network it goes to that Mac and no further.
Which model. One meant for code gives considerably better SQL. A small one may answer in prose, with no SQL block, and then the assistant shows the text as it came and there is nothing to take to the editor; it may also invent column names your schema does not have. With a local model the wait is set by your computer, too: if you get a timeout, raise the generation limit in Preferences.
If it does not answer. The assistant says so with the address inside. Two things, checked in this order: that Ollama is running, and that the address written is its own.
An AI client on this Mac can list databases, describe tables and run read-only queries.
Where it is: Calíope › Preferences › AI Assistant
With the MCP server on, an AI client running on this Mac — Claude Desktop, Cursor, anything that speaks MCP — can ask Calíope to list databases, describe tables and run read-only queries against the connections you tick.
Where it runs. Inside Calíope, listening on 127.0.0.1 — that is, on this Mac only — and only while Calíope is open. Nothing is exposed to your network or to the internet: that is not a setting, it is how it is built.
What it sees. Only the connections you tick in Preferences › AI Assistant › MCP server. What you do not tick does not exist for the client: it is not even listed.
What it can do. Read, and nothing else. One statement per call, and only SELECT, SHOW, EXPLAIN or DESCRIBE: an INSERT, an UPDATE, a DROP or a SELECT … FOR UPDATE are rejected before the server is touched. Answers are capped at 200 rows.
The key. The server does not answer without it. It lives in this Mac's Keychain, does not travel to iCloud and is not part of the settings backup. If you think it leaked, «Generate a new key» invalidates the old one at once — and you have to paste the configuration into the client again.
If the port you choose is already taken by another program, Calíope tells you and does not start.
Keywords: mcp, server, client, claude desktop, cursor, read-only, token, port
Turn it on, tick the connections, copy the configuration and paste it into the client.
Five steps, in this order:
1. In Preferences › AI Assistant › MCP server, turn the switch on.
2. Tick the connections you want the client to see. What you do not tick stays invisible to it.
3. Press Copy configuration. Two blocks go to the clipboard, one per client, with your port and your key already in them.
4. Paste the block you need into your client's file:
- Cursor → ~/.cursor/mcp.json
- Claude Desktop → ~/Library/Application Support/Claude/claude_desktop_config.json
5. Restart the client. Clients read their configuration at startup.
Claude Desktop only speaks over standard input and output, not HTTP, so its block uses mcp-remote as a bridge — that is what npx is doing in that configuration.
Calíope has to be open for the client to find anything. Close it and the tools stop answering until you open it again.
Keywords: mcp, configure, cursor, claude desktop, mcp-remote, json, client
What your AI client sees, and what it does with it next
Rows do travel over MCP. They go to your client, on your machine; what it does next is its call.
Calíope's assistant sends the model, at most, the schema names. The MCP server is a different thing and it is worth saying plainly: rows do travel here, because the answer to a query is the data.
Where they go. To the client you configured, running on this same machine. Calíope sends nothing to the internet.
And afterwards. What that client does with what it receives — sending it to its cloud model to write the answer, for instance — is decided by that client and its privacy policy, not by Calíope. If that matters for your data, the decision is made before you tick the connection.
How to cut it off, from least to most:
- Untick the connection: it stops existing for the client.
- Turn the server off: they all stop answering.
- Generate a new key: the old one stops working at once, even if someone had it.
What is written down. Everything run over MCP lands in the query log, with the connection and the result, just like what you type yourself. What is rejected never reaches the server and leaves no row.
Send the AI-generated SQL directly to the SQL Editor.
Where it is: AI Assistant › Open in editor
When the assistant generates a SQL block, an Open in editor button appears below the code. Tapping it opens a new SQL Editor tab with the SQL pre-loaded, ready to review and run.
Keywords: load, editor, open, generated sql, insert, send to editor
The assistant receives the structure of the active database as long as the switch is on.
Where it is: Workspace › Tools › AI
With the Send schema to the model switch on — it is on out of the box — and a database selected, Calíope reads the list of tables, columns and foreign keys of the active schema and sends it to the model along with your request. That is what makes the SQL come back fitted to your real tables without describing them by hand. Not a single row of data is sent. You can change the context database from the selector in the assistant's header; it opens with a filter field, so you can find a database by name when the server has many.
With the switch off, nothing of the schema is sent and the tables have to be named in your question. That is the better choice when the query is about a few tables, and with Apple Intelligence it is also what keeps the schema from overflowing the model's window.
If the server account lacks permission to read the catalog, the assistant warns that the context could not be loaded. That warning is about a read that failed: turning the switch off does not produce it, because then nothing was read as nobody asked for it.
Control how much text the model can generate in each response.
Where it is: Calíope › Preferences › AI Assistant
AI models work with tokens — text fragments of approximately 0.75 words each. The Maximum SQL length setting determines how many tokens the model can generate in a single response. It affects only the output; it does not limit the length of your request or the schema sent.
Available options (in Preferences › AI Assistant › Generation):
- Compact (800 tokens) — Sufficient for simple queries: SELECT with one or two tables, basic filters, straightforward GROUP BY. Reduces cost per call and shortens wait time. Use it when your typical queries are short and direct.
- Standard (2,000 tokens) — Default value. Suitable for the vast majority of queries, including multi-table JOINs, subqueries, and moderate CTEs.
- Extended (4,000 tokens) — For very complex queries: multiple chained JOINs, multi-branch CTEs, stored procedures, or long analytical queries. Use it if the SQL appears cut off with the other options.
When to increase the length? If the generated SQL looks incomplete — for example, the FROM clause is cut off midway or a JOIN is missing its closing part — it means the model hit the limit before finishing. Switch to Extended to fix it.
When to reduce it? If you only run maintenance or quick diagnostic queries, Compact mode is sufficient and reduces cost when the provider charges per token, and shortens the wait when the model runs on your own machine — there what you pay is time.
The setting takes effect immediately; there is no need to restart the app or reopen the assistant.
Keywords: tokens, length, max tokens, truncated sql, truncated, cost, generation, maximum length
Adjust how long Calíope waits before cancelling an AI API call.
Where it is: Calíope › Preferences › AI Assistant
Some models take their time: reasoning models — OpenAI's o1, o3, or o4, or Gemini Ultra — and the ones running on your own machine, which answer at the speed of the computer running them. They can take more than 30 seconds to generate a response for complex queries. If Calíope cancels the call before the model finishes, you will see a timeout error that looks like an app failure when in reality more time was simply needed.
In Preferences › AI Assistant › Generation there are two sliders:
- Model list load timeout (5–60 s, default 15 s) — controls how long Calíope waits when fetching the list of models published by the chosen provider.
- SQL generation timeout (10–120 s, default 30 s) — controls how long Calíope waits to receive the SQL generated by the model.
When to increase the generation timeout? If you use a reasoning model, or a local one on a Mac without much memory, and receive errors when generating complex queries, raise the value to 60–90 s. These models think before responding and need more time.
When to leave it at the default? With gpt-4o or gemini-1.5-flash, 30 s is more than enough for the vast majority of queries.
Changes take effect immediately without restarting the app.
Use the microphone to transcribe your assistant requests in real time, without your voice leaving the device.
Where it is: AI Assistant › Microphone
Tap the microphone button next to the text field to activate dictation. Speak in the language shown on the capsule next to the microphone; the text appears in real time as you speak. The icon turns red while recording.
Tapping the button again stops dictation and the transcribed text remains in the field, ready to edit or send directly with ↩.
First time: the system asks for a single permission, the microphone. Speech recognition is no longer needed, because transcription never leaves the device. If you decline it, you can restore it in System Settings › Privacy & Security › Microphone.
Language: next to the microphone there is a capsule with the code of the language being heard — EN, FR, IT… — and while you record the field spells it out in full. By default it follows the language you set in Calíope, using your system's regional variant when there is one: the app in French on a Canadian Mac dictates in Canadian French. Tap the capsule to pick another one. Languages whose model is not on the device yet say so as they are offered, and if you pick one of those, a notice above the field reminds you that it will be downloaded the first time you dictate; the download happens once and from then on it works offline.
Your voice never leaves the device: transcription happens entirely here, with no audio sent to any server, so it also works offline. That is why, when the language model is missing, Calíope tells you instead of dictating over the internet.
Start error: if an error message appears when pressing the microphone, check that permissions are active and that no other app is using the microphone exclusively.
Save the full conversation history with the assistant as a text file.
Where it is: AI Assistant › Export (↑)
Tap the ↑ button (square with arrow) in the AI Assistant header to export the active conversation. The button is only enabled when there is at least one message from you in the history.
Tapping it opens the system save dialog. The default file name includes the current date and time: caliope_ai_YYYYMMDD_HHmm.txt.
Exported file contents:
- Header with export date and time
- Active database, AI provider, and model used
- All history messages, marked with [You] or [AI Assistant]
- Generated SQL blocks (if any), delimited with --- SQL ---
The file is saved as plain text (.txt) with UTF-8 encoding, compatible with any text editor or analysis tool.
Note: the history is volatile — it resets when you close the assistant tab. Export the conversation before closing it if you need to keep it.
AI-generated SQL requires verification and is sent to an external service.
Where it is: AI Assistant › SQL Panel
"AI-generated" notice
Every SQL block the assistant produces carries "AI-generated · Verify before running" at its foot, along with the name of the provider that generated it. Always review it before running: language models make logical mistakes and invent table names.
Where your question goes
It depends on the provider you choose, and there are five:
- OpenAI — to their servers. Your own key: platform.openai.com
- Google Gemini — to their servers. Your own key: aistudio.google.com
- Anthropic Claude — to their servers. Your own key: console.anthropic.com
- Apple Intelligence — nowhere: the model belongs to the system and runs on your device. No key.
- Ollama — only to the address you write: your own machine, or one on your network. No key.
With the three cloud providers, Calíope acts as a client of that service and never stores your key on servers of its own nor shares it: it lives in your device's Keychain.
What is sent
When you send a question, your text travels, along with the last 3 exchanges of the conversation and, if the "Send schema to the model" switch is on, the table, column and foreign-key names of the active database.
Table data, passwords and connection credentials are never sent.
Every conversation with the assistant is saved and can be resumed.
Where it is: AI Assistant › History (clock)
Click the clock icon in the AI Assistant header to open the history panel beside the chat. Each conversation is saved as soon as you send the first question, so a failed answer or a connection switch doesn't take your question down with it.
Resuming a conversation. Click a row in the list: it becomes the active conversation with all its context, and further questions continue that same thread. To start from scratch use the + button in the header; the previous thread stays in the history.
Searching. The field at the top searches plain text in the title and in every turn — including the generated SQL — not just in titles.
What each row shows. The title comes from your first question; below it you see the date, the database that was the context and how many questions the thread has.
Deleting. Context menu on a row to remove it, or the trash icon in the footer to delete the whole history.
Where it lives. On this device, in ~/Library/Application Support/Caliope/ai_history.json. The 200 most recent conversations are kept; when you reach that ceiling the panel footer says so. In narrow windows the panel collapses into a drawer and stays reachable from the side strip.
Optional: upload your conversations to your private iCloud so you have them on every device.
Where it is: AI Assistant › History › iCloud (cloud)
The history is local by default. Syncing is turned on with the cloud icon in the history panel footer, and Calíope asks first what to do with what you already have: upload the existing conversations or sync only new ones.
What gets uploaded. The title, the date, the context (connection, database, provider and model) and the full transcript: your questions, the answers and the generated SQL. It goes to the private database of your iCloud account, not to a Calíope server.
Credentials. Before leaving the device the text goes through the same redactor as the query log: an IDENTIFIED BY '…' or a SET PASSWORD becomes '***REDACTED***'. The local file keeps the original text.
When you turn it off Calíope asks whether to keep the conversations that are in iCloud on this device; if you download them, they are merged with the local ones keeping the most recent version of each.
If something fails the icon turns red: click it to see why (no iCloud account, restrictions, network) and retry or turn syncing off.
Deleting. Deleting a conversation or the whole history while syncing is on removes them from iCloud too.
Copy an answer, only its SQL, or the whole conversation.
Where it is: AI Assistant › Copy answer
Under every bubble there is a Copy answer button: it copies the text and, if the answer carries a SQL block, the SQL too. The button confirms with a checkmark for two seconds.
Only the SQL. In the code panel header, next to Open in editor, there is Copy SQL.
A single fragment. The text of the bubbles and of the SQL panel is selectable: drag over a part of it and copy with ⌘C.
The whole conversation. Context menu on a bubble to copy that turn, or context menu on a history row › Copy conversation to take the full transcript with its date and context header — the same format as the export button.