Skip to content
Back to search

freecad-ai

AI-powered assistant workbench for FreeCAD — generate 3D models from natural language

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ghbalf/freecad-ai with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ghbalf/freecad-ai'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ghbalf--freecad-ai/badge.svg)](/listings/ghbalf--freecad-ai)

HTML

<a href="/listings/ghbalf--freecad-ai"><img src="/api/listings/ghbalf--freecad-ai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone or copy this repository into FreeCAD's Mod directory:

Linux

ln -s /path/to/freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai

macOS

ln -s /path/to/freecad-ai ~/Library/Application\ Support/FreeCAD/Mod/freecad-ai

Windows

# Run as Administrator
New-Item -ItemType SymbolicLink -Path "$env:APPDATA\FreeCAD\Mod\freecad-ai" -Target "C:\path\to\freecad-ai"

Or manually copy the repository into `%APPDATA%\FreeCAD\Mod\freecad-ai`.

> **FreeCAD 1.1+ uses version-scoped user dirs.** The `Mod` directory moved > under a per-version folder, so on Linux the path is > `~/.local/share/FreeCAD/v1.1/Mod/freecad-ai` (e.g. `v1.1`, `v1.2`), with the > equivalent `…/FreeCAD/v1.1/Mod/` layout on macOS and Windows. If the > workbench doesn't appear after a restart, check that you symlinked into the > versioned `Mod/` for the FreeCAD release you're running. The legacy > unversioned path above still works on many builds but is no longer canonical.

---

