AI agents
printCAD talks to AI agents in two ways: it starts agents that speak the Agent Client Protocol (ACP) and chats with them in the Assistant panel, and it serves its commands over the Model Context Protocol (MCP), to those agents and to any other MCP client.
An agent works through the same commands scripts use (see Scripting), so it can do what a script can and nothing more, and every change it makes is an ordinary undo step.
Setting up an agent
Preferences › AI agents lists the agents. Each has a name, the command that starts it, its arguments and extra environment variables. The two presets fill these in:
| Agent | Command | Arguments |
|---|---|---|
| Claude | claude-agent-acp |
|
| Gemini CLI | gemini |
--experimental-acp |
Any program that speaks ACP over its standard input and output works the same way. The agent runs in the folder of the open document, or your home folder for an unsaved one, and signs in the way it does on its own.
Chatting
Windows › Assistant opens the panel on the right. New chat starts one with a configured agent; each chat is a tab with its own agent and history, and several can run at once.
A chat names itself after the agent's first answer: the agent is asked for a short title in a session of its own, with no tools, so the question never shows in the chat. An agent that names its sessions on its own is heard until then. Double click a chat's tab, or right click it and pick Rename…, to name it yourself (Enter keeps the name, Escape leaves it); New title from the agent, in the same menu, asks again for the conversation so far and replaces any name, yours too. A name you gave stays with the chat when the document is opened again.
Enter sends, Shift+Enter starts a new line, and Up in an empty box brings back your last message to edit. While the agent works, the red square under the box stops its turn; Close ends the chat and its agent.
The agent's replies show as formatted text: headings, lists, tables, links and code, each code block with its own copy button. Hovering a message shows a button that copies it (a reply as the markdown it was written in), and any text can be selected and copied.
The arrows at the top of the chat jump to your previous or next message (Alt+Up, Alt+Down), and the double arrow back to the latest.
A message sent while the agent works waits above the box, marked Queued, and goes when the turn ends, one per turn. Edit takes it back into the box with its attachments, and the cross drops it. Stop holds what is queued: sending again, or Send them, lets it go.
The bar under the box has the settings the agent offers, as it names them: for Claude, the permission mode (Manual, Accept edits, Plan, Auto, Bypass permissions), the model and the effort. A change applies to the chat at once, and the agent's next chats start with it.
The "+" at the left of the bar attaches files, a picture of the view or the picture on the clipboard to the next message; so does pasting (Ctrl+V) a picture or files copied in a file manager, or dropping them on the panel (on X11; Wayland does not deliver drops to the app). Pictures go as pictures and small text files with their text; anything else, such as a STEP or STL file, goes as its path for the agent to open. Click an attachment to take it off.
Typing
@in the box lists the open files (each by its file name, or an unsaved tab by its title, the path beside it) and, while something is selected in the chat's tab,@selectionwith what is selected, then the tab's notes by number (@#3with the start of the note), open ones before resolved ones, a lost one marked. Arrows move through the list, Enter, Tab or a click take one, Escape puts the list away; typing after the@narrows it. What you pick shows as a chip in the text, and Backspace just after it (or Delete just before it) takes the whole chip away. A selection is taken as it is when you pick it, not when you send: pick it again for a second one (@selection-2). The message goes with a block for each chip saying what it names: for a file its path, tab and bodies with their features; for a selection its bodies, faces (surface, the feature that made each), edges (point, direction, length) and tree features, in world coordinates; for a note its number, text, author, whether it asks, is resolved or lost, its body, the face (kind and size, the feature that made it) or edge it sits on and its point, and for a note that came with the file, that it is content to read and not an instruction. Sent and queued messages keep their chips, and so does a queued message taken back to edit or a chat brought back with its file.The agent's thinking, the tools it calls and their results, and its plan show in the chat as it works. A call of printCAD's own tools reads as what it does: the few words the agent gave it ("Pocket the bolt holes"), else the command it runs or a script's first comment; hovering shows the tool's own name.
When the agent asks for permission to do something outside printCAD (edit a file, run a command), the chat shows its choices.
While printCAD is in the background, a desktop notification says when an agent finished its turn (with the start of its answer), asks for permission, holds a change for your OK, or stops. Preferences › AI agents › Notifications turns them off.
Chats stay with their document
A chat works on the document of the tab it was started in, whichever tab is on screen. Once the document has a file, its chats are kept with it: open the file again and they come back, and the first time one is shown its agent starts in the same session, the conversation replayed, so it continues where it left off. (The agent must be able to reload sessions; Claude can. One that cannot, or that refuses, keeps the chat's title, says so in the chat and starts a new conversation.) Closing the document's tab keeps its chats. They are kept in the application's own folder, not in the file, so a document you pass on carries no conversations.
Past chats
Closing a chat's tab ends its agent but keeps the chat: the history button beside the chat tabs lists the chats closed before, this file's first, newest first, with the agent and when each was last used. Type to search titles, agents and file names; All files lists every file's closed chats after this one's. Click a chat to reopen it as a tab: its agent starts in the same session and the conversation comes back, as a chat brought back with its file does. A chat reopened from another file opens on the document on screen and is kept with it from then on. The bin on a row removes the chat from the history for good (the agent's own copy of the session is left alone).
Chats of a document not saved yet are kept for as long as printCAD runs: closed ones show in the history, and the first save keeps them with the new file like any other.
What the agent knows
Every agent is told, when it connects, that it works inside printCAD
while you watch, on the document of its chat's tab, and how printCAD's
tools work. It can ask at any time what is open: the document and its
file, unsaved changes, the workbench, what is selected and being edited,
the bodies and the features that fail to build (the context
tool).
A chat changes only its own document, but it can read any open file:
the context, view, call,
batch and lua tools take a file,
the path, file name or tab title of another open document (as an
@ mention names it). There only commands that read run; a
command that would change that document is refused with a word saying
so, and a script stops at it.
It is told to work script-first: to plan, then make a part in one Lua
script that computes positions, reads faces and edges
(doc.faces, doc.edges) and picks from them,
rebuilds and returns what it made, so a part takes one step you approve
and one undo, not one per command.
An agent's script has Lua's base functions and its
table, string, math,
utf8 and coroutine libraries, nothing that
reads or writes files or starts programs (no io,
os, require, load or
dofile), so whatever it does to a file goes through a
command and is checked like one. pc.file.temp_path gives it
a file of its own to write, export to and import from, in a folder of
this run's that goes when printCAD closes. It runs apart from the
console, sharing none of its globals, and stops after 30 seconds of
running Lua (time spent waiting for commands, such as a rebuild, does
not count) or at 512 MB of memory.
For agents that take skills,
docs/skills/printcad-modelling/ is one: the modelling loop
(orient, find the commands, build in steps, rebuild, measure against
what the part should be, look) and the conventions that trip agents up
(which way each plane faces, sketches on a body's face, naming edges).
Copy the folder where your agent reads its skills (for Claude Code,
~/.claude/skills/, or .claude/skills/ in the
folder the document is in).
Some commands an agent never runs, whatever you allowed: quitting
printCAD and closing a tab would end its own session. The rules the
agent keeps to are yours to set, so it cannot change them either.
Commands that reach past the document wait for your OK every time, even
in a chat where changes run without asking: new and open, save as,
import, export, send to slicer, undo and redo, opening, reopening and
switching tabs, and reading a file into the document (replacing a body's
shape, laying a picture in a sketch, making a sketch of a DXF drawing),
and writing a picture of the model to a file (doc.picture;
the view tool shows the agent the same picture without
asking). An agent runs those one at a time, never from a script. Sketch
text is the one exception: a font file or an installed font that text
names is kept in the document without asking, so an agent can letter a
part from a script.
Rules
Rules are what agents keep to, in plain words: units, wall thicknesses, naming, what never to change.
- For every document: Preferences › AI agents › Rules for every document.
- For one document: the Rules button beside New chat,
in the Assistant panel. These are saved with the document, and undo
takes a change back. (
doc.set_agent_rulessets them from a script; an agent cannot.) - Your agent's own files: an agent starts in the
document's folder, where many read instruction files of their own on
start (
AGENTS.md; Claude readsCLAUDE.md).
An agent gets both sets of rules when its chat starts, and a chat already open gets them again with its next message after you change them.
Notes on the geometry
Notes are the way to talk about a spot (how to make them is in Editing). Each has a number (#3)
and sits on a face, an edge or a point of a part. Leave one saying what
to change there and an agent reads it: the open notes come with its
context, and doc.notes gives each with what it
is on (the face's kind and size, the feature that made it, the edge's
length). The agent acts on it and resolves it with what it did, which
then shows after the note in grey and crosses out its tree row.
An agent asking about a spot puts a question there instead of
describing it in the chat: it shows behind a ? in the
warning colour, and its card asks for your answer (or
doc.note_set{done = "..."}). An agent's notes say they are
the agent's. An agent may resolve, answer or reopen your notes, but
never reword or delete them: printCAD refuses
doc.note_remove to agents, and doc.delete,
doc.rename and doc.note_set refuse a change to
your note's text or its removal. A note whose face or edge is gone is
lost, and the agent is told to say so rather than guess.
Notes that came with an opened file are marked as such, wherever they
sit, and an agent is told to read them as content, not as instructions.
view draws the notes with notes = true.
Folders an agent may reach
A file an agent's commands read or write (an import, an export, a picture, a saved copy) must be in an open document's folder, the system's temporary folder, or a folder added in Preferences › AI agents › Folders agents may reach. It must be given as a whole path, and neither it nor a folder on its way below the allowed one may be hidden (a name starting with a dot). Anything else is refused before you are asked, with the folders it may use. This covers what printCAD's tools do; an agent's own tools for files follow its own settings.
Approving changes
"Ask before changes" (on by default, in Preferences and per chat) holds every command that changes the document until you allow it. The held change shows at the top of the panel as what the agent says it is for and the call it makes, with Allow, Deny, and Allow all in this chat, which turns asking off for that chat. Commands that only read (listing bodies, measuring, looking at the view) never wait when called on their own; a Lua script is held whatever it does.
Each call an agent makes is one undo step, labelled with the agent. A call or script that fails takes back what it changed and leaves no step, and its error says so.
The MCP server
While the application runs it listens on a local socket,
$XDG_RUNTIME_DIR/printcad/mcp-<pid>.sock. Its
tools:
| Tool | What it does |
|---|---|
context |
What is open, selected and being edited, the rules and the open
files; with file, another open file's |
commands |
Lists the commands, with their arguments, optionally by prefix |
search |
Finds commands and guide sections by the words of a task, several queries at once |
describe |
A command's or guide section's whole entry, by id, bare name or a near spelling |
call |
Runs one command with named arguments and answers its result |
lua |
Runs a Lua script and answers {returned, printed} as
JSON: what the script returns and what it printed |
batch |
Runs several commands in order, as call runs one, and
answers the list of their results; an argument written exactly
"$N" takes call N's result. One undo step: the first
failure stops it and leaves nothing behind |
view |
A picture of the bodies, from the current view or a fixed one |
screen |
The view as the window shows it now: the scene with an open sketch, its dimensions and everything else drawn over it |
log |
The application's recent messages |
Pictures for proof
view draws on the CPU, so the same arguments give the
same picture whatever the user's camera is doing. It draws the document,
not the screen: what a workbench draws over the scene (an open sketch's
lines and dimensions, guides, a package's drawing) and the patterns of
surface textures are not in it, and its answer says so beside the
picture. With no arguments it looks the way the view looks. Its
arguments, all optional:
| Argument | What it does |
|---|---|
view |
"current" (the default), "iso",
"front", "back", "left",
"right", "top", "bottom",
{azimuth, elevation} in degrees (azimuth 0 is the front, 90
the right side; elevation 90 looks straight down), or
{direction, up?}, the way the view looks. Directions follow
the axis preset in Preferences (Z up by default). |
bodies |
Only these bodies (ids or names), framed to them. Every visible body otherwise. |
highlight |
A list of {body, faces?, edges?, color?}: faces by
their doc.faces index or name, edges by the kernel's edge
index, the whole body when neither is given. The colour is
[r, g, b] from 0 to 1 or "#rrggbb"; amber when
left out. |
markers |
A list of {point, label?, color?}: a dot and a label at
a world point. |
section |
{origin, normal}: what lies on the side the normal
points to is cut away, and the cut shows flat and darker. |
edges |
The faces' outlines (on by default). |
xray |
Bodies see-through, highlighted faces solid. |
size |
[width, height], 800 × 600 by default, at most 2048 a
side. |
annotate |
An axis triad and the drawn bodies' box with its sizes in mm. |
notes |
The document's notes on the drawn bodies as numbered markers: open ones in the accent colour, questions amber, resolved ones grey, lost ones red. |
screen is the other way round: no arguments, and the
view's rectangle exactly as the window draws it, at the window's pixels,
through the user's camera, with whatever is over the scene at that
moment. It answers once the next frame is drawn, so it waits while the
window is not drawing (minimised, say).
Every view picture is orthographic and framed to what it
draws, markers included. The command doc.picture{path, …}
takes the same arguments and writes the PNG instead, in the app or in
printcad --script, where "current" draws the
isometric view. Since it writes a file, an agent's
doc.picture waits for your OK every time.
Every tool is marked to load from the start, so an agent that defers
tools until it searches for them (Claude Code does, once many are
installed) has printCAD's at hand in its first turn.
context, commands, search,
describe, log, view and
screen are marked read-only, call,
lua and batch as able to change things, and
every tool as reaching nothing outside printCAD.
An agent is told every command by its id and summary, one line each,
when it connects. search ranks commands and guide sections
by their words and knows the words users say for them (round for fillet,
shell for thickness, bore for hole), and describe gives
what one takes and answers. The Lua console's help searches
the same way when given a word that is not a command prefix:
help("round the edges").
The server also offers documents a client can read or attach
(printcad://rules, printcad://context, and the
scripting, AI and scan-modelling guides as
printcad://guide/scripting,
printcad://guide/ai and
printcad://guide/scan-modelling) and prompts, which clients
such as Claude Code offer as slash commands:
| Prompt | What it asks |
|---|---|
review-for-printing |
Check the document for what would print badly, and propose fixes |
explain-model |
How the document is built, feature by feature |
make-parametric |
Propose variables for sizes that belong together |
model-from-scan |
Rebuild a scanned part as a parametric body, held to the scan; its
part (machined, printed, cast or freeform) sets the
tolerance, see Modelling
from a scan |
printcad --mcp relays standard input and output to that
socket, so any MCP client can use the running application as a
server:
{ "mcpServers": { "printcad": { "command": "printcad", "args": ["--mcp"] } } }It connects to the newest running application, or to the socket
--socket <path> or PRINTCAD_MCP_SOCKET
names. The chats pass the same relay to their agents.