printCAD GitHub Download

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.

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.

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.

This page's source