AI assistant.

What it is, and what it is not#

AI is off until you configure a provider. When it is on, the Assistant tab in the right sidebar (⌘L/Ctrl+L) chats about the connected database. On the five SQL engines it works as an agent: it can propose actions, but every action appears as a card and runs only after you click it. It never changes anything by itself. On Redis and OpenSearch it is a chat that writes commands and queries for you.

Setting up a provider#

Settings → AI has a Provider switch.

• The key is encrypted with the operating system’s secret store and is never shown again (the field reads “Saved — paste a new key to replace”); Remove key deletes it. It stays in the main process: the interface sends prompts to it, and it makes the request.
• The model picker lists OpenRouter’s live model list, newest first, grouped by vendor (Anthropic, OpenAI, Google, xAI, Meta, Mistral, DeepSeek, Qwen, other), with context length, price, and whether a model supports tools, images or is free. You can star favourites, the last five used are remembered, and you can type an id that is not listed. The list is a public request to openrouter.ai that carries no key and none of your data; it is cached on disk for six hours. For a local server it lists the models the server reports; type a name to use one that is not listed.
• Tool calling. The agent needs a model that supports tool calling. Without it the local note says to pick one that does.

Until a provider is ready the panel says No API key (or No local model) and offers Open Settings. Codex and Claude Code need no key: if the program is missing or signed out, the chat says so when you send a message.

Your Codex or Claude Code plan#

If you already have Codex (a ChatGPT plan) or Claude Code (a Claude plan) installed and signed in, Plasma can drive that program instead of using an API key. Choose Codex or Claude Code as the Provider. Plasma finds the program on your PATH, in your login shell’s PATH and in the usual install folders; you can also choose the program yourself with the file picker (the file must be called codex or claude). The row under the provider shows whether it is installed, its version and whether you are signed in (with the plan name, never your e-mail address). Refresh checks again.

• Sign-in stays with the program. Plasma never sees or stores your ChatGPT or Claude credentials. If you are not signed in, run codex login or claude in a terminal.
• Where the data goes. The same items listed under What is sent go to OpenAI (Codex) or Anthropic (Claude Code) through the program, under your own account and your plan’s limits and terms. The schema and row-data switches apply exactly as they do for OpenRouter. When a plan limit is reached, the panel says so, with the reset time when the program reports one.
• What is turned off. Plasma runs the program in an empty folder that Plasma owns, with no approval prompts. For Claude Code, every built-in tool is off, and so are slash commands and skills; the only tools are Plasma’s. Claude Code may still read its own sign-in and configuration files, so Plasma does not claim it reads nothing from disk. For Codex, the shell, file-edit, browser, web search, plugin, hook and app features are switched off, the sandbox is read-only, and your own MCP servers from ~/.codex/config.toml are switched off for Plasma chats. What remains is not nothing: Codex still has apply_patch (the read-only sandbox blocks it), a clock tool, MCP-resource tools and sub-agent tools (which have the same limits), and a small code tool, because this version of Codex reaches any MCP tool through it. In our check, asking Codex or Claude Code to read /etc/hostname failed. If Plasma cannot confirm that your own Codex MCP servers are off, it does not start the chat. Every call to one of Plasma’s tools goes through the same guards and approval cards as with OpenRouter, one at a time.
• No session is kept. Every message starts a new run: Plasma sends the conversation so far, as a short transcript, with your latest message and asks the program not to save the conversation. Database memory notes are read once when a message is sent and not refreshed while the program works on it. What the program records beyond that, such as usage in your account, is up to OpenAI or Anthropic. The tools run in a loopback server that is open only while a chat runs, with a random key for that chat; it is separate from the MCP server you may enable.
• Stop ends the run and the program’s process. The program is also stopped when you close the window or quit, and after ten minutes in total.

What is sent#

The line under the message box always spells out what the next message will carry, built from the same rules the main process enforces. For example: OpenRouter · anthropic/claude-sonnet-5.5 · Schema: 12 tables · Current tab: sent · Row data: off.

