Skip to content

Home

Jump to bottom
alf edited this page Aug 15, 2026 · 21 revisions

FreeCAD AI -- AI-Powered 3D Modeling Assistant

Alpha software -- this project is in early development. Expect rough edges, breaking changes, and the occasional FreeCAD crash from LLM-generated code. Save your work frequently.

Latest release: v0.21.2-alpha -- two crash fixes (@s-light). list_documents raised an AttributeError on every FreeCAD 1.1.x session, not just the Flatpak build it was reported against (#57). And the execute_code sandbox pre-check could resolve a completely unrelated FreeCAD install -- a Snap on PATH while you run a Flatpak -- whose incompatible Draft/Arch/PySide stack segfaulted; it now resolves the console binary from the running session's own install, and no longer imports the real FreeCADGui, which unblocks generated code that imports Arch/BIM (#58). See execute_code for what the sandbox stubs out. Preceded by v0.21.1-alpha, which stopped truncated LLM replies from silently breaking Plan mode's Execute button (#50; @MusaAkyuz) and the Act-mode tool loop (#52), and by v0.21.0-alpha's managed backups directory with an optional max_backups cap (#46; @3dyuval) plus the .FCStd auto-save fix (#44; @FairlyInconspicuous). See the CHANGELOG for the full history.

FreeCAD AI is a workbench that adds an AI chat assistant to FreeCAD. Describe what you want to build in plain language and the assistant creates 3D models using structured tool calls or generated Python code. It supports multiple LLM providers, reusable skills, and project-level instructions -- all with zero external Python dependencies.

FreeCAD AI workbench overview

Key Features

  • Chat interface -- dock widget with streaming LLM responses, persistent layout across FreeCAD sessions (geometry and tab grouping restored on workbench activation)
  • Plan / Act modes -- review generated code before execution (Plan) or let the assistant execute automatically (Act). Plan mode includes Check and Fix with AI buttons for sandbox-validated code review (catches FreeCAD C++ console errors and invalid shapes that don't raise Python exceptions)
  • 53 built-in tools -- structured FreeCAD operations (sketch, edit sketch, pad, pocket, revolve, loft, sweep, fillet, chamfer, shell, patterns, mirror, boolean, datum planes & lines, transform, duplicate, viewport control, etc.) wrapped in undo transactions
  • 7 built-in skills -- reusable instruction sets the model invokes autonomously or via /command (enclosure, gear, fastener holes, thread inserts, lattice, sketch-from-image, skill-creator)
  • Skill optimizer -- iteratively improve skill instructions via test-evaluate-modify loop (/optimize-skill)
  • Hooks -- user-defined Python hooks for lifecycle events (block tools, modify input, log activity)
  • Thinking mode -- enable LLM reasoning chains (Off / On / Extended) for complex multi-step tasks
  • Context compacting -- automatically summarizes older messages when approaching context limits, with configurable context window size
  • Session resume -- conversations auto-save; reload any of the last 20 sessions
  • 20+ LLM providers -- Ollama, Anthropic, OpenAI, Gemini, OpenRouter, and 15 more (see table below), plus any OpenAI-compatible endpoint
  • Dark mode -- chat widget automatically adapts to FreeCAD's light/dark theme (theme changes require FreeCAD restart)
  • Vision routing -- auto-detects LLM vision capability via Ollama /api/show (authoritative) or OCR probe (other providers); non-vision models use MCP fallback. Ollama also reports tools and thinking capabilities, gating tool-call sends on per-model support
  • Image support -- attach viewport screenshots and images to chat messages (capture, attach, drag-drop, paste); auto-attach viewport on error retries so the LLM can see the resulting state
  • AGENTS.md support -- project-level instructions with include directives and variable substitution
  • User extension tools -- register your own Python functions as LLM-callable tools (.py or .FCMacro)
  • File attachments -- attach text files, PDFs, and documents to chat; binary files handled via hooks
  • MCP integration -- connect external Model Context Protocol servers to extend available tools, with per-server timeout configuration
  • Zero external dependencies -- uses only Python stdlib (urllib, json, threading, ssl)
  • FreeCAD-native preferences -- Edit → Preferences → FreeCAD AI page for the basics (provider, model, API key, mode, thinking, max tokens), kept in sync with the full AI Settings dialog via a JSON ↔ ParamGet bridge

Quick Start

  1. Installation -- clone or symlink the repo into FreeCAD's Mod directory
  2. Configuration -- select a provider, enter your API key, test the connection
  3. Getting Started -- open the chat panel and build your first model

Requires FreeCAD 1.0+ and an LLM provider (local Ollama or a cloud API key).

Supported Providers

Provider API Key Notes
Ollama No Local models, default http://localhost:11434
Anthropic Yes Claude models via native API
OpenAI Yes GPT models
Gemini Yes Google AI via OpenAI-compatible endpoint
OpenRouter Yes Multi-provider gateway
Moonshot Yes Kimi models (temperature locked)
DeepSeek Yes DeepSeek-V3
Qwen Yes Alibaba DashScope (international)
Groq Yes Ultra-fast inference
Mistral Yes Mistral models
Together Yes Open model hosting
Fireworks Yes Fast inference
xAI Yes Grok models
Cohere Yes Command models
SambaNova Yes Fast inference
MiniMax Yes MiniMax models
Llama Yes Meta's official Llama API
GitHub Yes (PAT) GitHub Models marketplace
HuggingFace Yes (hf_...) Serverless inference API
Zhipu Yes GLM models (z.ai international)
Custom Varies Any OpenAI-compatible endpoint

Tutorials

See Tutorials for the full list.

License

LGPL-2.1

FreeCAD AI Wiki

Clone this wiki locally