Restart FreeCAD. The **FreeCAD AI** workbench will appear in the workbench selector.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 605 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # FreeCAD AI
  2. > **Alpha software** — this project is in early development. Expect rough edges, breaking changes, and the occasional FreeCAD crash from LLM-generated code. Use with caution and save your work frequently.
  3. An AI-powered assistant workbench for FreeCAD that generates and executes Python code to create 3D models from natural language descriptions.
  4. ## Features
  5. - **Chat interface** — dock widget with streaming LLM responses
  6. - **Plan / Act modes** — review code before execution (Plan) or auto-execute (Act)
  7. - **Tool calling** — 50 structured FreeCAD operations (Act mode) for safer, more reliable modeling
  8. - **Tool reranking** — optional keyword or LLM-based filter sends only the top-N most relevant tools to the LLM per turn, saving prompt tokens when many tools + MCP servers are registered
  9. - **Skills** — reusable instruction sets the model invokes autonomously or via `/command` (enclosure, gear, fastener holes, sketch-from-image, etc.)
  10. - **Skill optimizer** — automatically improve skill instructions via iterative test-evaluate-modify loop (`/optimize-skill`)
  11. - **Hooks** — user-defined Python hooks for lifecycle events (block tools, modify input, log activity, convert file attachments)
  12. - **User extension tools** — register your own Python functions as LLM-callable tools (`.py` or `.FCMacro`)
  13. - **Vision routing** — auto-detects LLM vision capability; non-vision models use MCP fallback via [llm-vision-mcp](https://github.com/ghbalf/llm-vision-mcp), no-vision-path disables image controls
  14. - **File attachments** — attach images, text files, and documents to chat messages (capture, attach, drag-drop, paste); extensible via `file_attach` hook for binary formats (PDF, DOCX) or MCP servers for rich conversion
  15. - **Image support** — viewport screenshots and images sent as vision blocks; auto-detected binary format rejection (PDF, ZIP, Office docs)
  16. - **Thinking mode** — enable LLM reasoning for complex multi-step tasks (Off / On / Extended)
  17. - **Context compacting** — automatically summarizes older messages when approaching context limits
  18. - **Fallback profiles** — when the chat model can't be reached (Ollama box off, vendor 503, revoked key), the turn is tried once on each profile you list, in order, and a note says which one answered
  19. - **Session resume** — save and load chat sessions to continue work later
  20. - **25 LLM providers** — Anthropic, OpenAI, Ollama, Gemini, OpenRouter, Requesty, Cloudflare Workers AI, Moonshot, DeepSeek, Qwen, Groq, Mistral, Together, Fireworks, xAI, Cohere, SambaNova, MiniMax, Llama, GitHub Models, HuggingFace, Zhipu, Perplexity, DemonRoute, Runcrate, plus any OpenAI-compatible endpoint via Custom
  21. - **Context-aware** — automatically includes document state (objects, properties, selection) in prompts
  22. - **Error self-correction** — failed code is sent back to the LLM for automatic retry (up to 3 attempts)
  23. - **AGENTS.md support** — project-level instructions with include directives and variable substitution
  24. - **Dark mode** — chat widget automatically adapts to FreeCAD's light/dark theme (theme changes require FreeCAD restart)
  25. - **Persistent dock layout** — the chat dock remembers its position, tab siblings (e.g. tabified with the Tasks panel), and floating geometry across FreeCAD sessions
  26. - **Zero external dependencies** — uses only Python stdlib (`urllib`, `json`, `threading`, `ssl`)
  27. ## Requirements
  28. - FreeCAD 1.0+ (tested with 1.0.2 and 1.1.0)
  29. - An LLM provider (local Ollama, or an API key for a cloud provider)
  30. ## Installation
  31. Clone or copy this repository into FreeCAD's Mod directory:
  32. ### Linux
  33. ```bash
  34. ln -s /path/to/freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai
  35. ```
  36. ### macOS
  37. ```bash
  38. ln -s /path/to/freecad-ai ~/Library/Application\ Support/FreeCAD/Mod/freecad-ai
  39. ```
  40. ### Windows
  41. ```powershell
  42. # Run as Administrator
  43. New-Item -ItemType SymbolicLink -Path "$env:APPDATA\FreeCAD\Mod\freecad-ai" -Target "C:\path\to\freecad-ai"
  44. ```
  45. Or manually copy the repository into `%APPDATA%\FreeCAD\Mod\freecad-ai`.
  46. > **FreeCAD 1.1+ uses version-scoped user dirs.** The `Mod` directory moved
  47. > under a per-version folder, so on Linux the path is
  48. > `~/.local/share/FreeCAD/v1.1/Mod/freecad-ai` (e.g. `v1.1`, `v1.2`), with the
  49. > equivalent `…/FreeCAD/v1.1/Mod/` layout on macOS and Windows. If the
  50. > workbench doesn't appear after a restart, check that you symlinked into the
  51. > versioned `Mod/` for the FreeCAD release you're running. The legacy
  52. > unversioned path above still works on many builds but is no longer canonical.
  53. ---
  54. Restart FreeCAD. The **FreeCAD AI** workbench will appear in the workbench selector.
  55. ## Configuration
  56. There are two ways to configure FreeCAD AI:
  57. - **Edit → Preferences → FreeCAD AI** has four pages (Provider, Behavior, Tools, MCP) showing the same settings as the workbench's Settings dialog (gear icon); both write `config.json` directly.
  58. - **Workbench Settings dialog** (gear icon in the chat panel) — the same four pages in one window.
  59. Both UIs edit the same file, `<FreeCADAI dir>/config.json`; FreeCAD's own parameter store (`user.cfg`) holds no FreeCAD AI settings.
  60. ### Configuration paths
  61. `<FreeCADAI dir>` is resolved on workbench load. The order is:
  62. 1. **`$FREECAD_AI_CONFIG_DIR`** environment variable, if set. Used as-is.
  63. 2. **`<FreeCAD user config dir>/FreeCADAI/`** when the workbench is running inside FreeCAD. On FreeCAD 1.1+ Linux this is `~/.config/FreeCAD/v1-1/FreeCADAI/` (version-scoped, top-level alongside FreeCAD's own `FreeCAD.conf`, `user.cfg`, `system.cfg`). The path is obtained via `FreeCAD.getUserConfigDir()` when available, otherwise derived from `FreeCAD.Version()` plus `$XDG_CONFIG_HOME` (default `~/.config`).
  64. 3. **`~/.config/FreeCAD/FreeCADAI/`** (legacy) when FreeCAD is not importable — pytest, console scripts, plain Python REPL.
  65. > **Why under `.config/FreeCAD/v1-1/`?** FreeCAD 1.1 introduced version-scoped user dirs so different FreeCAD installs don't share settings. The workbench's data is config-shaped (settings, secrets, conversation logs) so it belongs under `XDG_CONFIG_HOME` (default `~/.config/`), not `XDG_DATA_HOME` (`~/.local/share/`, where `Mod/` and `Macro/` live). v0.13.0-alpha aligns with that XDG split.
  66. #### One-shot migration on first launch of v0.13.0-alpha+
  67. Users upgrading from v0.12.x and earlier are auto-migrated on first launch. Migration is rename-then-move with a two-stage candidate search and an automatic sweep:
  68. | # | Action |
  69. |---|---|
  70. | 1 | If a stale `FreeCADAI/` already exists at the new target (e.g. created by FreeCAD 1.1's own first-launch migration of `~/.config/FreeCAD/`), rename it to `FreeCADAI.pre-v0.13-snapshot/`. Frees the target name without overwriting. |
  71. | 2 | Pick the first **historical candidate** that has content as the migration source: (a) `<FreeCAD user data dir>/FreeCADAI/` (the v0.13.0-alpha pre-release wrote here briefly — only relevant on the maintainer's machine; released builds skip this), (b) `~/.config/FreeCAD/FreeCADAI/` (every released build before v0.13.0-alpha). |
  72. | 3 | **Move** (`shutil.move` — atomic same-filesystem rename when possible) the source → `<FreeCAD user config dir>/FreeCADAI/`. The source ceases to exist; no copy is left behind. |
  73. | 4 | **Sweep** any remaining historical candidates that *still* have content — rename them to `<candidate>.duplicate-cleanup/` (or `.duplicate-cleanup-<unix-ts>/` if the suffix is taken). Catches data left behind by an aborted/copy-based prior migration. |
  74. | 5 | Drop a marker file `<target>/.freecad_ai_active_marker` so subsequent imports skip migration. |
  75. The sweep also runs on **every** subsequent launch (cheap when no candidate dirs exist), so any leftover state from a partially-completed prior migration gets cleaned up automatically as soon as the new code runs.
  76. The renamed `*.pre-v0.13-snapshot/` and `*.duplicate-cleanup/` directories are kept untouched as a safety net — safe to delete after you've confirmed the migration succeeded. The migration is idempotent (marker file blocks re-runs), best-effort (logs to stderr and falls back to a candidate path on failure rather than crashing the workbench), and collision-safe (pre-existing backup names get a Unix timestamp appended).
  77. #### Forcing a custom location
  78. Set `FREECAD_AI_CONFIG_DIR` in your environment to bypass the FreeCAD-based resolution entirely. Useful for:
  79. - Running multiple isolated profiles for different LLM accounts
  80. - Pointing at a synced location (Syncthing, Dropbox)
  81. - Pinning a fixed path while testing v0.13.0+ migration
  82. ```bash
  83. FREECAD_AI_CONFIG_DIR=~/work/freecad-ai-profile-1 freecad
  84. ```
  85. ### Secure API key storage
  86. API keys can be entered as plain text, but for shared machines, repos, or backups, the key field accepts two prefixes that keep the secret out of the config file. Both work on Linux, macOS, and Windows.
  87. > **Note on platform coverage:** the workbench is developed and tested on Linux. The macOS and Windows examples below follow the documented behavior of the underlying tools (`security`, `CredentialManager`, `expanduser`/`expandvars`, `subprocess.run(shell=True)`) but have **not** been verified on those OSes by the maintainer. If you run into a platform-specific issue, please [open an issue](https://github.com/ghbalf/freecad-ai/issues) — patches and corrections welcome.
  88. **`file:` — read key from a file** (re-read on every API call). Path supports `~` and OS env vars (`$HOME`, `%APPDATA%`).
  89. | OS | Example |
  90. |---|---|
  91. | Linux/macOS | `file:~/.config/anthropic-key` |
  92. | Windows | `file:%APPDATA%\freecad-ai\anthropic-key.txt` |
  93. Lock the file down with filesystem permissions (`chmod 600` on Unix, file-properties → security on Windows).
  94. **`cmd:` — run a command, use its stdout as the key.** Lets you pull from the OS's native secret store via that store's CLI:
  95. | OS | Native store | Example |
  96. |---|---|---|
  97. | Linux | libsecret (GNOME Keyring, KWallet) via `libsecret-tools` | `cmd:secret-tool lookup service freecad-ai account anthropic` |
  98. | macOS | Keychain | `cmd:security find-generic-password -a anthropic -s freecad-ai -w` |
  99. | Windows | Credential Manager (needs the [`CredentialManager` PowerShell module][CM]) | `cmd:powershell -Command "(Get-StoredCredential -Target 'freecad-ai-anthropic').GetNetworkCredential().Password"` |
  100. | Any | GPG | `cmd:gpg --decrypt ~/keys/anthropic.gpg` |
  101. To populate the stores once:
  102. - **Linux:** `secret-tool store --label="freecad-ai anthropic" service freecad-ai account anthropic`
  103. - **macOS:** `security add-generic-password -a anthropic -s freecad-ai -w 'sk-ant-…'`
  104. - **Windows (PowerShell):** `New-StoredCredential -Target 'freecad-ai-anthropic' -UserName anthropic -Password (Read-Host -AsSecureString)`
  105. [CM]: https://www.powershellgallery.com/packages/CredentialManager
  106. ### Supported Providers
  107. | Provider | API Key Required | Notes |
  108. |----------|-----------------|-------|
  109. | Ollama | No | Local models, default `http://localhost:11434` |
  110. | Anthropic | Yes | Claude models via native API |
  111. | OpenAI | Yes | GPT models |
  112. | Gemini | Yes | Google AI via OpenAI-compatible endpoint |
  113. | OpenRouter | Yes | Multi-provider gateway |
  114. | Requesty | Yes | Multi-provider gateway, EU endpoint `https://router.eu.requesty.ai/v1` |
  115. | Cloudflare Workers AI | Yes (Workers AI token) | Per-account endpoint — replace `{ACCOUNT_ID}` in the Base URL with your Cloudflare account ID before use |
  116. | Moonshot | Yes | Kimi models (default params pre-configured) |
  117. | DeepSeek | Yes | DeepSeek-V3 |
  118. | Qwen | Yes | Alibaba DashScope (international) |
  119. | Groq | Yes | Ultra-fast inference |
  120. | Mistral | Yes | Mistral models |
  121. | Together | Yes | Open model hosting |
  122. | Fireworks | Yes | Fast inference |
  123. | xAI | Yes | Grok models |
  124. | Cohere | Yes | Command models |
  125. | SambaNova | Yes | Fast inference |
  126. | MiniMax | Yes | MiniMax models |
  127. | Llama | Yes | Meta's official Llama API |
  128. | GitHub | Yes (PAT) | GitHub Models marketplace |
  129. | HuggingFace | Yes (`hf_...`) | Serverless inference API |
  130. | Zhipu | Yes | GLM models (z.ai international) |
  131. | Perplexity | Yes | Orchestrator API (OpenAI-compatible) |
  132. | DemonRoute | Yes | Open-weight model gateway (OpenAI-compatible), prepaid. Prompts are forwarded to third-party upstream hosts (mainly Featherless, per the operator) with their own retention policies; see [DemonRoute's privacy page](https://demonroute.com/privacy) |
  133. | Runcrate | Yes (`rc_live_...`) | Open-weight models (DeepSeek, GLM, Qwen, Kimi and others) via an OpenAI-compatible API, prepaid. Keys from https://www.runcrate.ai/dashboard/api-keys, model ids at https://www.runcrate.ai/inference/pricing. Prompts are processed by third-party model providers under their own terms; see [Runcrate's privacy policy](https://www.runcrate.ai/privacy) |
  134. | Custom | Varies | Any OpenAI-compatible endpoint |
  135. ### Connection profiles
  136. Connection settings — provider, base URL, API key, model, sampling parameters —
  137. are stored as named **profiles**, not a single flat set. You can define as many
  138. as you like, including several for the same vendor: `ollama-local` and
  139. `ollama-remote` can coexist with different URLs and keys, and switching between
  140. profiles in the Settings dialog never touches the ones you're not looking at.
  141. A profile's API key can be left blank to fall back to a vendor-wide default
  142. key, so one Anthropic key can serve several Anthropic profiles. Those defaults
  143. live in the `provider_keys` object in `config.json` and are set by hand — the
  144. Settings dialog edits a profile's own key, and clearing that field clears it.
  145. A profile can also carry its own limits: a `max_tokens` row in its Model
  146. Parameters table sets its output cap, and **Compact above** sets how large a
  147. conversation on it may grow before older messages are summarised. Both fall
  148. back to the Behavior page's values when left unset.
  149. **Compact above** defaults to 64,000 tokens on new installs (existing
  150. configurations keep their saved value). About 16,500 of those tokens are fixed
  151. overhead sent with every request: roughly 13,300 for the tool schemas and 3,150
  152. for the system prompt. A threshold much below ~40,000 therefore compacts after
  153. only a few turns. Keep it below your model's real context window. For Ollama,
  154. that window is set on the server, not in this workbench: start Ollama with
  155. `OLLAMA_CONTEXT_LENGTH=65536` (or bake `PARAMETER num_ctx 65536` into a
  156. Modelfile). Otherwise Ollama silently truncates the prompt at its own, much
  157. smaller default.
  158. Beyond the active profile chat uses, four utility jobs each pick their own
  159. profile from a dropdown in Settings: context compaction, skill evaluation,
  160. tool optimisation, and tool reranking. Left on **inherit**, a utility runs on
  161. whatever profile is currently active; pointed at a specific profile, it always
  162. uses that one — for example, running chat on a capable cloud model while
  163. compaction and reranking run on a cheap or local one.
  164. Existing configurations migrate to this shape automatically the first time
  165. you load them — there is nothing to do by hand.
  166. ### Model Parameters
  167. The **Model Parameters** table in Settings lets you set arbitrary sampling parameters (temperature, top_p, top_k, etc.) that are sent with each API request. Parameters belong to the profile you are editing, so two profiles never share them — even when they name the same model — and removing a row removes the parameter. Removing *every* row is different: a profile with no parameters of its own falls back to the provider's recommended defaults, which is what you will see the next time you open Settings. The per-model defaults written by earlier versions are still in `config.json` but are no longer read; on upgrade the entry for your current model is copied into your profile once.
  168. Click **Load Defaults** to reset to the provider's recommended values. For most providers the only default is `temperature: 0.3`. Moonshot ships with pre-configured values required by Kimi-K2.5.
  169. For OpenAI Chat Completions, o-series and GPT-5+ models automatically use
  170. `max_completion_tokens` and omit `temperature`. Older GPT models retain
  171. `max_tokens` and their configured temperature. This applies to streaming,
  172. non-streaming, and tool-calling requests.
  173. Other OpenAI-compatible providers retain their existing parameters. For a
  174. custom endpoint or deployment alias that requires the newer token parameter,
  175. add a `max_completion_tokens` row to the profile's **Model Parameters** table.
  176. That explicit value takes precedence, and `max_tokens` is omitted so the request
  177. never contains both token-limit parameters.
  178. #### Strip thinking from history
  179. The **"Strip thinking from conversation history"** checkbox in Settings controls whether thinking/reasoning content is removed from previous turns before sending to the API. Some models (e.g. Gemma 3/4) reject thinking content in multi-turn conversations, while others (e.g. Kimi-K2.5) require it.
  180. The checkbox is tristate: partially checked = auto-detect by model name (Gemma models strip automatically), checked = always strip, unchecked = never strip.
  181. ## Usage
  182. ### Plan Mode
  183. Type a request like *"Create a box 50mm x 30mm x 20mm"*. The AI generates Python code and displays it for review. Click **Execute** to run it, **Check** to run the sandbox validation (catches FreeCAD C++-console errors and invalid shapes without touching the live document), or **Fix with AI** to loop the code plus a prompt back to the LLM for correction. **Copy** copies to clipboard.
  184. ### Act Mode
  185. Same workflow, but with two execution paths:
  186. - **Tool calling** (default): The LLM invokes structured tools like `create_primitive`, `boolean_operation`, `fillet_edges`, etc. These are pre-validated operations wrapped in undo transactions — safer and more reliable than raw code.
  187. - **Code generation** (fallback): When tools are disabled or the LLM generates code blocks instead, code executes with the same safety layers as before (static validation, subprocess sandbox, undo transactions).
  188. Tool calling is enabled by default. Disable it by setting `enable_tools: false` in `<FreeCADAI dir>/config.json`.
  189. ### Available Tools
  190. | Tool | Description |
  191. |------|-------------|
  192. | `create_primitive` | Box, Cylinder, Sphere, Cone, Torus |
  193. | `create_body` | Create a PartDesign Body for parametric modeling |
  194. | `create_sketch` | Sketch with lines, circles, arcs, rectangles + constraints (supports plane offset) |
  195. | `pad_sketch` | Extrude a sketch |
  196. | `pocket_sketch` | Cut a pocket from a sketch (auto-detects correct direction) |
  197. | `revolve_sketch` | Revolve a sketch around an axis (vase, wheel, bottle) |
  198. | `loft_sketches` | Loft between sketches for tapered/organic shapes |
  199. | `sweep_sketch` | Sweep a profile along a spine path (pipe, tube) |
  200. | `boolean_operation` | Fuse, Cut, or Common between two objects |
  201. | `transform_object` | Move and/or rotate an object |
  202. | `fillet_edges` | Round edges |
  203. | `chamfer_edges` | Chamfer edges |
  204. | `shell_object` | Hollow out a solid (PartDesign::Thickness) |
  205. | `mirror_feature` | Mirror a PartDesign feature across a plane |
  206. | `create_wedge` | Create a wedge/ramp shape |
  207. | `scale_object` | Scale an object uniformly or per-axis |
  208. | `section_object` | Cross-section through a plane or another object |
  209. | `linear_pattern` | Repeat a feature in a line |
  210. | `polar_pattern` | Repeat a feature in a circular pattern |
  211. | `multi_transform` | Chain linear pattern + polar pattern + mirror in one feature |
  212. | `create_inner_ridge` | Add a snap-fit ridge inside a rectangular hollow |
  213. | `create_snap_tabs` | Add snap tabs on a lid lip (pairs with ridge) |
  214. | `create_enclosure_lid` | Generate a snap-fit enclosure lid with correct dimensions |
  215. | `measure` | Volume, area, bounding box, distance, edge listing |
  216. | `describe_model` | Comprehensive geometry summary: dimensions, wall thickness, hollow/solid detection |
  217. | `list_faces` | List all faces with names, labels, normals, areas (optional filter) |
  218. | `list_edges` | List all edges with names, labels, lengths (optional filter) |
  219. | `list_documents` | List all open documents with object counts and active indicator |
  220. | `switch_document` | Switch the active FreeCAD document by name or label |
  221. | `get_document_state` | Inspect current objects and properties |
  222. | `create_variable_set` | Create a VarSet with named variables for parametric modeling |
  223. | `create_spreadsheet` | Create a Spreadsheet with named variables for parametric modeling |
  224. | `set_expression` | Bind object properties to expressions (parametric relationships) |
  225. | `modify_property` | Change any object property (supports relative: +10%, *1.5) |
  226. | `read_variable_set` | Read a VarSet's variables with types, units and expressions |
  227. | `edit_variable_set` | Change, add or remove VarSet variables (unit-aware) |
  228. | `read_spreadsheet` | Read spreadsheet cells: alias, contents, computed value |
  229. | `edit_spreadsheet` | Change, add or remove spreadsheet cells by alias or address |
  230. | `delete_object` | Delete an object (a Body with its features); refuses while other objects still use it |
  231. | `export_model` | Export to STL, STEP, or IGES |
  232. | `execute_code` | Fallback: run arbitrary Python |
  233. | `undo` | Undo last N operations, or undo until a named transaction |
  234. | `redo` | Redo previously undone operations |
  235. | `undo_history` | Show the undo/redo stack with named transactions |
  236. | `capture_viewport` | Save a screenshot of the 3D viewport |
  237. | `set_view` | Set camera orientation (front, top, isometric, etc.) |
  238. | `zoom_object` | Zoom the viewport to a specific object |
  239. | `use_skill` | Load a skill's instructions for complex tasks (enclosure, gear, etc.) |
  240. | `create_assembly` | Create an Assembly with grounded base part |
  241. | `add_assembly_joint` | Joint two parts (Fixed, Revolute, Cylindrical, Slider, Ball) |
  242. | `add_part_to_assembly` | Add a part to an existing assembly |
  243. | `select_geometry` | Interactive viewport picking for edges, faces, vertices |
  244. ### Connecting external MCP clients (Claude Code, Claude Desktop, …)
  245. These same tools can be exposed as a standalone MCP server, so any MCP-capable client can drive FreeCAD — not just this addon's own chat panel. Driving it from a client you already subscribe to means no provider API key and no per-token cost on top of it.
  246. Three ways to start it, differing in who owns the FreeCAD process:
  247. - **The toolbar** — no paths, no command line. In the **FreeCAD AI** workbench, click **MCP Server** on the toolbar (or the matching entry in the FreeCAD AI menu) to start the server inside the running FreeCAD; click again to stop it. The URL is printed to the Report view, and the address lives in **AI Settings → MCP Servers**. The button reflects the real server state, so a server started either of the ways below shows as running and can be stopped from it too.
  248. ```bash
  249. claude mcp add --transport http freecad http://127.0.0.1:3000/mcp
  250. ```
  251. - **`mcp_server_http.py`** — the same HTTP server, started from the command line. FreeCAD is already running with your document open and the client attaches to it, so you watch the model change live in the viewport.
  252. ```bash
  253. /path/to/FreeCAD.AppImage /path/to/freecad-ai/mcp_server_http.py
  254. claude mcp add --transport http freecad http://127.0.0.1:3000/mcp
  255. ```
  256. - **`mcp_server_entry.py`** — STDIO, headless. The client spawns FreeCAD, which lives and dies with the session.
  257. ```bash
  258. claude mcp add freecad -- bash -c \
  259. 'exec 3>&1 1>&2 && /path/to/FreeCAD.AppImage -c /path/to/freecad-ai/mcp_server_entry.py'
  260. ```
  261. > **The MCP server is unauthenticated by default.** Anything that can reach the address it is bound to can run FreeCAD tools, including arbitrary Python. On the `127.0.0.1` default that means any process on your machine. Set a bearer token in the **AI Settings** MCP Servers section (or `MCP_AUTH_TOKEN`) to require `Authorization: Bearer <token>` on every request; clients pass it as a header (e.g. `claude mcp add --transport http freecad http://127.0.0.1:3000/mcp -H "Authorization: Bearer <token>"`).
  262. Note that Claude Code loads MCP tools **at session start** — a server added mid-session won't appear until the next launch.
  263. Full setup, including Flatpak paths, `MCP_HOST`/`MCP_PORT`, and why the STDIO mode needs the `bash -c` wrapper: [MCP Integration](https://github.com/ghbalf/freecad-ai/wiki/MCP-Integration#mcp-server-exposing-freecad-tools) in the wiki.
  264. ### Skills
  265. Skills are reusable instruction sets stored in `<FreeCADAI dir>/skills/`. Invoke them by typing `/command` in the chat.
  266. **Built-in skills:**
  267. | Command | Description |
  268. |---------|-------------|
  269. | `/enclosure` | Parametric electronics enclosure with base, lid, screw posts |
  270. | `/thread-insert` | Heat-set thread insert holes (M2–M5) with correct dimensions |
  271. | `/gear` | Involute spur gear from module and tooth count |
  272. | `/fastener-hole` | Clearance, counterbore, or countersink holes (ISO dimensions) |
  273. | `/lattice` | Grid, honeycomb, or diagonal infill patterns |
  274. | `/skill-creator` | Create new skills interactively from the chat |
  275. **Creating custom skills:**
  276. You can create skills manually (see below) or use `/skill-creator` in the chat to have the AI walk you through it.
  277. ```
  278. <FreeCADAI dir>/skills/
  279. my-skill/
  280. SKILL.md # Instructions injected into the LLM prompt
  281. handler.py # Optional: Python handler with execute(args) function
  282. ```
  283. The `SKILL.md` file contains instructions for the LLM. When invoked, these are injected into the prompt along with any arguments you provide. For example:
  284. ```
  285. /enclosure 100x60x40mm, 2mm walls, snap-fit lid
  286. ```
  287. If a `handler.py` exists with an `execute(args)` function, it runs directly instead of prompting the LLM.
  288. ### User Extension Tools
  289. You can register your own Python functions as tools that the LLM can call. Place `.py` or `.FCMacro` files in `<FreeCADAI dir>/tools/` (see [Configuration paths](#configuration-paths) for what `<FreeCADAI dir>` resolves to on your setup). Functions with type hints are automatically discovered and registered:
  290. ```python
  291. import math
  292. def bolt_circle(diameter: float, count: int = 8, bolt_size: float = 6.5) -> str:
  293. """Create a bolt hole circle pattern on the XY plane."""
  294. import Part
  295. import FreeCAD as App
  296. # ... create geometry ...
  297. return f"Created {count} bolt holes on {diameter}mm PCD"
  298. ```
  299. **Requirements:**
  300. - Public functions (no `_` prefix) with type-hinted parameters
  301. - Supported types: `float`, `int`, `str`, `bool`
  302. - Return a `str` (success message) or `dict` with `output`/`data` keys
  303. - Docstring first line becomes the tool description
  304. User tools are prefixed with `user_` and available to the LLM, skills, and MCP server. Manage them in Settings → User Tools (Add, Remove, Reload). Enable "Scan FreeCAD macro directory" to also pick up compatible macros from FreeCAD's macro folder.
  305. ### Thinking Mode
  306. Enable LLM reasoning in Settings (gear icon). Three levels:
  307. | Level | Description |
  308. |-------|-------------|
  309. | Off | Standard responses (default) |
  310. | On | LLM shows reasoning before responding |
  311. | Extended | Longer reasoning budget for complex tasks |
  312. Thinking is displayed dimmed in the chat. Provider support varies — Anthropic Claude, OpenAI o-series, and some Ollama models (qwen3) support thinking. Models that don't support it will silently ignore the setting.
  313. ### Session Resume
  314. Conversations are auto-saved after each LLM response. Click the **Load** button in the chat footer to resume a previous session from the last 20 saved conversations.
  315. ### File Attachments
  316. Attach files to chat messages via the **Attach** button, drag-and-drop, or paste:
  317. | File type | Handling |
  318. |-----------|----------|
  319. | Images (PNG, JPG, etc.) | Sent as vision blocks (requires vision-capable model or MCP fallback) |
  320. | Text files (TXT, MD, CSV, PY, JSON, etc.) | Read as text and included in the message |
  321. | Binary files (PDF, DOCX, XLSX, etc.) | Converted via `file_attach` hook or MCP server |
  322. **Why no built-in PDF/DOCX support?** FreeCAD AI has a strict zero-external-dependencies policy — it uses only Python stdlib and runs inside FreeCAD's bundled Python. PDF/DOCX parsing requires external C libraries that cannot be bundled portably. Instead, two extensibility paths are provided:
  323. 1. **Hooks** — lightweight, user-installed shell commands. Create a `file_attach` hook that calls CLI tools like `pdftotext` or `pandoc`. See `docs/hooks/file-attach-example/` for a ready-to-use example. Text-only output.
  324. 2. **MCP servers** — for rich conversion with images and structure preservation. Install a server like [markdownify-mcp](https://github.com/zcaceres/markdownify-mcp) in Settings → MCP Servers.
  325. To install the example PDF hook:
  326. ```bash
  327. # Replace <FreeCADAI dir> with your actual path — see "Configuration paths" above.
  328. # On FreeCAD 1.1+ Linux this is ~/.config/FreeCAD/v1-1/FreeCADAI/.
  329. cp -r docs/hooks/file-attach-example/ "<FreeCADAI dir>/hooks/file-attach/"
  330. # Requires: sudo apt install poppler-utils (provides pdftotext)
  331. ```
  332. Binary files are detected by magic bytes (PDF, ZIP/Office, PNG, JPEG, ELF, etc.) and null-byte content scanning.
  333. ### Referencing FreeCAD Objects
  334. Attach your current selection to the next message via the **Reference** button (above Attach):
  335. 1. Select geometry in the 3D view or model tree (Ctrl+click for several items).
  336. 2. Click **Reference** — an `@Name` token drops into the input box and a green chip appears in the attachment strip.
  337. 3. Type your question around the tokens (e.g. `why is @Pad.Face3 not parallel to @Pad.Face1?`) and send.
  338. The LLM receives a short snapshot of each reference — object type, placement, and bounding box, or for faces/edges/vertices their classification, area/length, center, and normal — so it knows exactly which geometry an `@token` means without re-inspecting the model.
  339. | Detail | Behaviour |
  340. |--------|-----------|
  341. | Whole objects | Click the object in the tree → `@Pad` |
  342. | Sub-elements | One chip per selected face/edge/vertex → `@Pad.Face3`, `@Pad.Edge7`, `@Pad.Vertex2` |
  343. | Snapshot timing | Descriptions are captured when you click the button — re-click after moving or editing geometry to refresh |
  344. | Renamed objects | Tokens use the immutable internal name, so `@Pad` stays valid even after the object's label changes; the label appears in the description text |
  345. | Removing | The chip's **x** removes the context block; delete the `@token` from the input yourself |
  346. | Auto-clear | The strip clears after sending, like file attachments |
  347. ### AGENTS.md
  348. Place an `AGENTS.md` or `FREECAD_AI.md` file next to your `.FCStd` file to provide project-specific instructions:
  349. ```markdown
  350. # AGENTS.md
  351. This project uses metric units (mm).
  352. All parts should have 1mm fillets on external edges.
  353. Use PartDesign workflow (Body -> Sketch -> Pad), not Part primitives.
  354. ```
  355. **Search order:** document directory → parent directories (up to 3 levels) → `<FreeCADAI dir>/AGENTS.md`
  356. **Include directives** — split instructions across files:
  357. ```markdown
  358. <!-- include: materials.md -->
  359. <!-- include: conventions.md -->
  360. ```
  361. **Variable substitution** — use live document values:
  362. ```markdown
  363. Document: {{document_name}}
  364. Objects: {{object_count}}
  365. Active body: {{active_body}}
  366. ```
  367. ## Running macros & Dangerous mode
  368. The `run_macro` tool lets the assistant run an existing FreeCAD macro and read
  369. its console output directly — useful for AI-written test harnesses. By default
  370. it only runs a macro by **name** from FreeCAD's macro directory.
  371. ### ⚠️ Dangerous mode — read this
  372. Dangerous mode is an opt-in escape hatch that **removes the safety checks**
  373. FreeCAD AI normally applies to code it runs. Enable it from the chat panel
  374. (a confirmation dialog explains the risks; it resets to OFF every time FreeCAD
  375. restarts, and a red banner shows while it is active).
  376. While Dangerous mode is active:
  377. - **Arbitrary code/commands:** AI-run code can call shell commands, delete
  378. files, and do anything your user account is allowed to do.
  379. - **No timeout:** a macro containing an infinite loop will **freeze FreeCAD's
  380. main window with no way to recover — any unsaved work is lost.**
  381. - **No sandbox pre-check:** broken or destructive code runs straight against
  382. your live document.
  383. - **Endless loops:** if you also set the tool-loop count to `0` (endless), the
  384. AI can keep acting until you press **Stop**. There is no other limit, and it
  385. can consume a large number of tokens.
  386. **You are solely responsible for anything you run in this mode.** It is provided
  387. as a power-user convenience and is not tested against malicious or destructive
  388. input. Document integrity (undo rollback) is the only safeguard that remains on.
  389. To make Dangerous mode persist across restarts (not recommended), set
  390. `"dangerous_skip_safety": true` in your `config.json` by hand. The GUI will
  391. never write this for you.
  392. > Note: behavior described here is verified on Linux; the macro-directory
  393. > resolution uses FreeCAD's cross-platform API but is untested on macOS/Windows.
  394. ## Translations
  395. The UI supports internationalization via Qt's `.ts`/`.qm` translation system. Currently available:
  396. | Language | Status |
  397. |----------|--------|
  398. | English | Default (built-in) |
  399. | German | Complete |
  400. To add a new language, copy `translations/freecad_ai_de.ts` to `freecad_ai_<lang>.ts`, translate the strings (or use [Qt Linguist](https://doc.qt.io/qt-5/qtlinguist-index.html)), and compile with `lrelease`.
  401. To re-extract strings after code changes:
  402. ```bash
  403. cd translations && bash update_translations.sh
  404. ```
  405. ## Project Structure
  406. ```
  407. freecad-ai/
  408. ├── Init.py # Non-GUI init
  409. ├── InitGui.py # Workbench registration + commands
  410. ├── package.xml # FreeCAD addon metadata
  411. ├── freecad_ai/
  412. │ ├── config.py # Settings (provider, API key, mode, tools, thinking)
  413. │ ├── i18n.py # Internationalization helpers
  414. │ ├── paths.py # Path utilities
  415. │ ├── llm/
  416. │ │ ├── client.py # HTTP client with SSE streaming + tool calling
  417. │ │ └── providers.py # Provider registry
  418. │ ├── tools/
  419. │ │ ├── registry.py # Tool abstractions + registry
  420. │ │ ├── freecad_tools.py # 39 FreeCAD tool handlers
  421. │ │ └── setup.py # Default registry factory
  422. │ ├── ui/
  423. │ │ ├── compat.py # PySide2/PySide6 shim
  424. │ │ ├── chat_widget.py # Chat dock + agentic tool loop
  425. │ │ ├── message_view.py # Message + tool call rendering
  426. │ │ ├── code_review_dialog.py
  427. │ │ └── settings_dialog.py
  428. │ ├── core/
  429. │ │ ├── active_document.py # GUI-aligned active document resolution
  430. │ │ ├── executor.py # Code execution with safety layers
  431. │ │ ├── context.py # Document state inspector
  432. │ │ ├── system_prompt.py # System prompt builder
  433. │ │ └── conversation.py # Conversation history + compacting + save/load
  434. │ ├── hooks/
  435. │ │ ├── __init__.py # Hooks package
  436. │ │ └── registry.py # Hook lifecycle event dispatch
  437. │ └── extensions/
  438. │ ├── agents_md.py # AGENTS.md loader (multi-location, includes, vars)
  439. │ ├── skills.py # Skills registry + execution
  440. │ └── user_tools.py # User extension tools (discover, validate, register)
  441. ├── translations/
  442. │ ├── freecad_ai_de.ts # German translation source
  443. │ └── update_translations.sh # Re-extract strings with pylupdate5
  444. ├── skills/ # Built-in skill definitions
  445. │ ├── enclosure/SKILL.md
  446. │ ├── gear/SKILL.md
  447. │ ├── fastener-hole/SKILL.md
  448. │ ├── thread-insert/SKILL.md
  449. │ ├── lattice/SKILL.md
  450. │ └── skill-creator/SKILL.md
  451. ├── hooks/ # Built-in hook examples
  452. │ └── log-tool-calls/
  453. └── resources/
  454. └── icons/
  455. └── freecad_ai.svg
  456. ```
  457. ## Contributing
  458. Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a dev environment, submit pull requests, and create new skills or providers.
  459. ## License
  460. - **Code:** LGPL-2.1 — see [LICENSE-CODE](LICENSE-CODE)
  461. - **Icons:** CC0-1.0 (public domain) — see [LICENSE-ICON](LICENSE-ICON)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.