ghbalf/freecad-ai

FreeCAD AI – AI‑assisted 3D modeling inside FreeCAD

What it is – A FreeCAD workbench that adds a chat‑style assistant. You type natural‑language commands (e.g., “make a 50 mm × 30 mm × 20 mm box”) and the assistant either generates Python code or calls a set of pre‑defined “tools” that perform the requested operation in FreeCAD. The result is inserted directly into the active FreeCAD document.

Key capabilities

• Chat UI docked inside FreeCAD, streaming responses from any of 22 supported LLM providers (OpenAI, Anthropic, Ollama, Gemini, etc.).
• Plan vs Act: Plan shows the generated code for you to review; Act can auto‑execute the code or, preferably, invoke structured tool calls that are wrapped in safe undo transactions.
• Tool library: 50 built‑in FreeCAD operations (create primitives, sketches, pads, pockets, boolean ops, fillets, patterns, export, etc.) plus a hook system for users to add their own Python functions.
• Vision support – images attached to the chat are sent to vision‑capable models; otherwise they are handled by a fallback MCP server.
• Session management – save/load chat sessions, automatic context summarisation, and fallback profiles if a provider is unavailable.
• Zero external dependencies – the workbench only uses the Python standard library.

How to get it

1. Install FreeCAD 1.0+.
2. Clone the repo and create a symbolic link (or copy) into FreeCAD’s Mod directory (paths differ per OS, see the README).
3. Restart FreeCAD; the FreeCAD AI workbench appears in the selector.
4. Open the workbench, configure an LLM provider (API key or local Ollama) via Edit → Preferences → FreeCAD AI or the gear‑icon settings dialog, then start chatting.

Typical workflow

1. Type a description.
2. In Plan mode, inspect the generated Python and press Execute (or Fix with AI if it fails).
3. In Act mode, let the model call tools directly for safer modelling, or fall back to raw code execution.
4. Use the built‑in tools (export_model, capture_viewport, etc.) or add custom tools via .py or .FCMacro files.

Who it’s for – CAD designers, hobbyists, or developers who want to experiment with natural‑language‑driven modeling without leaving FreeCAD. It is still alpha; expect crashes and breaking changes, so keep frequent backups.