FreeCAD AI: an alpha workbench that turns prompts into Python for FreeCAD
AI-powered assistant workbench for FreeCAD — generate 3D models from natural language
At a glance
- What is it?
- FreeCAD AI is a FreeCAD workbench that asks an LLM for Python, then either shows you the code or runs it. It is alpha software with no external dependencies and a wide provider list, and the README is explicit that LLM-generated code can crash FreeCAD.
- Who is it for?
- Adopt FreeCAD AI if you already script FreeCAD in Python and want a chat panel that drafts code you review before it runs; the Plan mode plus the 50 structured tool operations exist precisely so you can check a proposal instead of trusting it. Do not adopt it as a production modeling pipeline, and do not point it at an unsaved document, because the README states that LLM-generated code occasionally crashes FreeCAD.
- Can I use it commercially?
- Yes, with conditions. LGPL-2.1 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap FreeCAD AI targets: scripting without writing the script
FreeCAD is scriptable through its Python console, but the distance between wanting a bracket with four bolt holes and having one is a session in the API documentation. FreeCAD AI closes that distance by putting a chat dock widget inside the application and asking a language model to produce the Python. The README frames the workbench as generating and executing Python code to create 3D models from natural language descriptions. The intended user is someone who already runs FreeCAD, has an LLM provider available (a local Ollama instance or an API key for a cloud service), and is willing to read generated code. It is not aimed at a user who wants a push-button model. The README opens with an alpha warning that names the risk directly: rough edges, breaking changes, and the occasional FreeCAD crash from LLM-generated code, with advice to save work frequently. That warning sets the tone for everything else in the repository.
Plan and Act, and why the tool layer is a different execution path
The workbench has two modes. In Plan mode the model's code is shown for review before anything runs. In Act mode it executes automatically. That split is the central design decision, and it maps onto two distinct mechanisms rather than one. The first is raw code generation: the model writes Python against the FreeCAD API, and the README states that failed code is sent back to the LLM for automatic retry, up to 3 attempts. The second is tool calling, described as 50 structured FreeCAD operations available in Act mode, positioned in the README as the safer and more reliable route. The distinction matters because a structured operation constrains what the model can emit, while free-form Python does not. Prompt construction is context-aware: document state, meaning objects, properties and selection, is included automatically. Around that sit optional layers. Tool reranking filters the registered tools down to the top-N most relevant per turn, using either keyword matching or an LLM, which the README presents as a way to save prompt tokens when many tools and MCP servers are registered. Skills are reusable instruction sets the model can invoke on its own or through a slash command, with examples given as enclosure, gear, fastener holes and sketch-from-image. Hooks let a user run Python at lifecycle events to block tools, modify input, log activity or convert file attachments. User extension tools let you register your own Python functions, as a .py file or an .FCMacro, as LLM-callable tools. Each of these is a separate surface with its own failure mode, and the README treats them as optional rather than required.
Installation is a symlink, and the target directory is version-dependent
There is no package to install. The README instructs you to clone or copy the repository into FreeCAD's Mod directory, and gives a symlink command per platform. On Linux: ln -s /path/to/freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai. On macOS the target is ~/Library/Application Support/FreeCAD/Mod/freecad-ai. On Windows, a symbolic link created as Administrator into $env:APPDATA\FreeCAD\Mod\freecad-ai, or a manual copy into %APPDATA%\FreeCAD\Mod\freecad-ai. The README then flags a trap that will catch people upgrading FreeCAD: FreeCAD 1.1 and later use version-scoped user directories, so on Linux the path becomes ~/.local/share/FreeCAD/v1.1/Mod/freecad-ai, with the equivalent versioned layout on macOS and Windows. The unversioned path still works on many builds but is no longer canonical. The stated symptom of getting this wrong is that the workbench does not appear after a restart. Requirements are FreeCAD 1.0 or later (the README says tested with 1.0.2 and 1.1.0) plus an LLM provider. The dependency footprint is unusual for a project of this scope: the README states zero external dependencies, using only the Python standard library, specifically urllib, json, threading and ssl. That means no pip step and no virtual environment to reconcile with FreeCAD's bundled interpreter.
Two settings UIs, one config.json, and a migration you should understand before upgrading
Configuration is reachable from two places that the README says stay in sync. The first is Edit, then Preferences, then FreeCAD AI, covering provider, model, API key, max tokens, mode, thinking and tool calling, persisted to FreeCAD's parameter store and mirrored into the workbench config on next load. The second is a Settings dialog behind the gear icon in the chat panel, which adds MCP servers, tool reranking, viewport capture, model parameters, hooks, system prompt overrides and dock layout. Both write to config.json under a directory the README calls <FreeCADAI dir>, resolved on workbench load in a defined order. First, the $FREECAD_AI_CONFIG_DIR environment variable, used as-is if set. Second, <FreeCAD user config dir>/FreeCADAI/ when running inside FreeCAD, which on FreeCAD 1.1 Linux is ~/.config/FreeCAD/v1-1/FreeCADAI/, obtained through FreeCAD.getUserConfigDir() when available and otherwise derived from FreeCAD.Version() plus $XDG_CONFIG_HOME. Third, ~/.config/FreeCAD/FreeCADAI/ as a legacy fallback for when FreeCAD is not importable, such as under pytest or a plain Python REPL. The README justifies placing data under XDG_CONFIG_HOME rather than XDG_DATA_HOME on the grounds that settings, secrets and conversation logs are config-shaped, while Mod/ and Macro/ belong under the data directory. That reasoning is sound, and it is also the reason the v0.13.0-alpha migration exists. The README documents a one-shot migration for users coming from v0.12.x and earlier: if a stale FreeCADAI/ already occupies the new target, it is renamed to FreeCADAI.pre-v0.13-snapshot/ rather than overwritten; then the first historical candidate with content is chosen as the source, either the FreeCAD user data directory location or ~/.config/FreeCAD/FreeCADAI/; then the source is moved with shutil.move, described as an atomic same-filesystem rename when possible, so no copy is left behind. If you keep anything in that directory by hand, read the migration table before upgrading, because a move is not a copy.
Where it breaks: alpha status, crash risk, and the wrong jobs for it
The README's own warning is the most important limitation, and it should be read literally: LLM-generated code can crash FreeCAD. Plan mode mitigates this by putting a human between generation and execution, but it does not remove the risk, and Act mode removes the human. The retry mechanism, up to 3 attempts, is a loop over a failure that may be a crash rather than an exception the workbench can catch. Version churn is the second constraint. The recent release list shows v0.24.0-alpha, v0.23.1-alpha and v0.23.0-alpha within about a week, and every one carries the alpha suffix. The README says to expect breaking changes. The migration from v0.12.x to v0.13.0-alpha, which moved the config directory, is a concrete example of a change that touches user data rather than just code. Third, this is the wrong tool for deterministic, repeatable geometry. If you need the same part every time from a script under version control, an LLM in the loop adds variance and a network or local-inference dependency where a plain Python macro adds neither. Fourth, features that look like conveniences carry their own setup cost: MCP servers, vision routing and file attachment conversion are optional paths, and the README notes that a no-vision-path configuration disables image controls entirely, so a model choice can silently remove functionality. Fifth, the provider list is long (20 providers plus any OpenAI-compatible endpoint), but a long list is not the same as uniform behaviour across those providers, and the README does not claim it is.
How it differs from driving FreeCAD through an MCP server alone
The obvious alternative is to skip the workbench and connect FreeCAD to a general coding agent through MCP. The difference is where the model's output lands. An MCP-only setup typically has the agent call tools exposed by a server, and the agent has no view of FreeCAD's live document unless something feeds it that state. FreeCAD AI inverts the arrangement: the chat panel lives inside FreeCAD, so document state (objects, properties, selection) is gathered automatically and included in prompts, and the model can either call one of the 50 structured operations or emit Python that runs in the same process. The README also supports the other direction, since v0.23.0-alpha added Streamable HTTP MCP transport and v0.24.0-alpha added an MCP bearer token, so external MCP servers can be registered and their tools exposed to the model. The trade-off is coupling. Running generated code inside the FreeCAD process is what makes the crash warning necessary, and it is also what makes context injection cheap. An external agent that talks to FreeCAD over a protocol keeps the blast radius smaller but has to be told about the document. Neither approach is strictly better; they fail differently. The same reasoning applies to comparing it with hand-written FreeCAD macros, which have no model dependency at all and no alpha warning, but also no natural-language entry point.
Maintenance, licensing and what to check before you commit
The licence is LGPL-2.1. For a FreeCAD addon that is a permissive-enough choice for most users, and it is compatible with linking into the FreeCAD process, but if you plan to redistribute a modified copy or bundle it with a commercial product, read the LGPL text yourself rather than treating this paragraph as advice. Maintenance cost is dominated by two things. The first is FreeCAD's own release cadence and its version-scoped user directories, which already forced a config path change and a migration in v0.13.0-alpha; expect that class of change again. The second is provider drift, since the workbench speaks to 20 named providers plus custom endpoints, and each provider's API can move independently of this project. The zero-dependency design helps here: there is no requirements file to update and no compiled extension to rebuild, so an upgrade is a git pull or a re-clone into the Mod directory plus a FreeCAD restart. Session resume and context compacting reduce the cost of losing a conversation, but they do not reduce the cost of a config migration. The practical check before adopting is narrow: confirm the workbench appears in the workbench selector after a restart, which validates that you symlinked into the correct Mod directory for your FreeCAD version, and confirm your chosen provider is reachable from inside FreeCAD rather than only from a terminal, since the workbench uses urllib and ssl from the standard library and inherits whatever proxy and certificate setup FreeCAD's Python has.
Editorial conclusion
Adopt FreeCAD AI if you already script FreeCAD in Python and want a chat panel that drafts code you review before it runs; the Plan mode plus the 50 structured tool operations exist precisely so you can check a proposal instead of trusting it. Do not adopt it as a production modeling pipeline, and do not point it at an unsaved document, because the README states that LLM-generated code occasionally crashes FreeCAD. Before installing, verify which Mod directory your FreeCAD build reads: on FreeCAD 1.1 and later the canonical path is version-scoped, for example ~/.local/share/FreeCAD/v1.1/Mod/freecad-ai on Linux, and a symlink into the legacy unversioned Mod/ is no longer canonical.
Community notes