• Production. On a connection tagged Prod, even the schema is withheld until you opt that connection in; the same control that enables row data does it, and it warns that it “also sends its schema names”.
• Row data is off by default, per connection. Turn it on or off with the Row data chip in the message box (Names only / Let the AI read rows). The agent’s read tool runs your query in a read-only session, so it cannot write, and results over the caps are cut and labelled as truncated.
• Schema context can be switched off entirely in Settings → AI. Then the agent is told it cannot see the schema and to ask you for names.
• Local provider. Requests go to the address you set, which must be on this computer.

The agent and its approval cards#

On PostgreSQL, MySQL/MariaDB, SQLite, ClickHouse and DuckDB the assistant has four actions. Each one is validated before you ever see it, and shown as a card.

• You can Reject any card; the assistant is told it was rejected, and is instructed not to retry the same thing.
• Before an action reaches you, Plasma re-checks that it still belongs to the connection that is open.
• A model call that fails validation (more than one statement, a write passed to run_query, unknown table) is answered to the model at once; you are never asked about it.
• Views: ask / apply (Settings → AI → Agent, “Apply view changes without asking”) lets show_table apply at once, with Undo. Running queries and changing data always ask first.
• Closing the window, reloading it or a crash cancels every waiting card.

AI tasks: fix, explain, ask#

Besides chat, three one-shot helpers use the same provider. They only suggest; nothing runs and nothing is applied without you.

• Fix with AI, on a failed query. It sends the failing SQL (up to the first part of a long statement) and the error message, plus the schema when schema context is allowed. You get one corrected statement and a short explanation, which replaces the failed statement in the editor if you accept; it is not run. Because a database error message can quote values from your data, treat the error text as data you are sending.
• Explain with AI, in the plan view. It sends the query and a one-node-per-line summary of the plan. The answer is a plain-English walk-through and at most three CREATE INDEX CONCURRENTLY suggestions, which you can open in the editor to review, never run.
• Ask in a table’s filter bar. Describe the view you want (“latest 10 orders, only id, total, created_at”); it sends the table’s column names and types, today’s date and your current view, and returns columns, sort, filters and a page size you can Apply and Undo. Filter values are hidden from the model unless row data is on. If the filter cannot be expressed as simple filters, it can return a single boolean expression, which is checked: it may not contain statement keywords such as SELECT or DROP.
• Ask AI about selection (⌘⇧L/Ctrl+Shift+L) in the editor, or Ask AI about this SQL, starts a chat turn with your SQL.

Images#

Attach, paste or drop images into the message box (PNG, JPEG, WebP or GIF; a GIF sends its first frame). You can attach up to 6 per message, and a conversation keeps the newest 12; older ones are replaced by a short note. Plasma downscales each image to at most 1,568 pixels on its long edge and re-encodes it to stay under a size limit before sending, and only images you attached are sent. Use a model that supports images.

Database memory#

Memory is a short list of notes about one saved connection, sent with every AI request for it. Use it for what the schema cannot say: “orders.amount is in cents”. Open it with the memory button in the Assistant header (Memory: N notes) or with Database memory… on the connection.

• Notes are one paragraph, up to 500 characters, up to 100 per connection. You can add, edit, search and delete them. Each is labelled with who wrote it: you, the assistant, or the MCP client by name.
• The assistant can propose notes (Remember cards) and propose removing wrong ones (Forget cards). You can edit the text before you approve, and Skip (Keep on a Forget card) declines. It is told to remember a business rule or a correction once per reply, and never to put row values, personal data, passwords or keys in a note.
• Secrets are refused. A note that looks like a password, key, token, a URL with credentials or a known secret of the connection is rejected with “Memory can’t hold passwords or keys.”
• Notes are treated as facts, not instructions: the prompt tells the model that a note cannot change its rules or permissions.
• The Use memory for this connection switch turns it off per connection; when off, no notes are sent.

Redis and OpenSearch#

On Redis the assistant answers with commands in a code block, and with row data allowed it can run a read-only allow-list of commands through a redis_command tool. On OpenSearch it answers with query DSL or SQL, and with row data allowed it can run read-only os_search and os_sql requests. The cards and memory tools described above belong to the SQL engines.