AI-powered CAD modeling inside FreeCAD.
Describe what you want to build. Claude builds it.
Claude CAD is for architects and engineers what Claude Code is for software engineers. It embeds a Claude agent directly inside FreeCAD with structured tool calling — not code generation — to create, position, and combine 3D geometry with precision.
Note
Claude CAD is early-stage software. It works well for primitives, booleans, and simple assemblies. Complex sketch-based features (lofts, sweeps) use a code execution fallback. Contributions welcome.
You: make a 50mm cube with a 20mm hole through the center
● create_object Box 'Cube' (Length=50, Width=50, Height=50)
● create_object Cylinder 'Hole' (Radius=10, Height=60)
● modify_object Hole: x=25, y=25, z=-5
● boolean_operation Cut(Cube, Hole)
● Model updated.
No prompt engineering. No copy-pasting scripts. Describe parts and watch them appear.
# macOS
git clone https://github.com/milolabs-team/claudecad.git \
"$HOME/Library/Application Support/FreeCAD/v1-1/Mod/ClaudeCAD"
# Linux
git clone https://github.com/milolabs-team/claudecad.git \
~/.local/share/FreeCAD/Mod/ClaudeCAD
# Windows (PowerShell)
git clone https://github.com/milolabs-team/claudecad.git `
"$env:APPDATA\FreeCAD\Mod\ClaudeCAD"Create a .env file in the addon directory:
ANTHROPIC_API_KEY=sk-ant-...
Or export before launching FreeCAD:
export ANTHROPIC_API_KEY=sk-ant-...Important
You need a Claude API key from console.anthropic.com. Claude CAD uses Sonnet 4 by default.
In FreeCAD: Macro > Macros > select launch_ai_assistant > Execute
The Claude CAD panel appears on the right side of FreeCAD.
Claude CAD uses 6 structured tools instead of monolithic code generation. Each tool handles its own transactions, validation, and error enrichment.
| Tool | What it does | When Claude uses it |
|---|---|---|
query_scene |
Inspect objects, bounding boxes, properties | Before modifying anything |
create_object |
Create Box, Cylinder, Sphere, Cone, Torus | Any primitive geometry |
modify_object |
Change dimensions, properties, placement | Repositioning, resizing |
boolean_operation |
Cut, Fuse, Common with overlap validation | Combining/subtracting shapes |
search_objects |
Find objects by name, type, or property | Locating existing geometry |
execute_code |
Raw FreeCAD Python | Sketches, fillets, lofts, sweeps |
The boolean_operation tool alone eliminates an entire class of bugs. FreeCAD booleans use .Base and .Tool — but Claude models trained on older docs often generate .Shape1 and .Shape2, which silently fail. By wrapping the operation in a tool, we handle this correctly every time, validate that objects actually overlap, and provide diagnostic errors when they don't.
execute_code is the escape hatch, equivalent to Claude Code's Bash tool. It's used for complex geometry that the structured tools can't express: sketches with constraints, extrusions, fillets, chamfers, lofts, and sweeps.
┌─────────────┐
│ ai_panel │ Qt dock widget, message rendering
│ (UI layer) │ main thread — FreeCAD objects
└──────┬──────┘
│ events
┌──────┴──────┐
│ ai_loop │ Agent loop state machine
│ (control) │ retry caps, turn limits
└──────┬──────┘
┌─────┴─────┐
┌────┴───┐ ┌────┴────┐
│ai_tools│ │ai_client│
│(FreeCAD│ │ (HTTP) │
│ ops) │ │ thread │
└────────┘ └─────────┘
| File | Lines | Purpose |
|---|---|---|
ai_panel.py |
823 | UI layer — Qt dock widget, event rendering, file upload |
ai_tools.py |
472 | Tool implementations with transactions and error enrichment |
ai_prompt.py |
295 | System prompt + 6 tool schemas |
ai_context.py |
199 | Scene introspection + conversation compaction |
ai_loop.py |
189 | Generator-based agent loop |
ai_client.py |
91 | Claude API client (stdlib urllib, zero deps) |
Claude CAD was built by studying Claude Code's architecture and transferring effective patterns to CAD:
- Agent loop — Generator-based state machine with multi-tool support, 3-retry cap on consecutive errors, 15-turn cap per request
- Tool routing — System prompt explicitly says "use
create_objectNOTexecute_codefor primitives" - Anti-gold-plating — "Don't add fillets unless asked. A box with a hole = one Box + one Cylinder + one Cut. Nothing more."
- Error recovery — On failure, query the scene to see what actually happened, fix the specific issue, don't regenerate everything
- Context budgeting — Tool results capped at 4K chars, conversation compacted at 80K chars
- Main-thread execution — API calls on background QThread, tool execution on main thread (FreeCAD objects aren't thread-safe)
The panel UI was built from the actual Claude Code VS Code extension source (v2.1.101):
- Exact color tokens (
#d97757,#c6613f,#faf9f5) - Send button: 26x26px, border-radius 5px,
#c6613f - Spinner: 12-frame symbol rotation (
·✢*✶✻✽) at 120ms with all 87 verbs (Clauding, Noodling, Flibbertigibbeting...) - Timeline dots: success
#74c991, failure#c74e39 clawd.svgmascot from extension resources
- Vision — Upload reference images or capture the FreeCAD viewport. Claude sees the image and builds to match.
- Context-aware — Every API call includes current scene state (object names, dimensions, positions).
- Self-correcting — If a boolean fails, Claude reads the error, queries the scene, fixes placement, retries.
- Undo — Every tool call is wrapped in a FreeCAD transaction. One-click undo.
- Conversation memory — Claude maintains context across tool calls within a session.
- Zero dependencies — Pure Python stdlib. No pip install needed.
"make a box with a hole through the center"
"add 4 bolt holes in the corners, 5mm diameter, 8mm from each edge"
"fillet all edges at 2mm radius"
"create an L-bracket, 50mm base, 40mm upright, 5mm thick"
"make it 20% larger"
"subtract a slot 30mm long and 5mm wide through the middle"
| Version | |
|---|---|
| FreeCAD | 1.0+ |
| Python | 3.10+ (ships with FreeCAD) |
| API key | Anthropic Console |
| Dependencies | None (stdlib only) |
Claude CAD is open source under the MIT license. Issues and PRs welcome.
The system prompt (ai_prompt.py) is the product — improvements to tool descriptions, spatial reasoning hints, and worked examples have the highest impact.