Drive FreeCAD from pi to create 3D geometry, open and modify .FCStd files, batch-export to STEP/IGES/STL/DXF, and run natural language CAD commands. Use when the user asks to: create a 3D shape (box, cylinder, sphere), open or save a FreeCAD document, export .FCStd files to another format, batch-convert a folder of FreeCAD models, write FreeCAD Python scripts, or work with parametric/marine CAD models. The FreeCAD agent lives at skills/freecad/ and is exposed through five pi tools registered by the freecad extension: freecad_capabilities, freecad_prompt, freecad_create, freecad_export, and freecad_batch.
| Tool | What it does |
|---|---|
freecad_capabilities | Confirm FreeCAD is available; list capabilities |
freecad_prompt | Run a natural language command ("Create a box 100x50x25") |
freecad_create | Create a box/cylinder/sphere and save to .FCStd |
freecad_export | Open a .FCStd and export to STEP / IGES / STL / DXF / PDF |
freecad_batch | Batch-export all .FCStd files in a directory |
The agent requires an active document. freecad_create handles this automatically. When writing Python scripts against directly:
FreeCADAPIWrapperagent.new_document("MyPart") # ← required first
result = agent.create_box(100, 50, 25)
agent.save_document("/tmp/part.FCStd")
doc.recompute() after adding objectsFreeCAD never recomputes automatically. The wrapper calls it internally, but raw scripts must do it explicitly:
obj = doc.addObject("Part::Feature", "Box")
obj.Shape = Part.makeBox(100, 50, 25)
doc.recompute() # ← mandatory, not optional
Body container, single contiguous solid. PartDesign scripting does not work with Part objects and vice versa.The agent always runs headless (FreeCADCmd). Never import FreeCADGui or use view providers — they don't exist headlessly. The wrapper's mock fallback lets code run in dev even without FreeCAD installed.
# Natural language
freecad_prompt: "Create a cylinder radius 30 height 80"
# Explicit shape
freecad_create shape=box dimensions=[200,100,50] output_dir=/tmp
# Export existing file
freecad_export input_file=hull.FCStd output_file=hull.step format=STEP
# Batch export a folder
freecad_batch directory=./models pattern=*.FCStd
# Requires FreeCAD.app at /Applications/FreeCAD.app
skills/freecad/freecad_run.sh --show-capabilities
skills/freecad/freecad_run.sh --prompt "Create a box 100 50 25"
skills/freecad/freecad_run.sh --create box --dimensions 100 50 25 --output /tmp
skills/freecad/freecad_run.sh --file model.FCStd --export model.step --format STEP
skills/freecad/freecad_run.sh --batch --pattern "*.FCStd" --input-directory ./models
rules/python-scripting.md — Raw FreeCAD Python API patterns (when extending src/api/wrapper.py)rules/export-formats.md — Format fidelity tradeoffs (STEP vs STL vs DXF)rules/marine-engineering.md — Hull, mooring, FEM preprocessing patterns