scinotes_assistant

Description

The assistant is a side panel of SciNotes. You describe what you need in plain language; an AI agent writes the Scilab code, runs it in your Scilab session, looks at the plots it produces, reads the help pages, and edits the file open in the editor.

Scilab does not ship an AI model, and installs nothing. The assistant talks to an AI agent program that you install and log in to with your own account (subscription or API key). It uses the open Agent Client Protocol (ACP), the protocol code editors use to work with AI agents: any agent that supports it can be used, those listed below are known to Scilab. The agent talks to its provider's servers; Scilab gives it a set of tools (run code, read variables, capture figures, read and edit the editor file...) through a local MCP server.

Supported AI agents

Install at least one of these agents, then log in once in a terminal. Scilab finds the program automatically; the Settings page shows whether it is found.

The agents update themselves. Scilab only relies on the protocol, so a newer version normally works; the "Validated with" column gives the version known to work. What each agent offers depends on its own support of the protocol: the list of models, the effort levels, the token count, images in requests. For example, GitHub Copilot does not let Scilab choose the model (it routes each request itself), and Cursor and Antigravity do not report the tokens used.

Where Scilab looks for each program: the folders given in the agents catalogue (see The agents catalogue), then the PATH, and on Linux and macOS the usual install folders: ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, ~/.npm-global/bin, ~/.volta/bin, ~/.bun/bin and the node versions of ~/.nvm (Scilab started from the macOS Dock or a desktop menu does not get the PATH of your shell). For a program installed elsewhere, give its full path in the Settings page.

Opening the assistant and choosing an agent

Click the Assistant button at the right end of the SciNotes tabs, or use the Window > Assistant menu. The panel opens next to the editor; use the button or the menu again to close it.

The first time SciNotes opens, the assistant opens with it. Then SciNotes remembers whether you left the panel open or closed it: once closed, it opens only on demand. Drag the left border of the panel to resize it; its width is kept too.

The gear button of the panel (or the "agent · model · effort" chip under the input box) opens the Settings page. Its list shows, for each agent, whether its program is installed. When an agent is chosen, Scilab starts it at once: the page shows its version and the models it offers, and your first request does not wait for it to start. When the program is missing, the page shows how to install it. Then:

• Model: one of the models the agent offers, or a model name typed in. Until you choose one, the agent uses its own default, shown in the field.

• Effort: how much the model reasons before answering, for the agents that offer it.

• Executable: the path of the agent program when it is not found automatically (Save; Auto-detect forgets it).

Add an agent…, at the end of the agent list, adds any other ACP agent (see the list of ACP agents): give its name, its program (a name found on the PATH or a full path), the arguments that start its ACP mode, and environment variables if it needs some. Scilab starts it right away to check that it answers. For example, OpenCode: program opencode, arguments acp. The agents you added have a Remove this agent button.

These choices are stored in SCIHOME/assistant/assistant.json. The page also has the Open the assistant with SciNotes and Log conversations to disk options (see Files and privacy). Its ? button opens this help page. An agent left unused for 15 minutes is stopped; it starts again on the next request.

Permissions and sign-in

The assistant runs the Scilab tools (run code, read variables, capture figures, edit the editor file...) without asking: this is its job. The agent can also read and search files. Anything else the agent wants to do with its own tools — write or change a file, run a system command, fetch a web page, delete or move a file — is asked first: a card appears in the activity feed, with what the agent wants to do (the command, the file or the address) and its choices, usually Allow, Always allow (for the rest of the conversation) and Reject. The agent waits for your answer; a rejected request is reported in its answer. Stopping the request withdraws the question.

Some agents decide by themselves which actions they ask about: Codex, for instance, reviews its actions on its own servers and rarely asks. Your own settings of an agent (for example the permissions allowed in Claude Code) apply too.

When an agent needs you to sign in, a card offers its sign-in methods: one may open a browser page, another asks you to run a command in a terminal (then click I've signed in). The Settings page offers the same buttons when the agent reports that it is not signed in.

The agents catalogue

How to find and start each agent is not in the code: it comes from SCI/modules/scinotes/etc/assistant/agents.json. For each agent: its name, its program names, the arguments that start its ACP mode, extra folders where to look for it, environment variables, and the installation steps shown when it is missing.

Unfold Command line in the Settings page to see and change the arguments and environment variables of the agent, and the command run. Edit a field to change it, ↺ default to undo it, Reset all to undo every change of the agent. Copy copies the command, for example to ask for help on the Scilab forum. Paste a fix… applies a fix given as JSON, for one or several agents; an unknown name with a command adds an agent:

{"claude": {"env": {"ENABLE_TOOL_SEARCH": "false"}},
 "opencode": {"name": "OpenCode", "command": ["opencode"], "args": ["acp"]}}

The changes are saved in SCIHOME/assistant/agents.json, which holds only what differs from the defaults (same format; it can also be edited by hand, and is read again when it changes). A customized mark, and a dot on the chip under the input box, show that an agent was changed.

Using the assistant

• Editor context: the assistant knows the file active in SciNotes and the selected lines when you send your request (they are shown above the input box). Select code and ask "explain this", "optimize this", "why does this fail?"... Its edits apply to that file, even if you switch to another tab while it works; each edit is saved, and is undone by a single Ctrl+Z in the editor. If you close that file while it works, it stops editing instead of writing into another file; if you delete it, its changes stay in the editor without recreating the file; if you edit the file yourself meanwhile, it re-reads it instead of overwriting your changes, and a file with unsaved changes is never reloaded from disk.

• Your Scilab session: the code it runs executes in your session and in the current directory (pwd), and can use and change your variables. New files are created in the current directory.

• Files: type @ to reference a file of the current directory ("plot the columns of @data/measures.csv"). Attach files with the paperclip button, by drag and drop, or paste an image (15 MB at most per file).

• Code blocks of the answers have Run, Insert (at the cursor of the editor) and Copy buttons.

• Stop: while the assistant works, the send button becomes a stop button. A request is limited to 60 steps; when it stops on this limit, reply "continue".

• Conversations are saved automatically: the history button lists the last 20, to resume, rename or delete them. The + button starts a new conversation. When a conversation is resumed, the agent picks up where it left off; if it cannot (its own record of the conversation is gone, or you changed agent in the middle of a conversation), it is given the previous messages so that the conversation goes on.

• Enter sends the request, Shift+Enter inserts a new line, the up and down arrows recall your previous requests.

Skills

Skills are instruction files that teach the assistant how to handle a domain in Scilab. Scilab ships skills for graphics, GUIs, data import, signal processing, control systems, simulation (ODE, DAE), optimization, debugging, toolboxes, classdef and arguments blocks. The skills matching the words of your request are loaded automatically (the activity feed shows "Skill loaded: ..."); the assistant can load the others when needed.

You can add your own skills, or replace a built-in one, in SCIHOME/assistant/skills/<name>/SKILL.md (see SCIHOME). A skill is a Markdown file starting with a header:

---
name: mylab
description: Conventions of my lab: data formats, plotting style, helper functions.
triggers: lab, measure, bench, mylab
---

# My lab conventions
- Measurement files are CSV with a header line, read them with csvRead(..., ",", ".", "double", [], [], [], 1)
- ...

triggers is a comma-separated list of words or phrases (case and accents ignored) that load the skill automatically. Skills are re-read at each request: no restart is needed after an edit.

Files and privacy

• Your requests, the content of the active file, the files you reference or attach, and the results of the code run by the assistant are sent to the provider of the agent, under the terms of your account with that provider.

• The Scilab code the assistant runs is not confirmed first (see Permissions and sign-in): it can create or modify files from Scilab. Review what it did, and keep your work under version control.

• The MCP server that gives the tools to the agent listens on the local machine only (127.0.0.1), on a port chosen at each Scilab session. Scilab gives it to the agent for each conversation: the configuration files of the agents are not modified. An agent that only accepts local programs as MCP servers gets a small Java bridge started with the Java of Scilab.

• Files written by the assistant in SCIHOME/assistant/: saved conversations (conversations/), your skills (skills/), settings (assistant.json), your changes to the agents catalogue (agents.json) and, when the Log conversations to disk option is on (default), full transcripts of the conversations (logs/, 50 MB at most, oldest removed first). These logs stay on your machine; turn the option off if you do not want them.

• The agents keep their own record of the conversations, in their own folders (for instance ~/.claude for Claude).

Troubleshooting

• "<Name> not found": install the agent (see the table), check that its program runs in a terminal, then click the refresh button of the Settings page, or give the path of the program there.

• Not signed in (the Settings page shows "sign-in required", or the answer reports an authentication error): use the sign-in buttons, or run the login command of the table in a terminal, then retry.

• An agent answers but cannot use the Scilab tools, or fails after an update: compare its version, shown in the Settings page, with the "Validated with" column. Most agents can install a given version, e.g. npm install -g @agentclientprotocol/claude-agent-acp@0.85.1.

• Diagnostic logs: the exchanges with the agent (ACP messages) are written in TMPDIR/assistant.log (see TMPDIR); the conversation transcripts are in SCIHOME/assistant/logs/. Join them to a bug report.

See also

• scinotes — Scinotes: Embedded Scilab text editor
• SCIHOME — contains the path to preferences, history files of your Scilab session.
• TMPDIR — chemin du répertoire temporaire

History