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.
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
Markdown
[](/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
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.
- # FreeCAD AI
- > **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.
- An AI-powered assistant workbench for FreeCAD that generates and executes Python code to create 3D models from natural language descriptions.
- ## Features
- - **Chat interface** — dock widget with streaming LLM responses
- - **Plan / Act modes** — review code before execution (Plan) or auto-execute (Act)
- - **Tool calling** — 50 structured FreeCAD operations (Act mode) for safer, more reliable modeling
- - **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
- - **Skills** — reusable instruction sets the model invokes autonomously or via `/command` (enclosure, gear, fastener holes, sketch-from-image, etc.)
- - **Skill optimizer** — automatically improve skill instructions via iterative test-evaluate-modify loop (`/optimize-skill`)
- - **Hooks** — user-defined Python hooks for lifecycle events (block tools, modify input, log activity, convert file attachments)
- - **User extension tools** — register your own Python functions as LLM-callable tools (`.py` or `.FCMacro`)
- - **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
- - **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
- - **Image support** — viewport screenshots and images sent as vision blocks; auto-detected binary format rejection (PDF, ZIP, Office docs)
- - **Thinking mode** — enable LLM reasoning for complex multi-step tasks (Off / On / Extended)
- - **Context compacting** — automatically summarizes older messages when approaching context limits
- - **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
- - **Session resume** — save and load chat sessions to continue work later
- - **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
- - **Context-aware** — automatically includes document state (objects, properties, selection) in prompts
- - **Error self-correction** — failed code is sent back to the LLM for automatic retry (up to 3 attempts)
- - **AGENTS.md support** — project-level instructions with include directives and variable substitution
- - **Dark mode** — chat widget automatically adapts to FreeCAD's light/dark theme (theme changes require FreeCAD restart)
- - **Persistent dock layout** — the chat dock remembers its position, tab siblings (e.g. tabified with the Tasks panel), and floating geometry across FreeCAD sessions
- - **Zero external dependencies** — uses only Python stdlib (`urllib`, `json`, `threading`, `ssl`)
- ## Requirements
- - FreeCAD 1.0+ (tested with 1.0.2 and 1.1.0)
- - An LLM provider (local Ollama, or an API key for a cloud provider)
- ## Installation
- Clone or copy this repository into FreeCAD's Mod directory:
- ### Linux
- ```bash
- ln -s /path/to/freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai
- ```
- ### macOS
- ```bash
- ln -s /path/to/freecad-ai ~/Library/Application\ Support/FreeCAD/Mod/freecad-ai
- ```
- ### Windows
- ```powershell
- # 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.
- ## Configuration
- There are two ways to configure FreeCAD AI:
- - **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.
- - **Workbench Settings dialog** (gear icon in the chat panel) — the same four pages in one window.
- Both UIs edit the same file, `<FreeCADAI dir>/config.json`; FreeCAD's own parameter store (`user.cfg`) holds no FreeCAD AI settings.
- ### Configuration paths
- `<FreeCADAI dir>` is resolved on workbench load. The order is:
- 1. **`$FREECAD_AI_CONFIG_DIR`** environment variable, if set. Used as-is.
- 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`).
- 3. **`~/.config/FreeCAD/FreeCADAI/`** (legacy) when FreeCAD is not importable — pytest, console scripts, plain Python REPL.
- > **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.
- #### One-shot migration on first launch of v0.13.0-alpha+
- 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:
- | # | Action |
- |---|---|
- | 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. |
- | 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). |
- | 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. |
- | 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. |
- | 5 | Drop a marker file `<target>/.freecad_ai_active_marker` so subsequent imports skip migration. |
- 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.
- 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).
- #### Forcing a custom location
- Set `FREECAD_AI_CONFIG_DIR` in your environment to bypass the FreeCAD-based resolution entirely. Useful for:
- - Running multiple isolated profiles for different LLM accounts
- - Pointing at a synced location (Syncthing, Dropbox)
- - Pinning a fixed path while testing v0.13.0+ migration
- ```bash
- FREECAD_AI_CONFIG_DIR=~/work/freecad-ai-profile-1 freecad
- ```
- ### Secure API key storage
- 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.
- > **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.
- **`file:` — read key from a file** (re-read on every API call). Path supports `~` and OS env vars (`$HOME`, `%APPDATA%`).
- | OS | Example |
- |---|---|
- | Linux/macOS | `file:~/.config/anthropic-key` |
- | Windows | `file:%APPDATA%\freecad-ai\anthropic-key.txt` |
- Lock the file down with filesystem permissions (`chmod 600` on Unix, file-properties → security on Windows).
- **`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:
- | OS | Native store | Example |
- |---|---|---|
- | Linux | libsecret (GNOME Keyring, KWallet) via `libsecret-tools` | `cmd:secret-tool lookup service freecad-ai account anthropic` |
- | macOS | Keychain | `cmd:security find-generic-password -a anthropic -s freecad-ai -w` |
- | Windows | Credential Manager (needs the [`CredentialManager` PowerShell module][CM]) | `cmd:powershell -Command "(Get-StoredCredential -Target 'freecad-ai-anthropic').GetNetworkCredential().Password"` |
- | Any | GPG | `cmd:gpg --decrypt ~/keys/anthropic.gpg` |
- To populate the stores once:
- - **Linux:** `secret-tool store --label="freecad-ai anthropic" service freecad-ai account anthropic`
- - **macOS:** `security add-generic-password -a anthropic -s freecad-ai -w 'sk-ant-…'`
- - **Windows (PowerShell):** `New-StoredCredential -Target 'freecad-ai-anthropic' -UserName anthropic -Password (Read-Host -AsSecureString)`
- [CM]: https://www.powershellgallery.com/packages/CredentialManager
- ### Supported Providers
- | Provider | API Key Required | 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 |
- | Requesty | Yes | Multi-provider gateway, EU endpoint `https://router.eu.requesty.ai/v1` |
- | Cloudflare Workers AI | Yes (Workers AI token) | Per-account endpoint — replace `{ACCOUNT_ID}` in the Base URL with your Cloudflare account ID before use |
- | Moonshot | Yes | Kimi models (default params pre-configured) |
- | 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) |
- | Perplexity | Yes | Orchestrator API (OpenAI-compatible) |
- | 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) |
- | 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) |
- | Custom | Varies | Any OpenAI-compatible endpoint |
- ### Connection profiles
- Connection settings — provider, base URL, API key, model, sampling parameters —
- are stored as named **profiles**, not a single flat set. You can define as many
- as you like, including several for the same vendor: `ollama-local` and
- `ollama-remote` can coexist with different URLs and keys, and switching between
- profiles in the Settings dialog never touches the ones you're not looking at.
- A profile's API key can be left blank to fall back to a vendor-wide default
- key, so one Anthropic key can serve several Anthropic profiles. Those defaults
- live in the `provider_keys` object in `config.json` and are set by hand — the
- Settings dialog edits a profile's own key, and clearing that field clears it.
- A profile can also carry its own limits: a `max_tokens` row in its Model
- Parameters table sets its output cap, and **Compact above** sets how large a
- conversation on it may grow before older messages are summarised. Both fall
- back to the Behavior page's values when left unset.
- **Compact above** defaults to 64,000 tokens on new installs (existing
- configurations keep their saved value). About 16,500 of those tokens are fixed
- overhead sent with every request: roughly 13,300 for the tool schemas and 3,150
- for the system prompt. A threshold much below ~40,000 therefore compacts after
- only a few turns. Keep it below your model's real context window. For Ollama,
- that window is set on the server, not in this workbench: start Ollama with
- `OLLAMA_CONTEXT_LENGTH=65536` (or bake `PARAMETER num_ctx 65536` into a
- Modelfile). Otherwise Ollama silently truncates the prompt at its own, much
- smaller default.
- Beyond the active profile chat uses, four utility jobs each pick their own
- profile from a dropdown in Settings: context compaction, skill evaluation,
- tool optimisation, and tool reranking. Left on **inherit**, a utility runs on
- whatever profile is currently active; pointed at a specific profile, it always
- uses that one — for example, running chat on a capable cloud model while
- compaction and reranking run on a cheap or local one.
- Existing configurations migrate to this shape automatically the first time
- you load them — there is nothing to do by hand.
- ### Model Parameters
- 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.
- 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.
- For OpenAI Chat Completions, o-series and GPT-5+ models automatically use
- `max_completion_tokens` and omit `temperature`. Older GPT models retain
- `max_tokens` and their configured temperature. This applies to streaming,
- non-streaming, and tool-calling requests.
- Other OpenAI-compatible providers retain their existing parameters. For a
- custom endpoint or deployment alias that requires the newer token parameter,
- add a `max_completion_tokens` row to the profile's **Model Parameters** table.
- That explicit value takes precedence, and `max_tokens` is omitted so the request
- never contains both token-limit parameters.
- #### Strip thinking from history
- 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.
- The checkbox is tristate: partially checked = auto-detect by model name (Gemma models strip automatically), checked = always strip, unchecked = never strip.
- ## Usage
- ### Plan Mode
- 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.
- ### Act Mode
- Same workflow, but with two execution paths:
- - **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.
- - **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).
- Tool calling is enabled by default. Disable it by setting `enable_tools: false` in `<FreeCADAI dir>/config.json`.
- ### Available Tools
- | Tool | Description |
- |------|-------------|
- | `create_primitive` | Box, Cylinder, Sphere, Cone, Torus |
- | `create_body` | Create a PartDesign Body for parametric modeling |
- | `create_sketch` | Sketch with lines, circles, arcs, rectangles + constraints (supports plane offset) |
- | `pad_sketch` | Extrude a sketch |
- | `pocket_sketch` | Cut a pocket from a sketch (auto-detects correct direction) |
- | `revolve_sketch` | Revolve a sketch around an axis (vase, wheel, bottle) |
- | `loft_sketches` | Loft between sketches for tapered/organic shapes |
- | `sweep_sketch` | Sweep a profile along a spine path (pipe, tube) |
- | `boolean_operation` | Fuse, Cut, or Common between two objects |
- | `transform_object` | Move and/or rotate an object |
- | `fillet_edges` | Round edges |
- | `chamfer_edges` | Chamfer edges |
- | `shell_object` | Hollow out a solid (PartDesign::Thickness) |
- | `mirror_feature` | Mirror a PartDesign feature across a plane |
- | `create_wedge` | Create a wedge/ramp shape |
- | `scale_object` | Scale an object uniformly or per-axis |
- | `section_object` | Cross-section through a plane or another object |
- | `linear_pattern` | Repeat a feature in a line |
- | `polar_pattern` | Repeat a feature in a circular pattern |
- | `multi_transform` | Chain linear pattern + polar pattern + mirror in one feature |
- | `create_inner_ridge` | Add a snap-fit ridge inside a rectangular hollow |
- | `create_snap_tabs` | Add snap tabs on a lid lip (pairs with ridge) |
- | `create_enclosure_lid` | Generate a snap-fit enclosure lid with correct dimensions |
- | `measure` | Volume, area, bounding box, distance, edge listing |
- | `describe_model` | Comprehensive geometry summary: dimensions, wall thickness, hollow/solid detection |
- | `list_faces` | List all faces with names, labels, normals, areas (optional filter) |
- | `list_edges` | List all edges with names, labels, lengths (optional filter) |
- | `list_documents` | List all open documents with object counts and active indicator |
- | `switch_document` | Switch the active FreeCAD document by name or label |
- | `get_document_state` | Inspect current objects and properties |
- | `create_variable_set` | Create a VarSet with named variables for parametric modeling |
- | `create_spreadsheet` | Create a Spreadsheet with named variables for parametric modeling |
- | `set_expression` | Bind object properties to expressions (parametric relationships) |
- | `modify_property` | Change any object property (supports relative: +10%, *1.5) |
- | `read_variable_set` | Read a VarSet's variables with types, units and expressions |
- | `edit_variable_set` | Change, add or remove VarSet variables (unit-aware) |
- | `read_spreadsheet` | Read spreadsheet cells: alias, contents, computed value |
- | `edit_spreadsheet` | Change, add or remove spreadsheet cells by alias or address |
- | `delete_object` | Delete an object (a Body with its features); refuses while other objects still use it |
- | `export_model` | Export to STL, STEP, or IGES |
- | `execute_code` | Fallback: run arbitrary Python |
- | `undo` | Undo last N operations, or undo until a named transaction |
- | `redo` | Redo previously undone operations |
- | `undo_history` | Show the undo/redo stack with named transactions |
- | `capture_viewport` | Save a screenshot of the 3D viewport |
- | `set_view` | Set camera orientation (front, top, isometric, etc.) |
- | `zoom_object` | Zoom the viewport to a specific object |
- | `use_skill` | Load a skill's instructions for complex tasks (enclosure, gear, etc.) |
- | `create_assembly` | Create an Assembly with grounded base part |
- | `add_assembly_joint` | Joint two parts (Fixed, Revolute, Cylindrical, Slider, Ball) |
- | `add_part_to_assembly` | Add a part to an existing assembly |
- | `select_geometry` | Interactive viewport picking for edges, faces, vertices |
- ### Connecting external MCP clients (Claude Code, Claude Desktop, …)
- 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.
- Three ways to start it, differing in who owns the FreeCAD process:
- - **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.
- ```bash
- claude mcp add --transport http freecad http://127.0.0.1:3000/mcp
- ```
- - **`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.
- ```bash
- /path/to/FreeCAD.AppImage /path/to/freecad-ai/mcp_server_http.py
- claude mcp add --transport http freecad http://127.0.0.1:3000/mcp
- ```
- - **`mcp_server_entry.py`** — STDIO, headless. The client spawns FreeCAD, which lives and dies with the session.
- ```bash
- claude mcp add freecad -- bash -c \
- 'exec 3>&1 1>&2 && /path/to/FreeCAD.AppImage -c /path/to/freecad-ai/mcp_server_entry.py'
- ```
- > **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>"`).
- Note that Claude Code loads MCP tools **at session start** — a server added mid-session won't appear until the next launch.
- 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.
- ### Skills
- Skills are reusable instruction sets stored in `<FreeCADAI dir>/skills/`. Invoke them by typing `/command` in the chat.
- **Built-in skills:**
- | Command | Description |
- |---------|-------------|
- | `/enclosure` | Parametric electronics enclosure with base, lid, screw posts |
- | `/thread-insert` | Heat-set thread insert holes (M2–M5) with correct dimensions |
- | `/gear` | Involute spur gear from module and tooth count |
- | `/fastener-hole` | Clearance, counterbore, or countersink holes (ISO dimensions) |
- | `/lattice` | Grid, honeycomb, or diagonal infill patterns |
- | `/skill-creator` | Create new skills interactively from the chat |
- **Creating custom skills:**
- You can create skills manually (see below) or use `/skill-creator` in the chat to have the AI walk you through it.
- ```
- <FreeCADAI dir>/skills/
- my-skill/
- SKILL.md # Instructions injected into the LLM prompt
- handler.py # Optional: Python handler with execute(args) function
- ```
- 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:
- ```
- /enclosure 100x60x40mm, 2mm walls, snap-fit lid
- ```
- If a `handler.py` exists with an `execute(args)` function, it runs directly instead of prompting the LLM.
- ### User Extension Tools
- 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:
- ```python
- import math
- def bolt_circle(diameter: float, count: int = 8, bolt_size: float = 6.5) -> str:
- """Create a bolt hole circle pattern on the XY plane."""
- import Part
- import FreeCAD as App
- # ... create geometry ...
- return f"Created {count} bolt holes on {diameter}mm PCD"
- ```
- **Requirements:**
- - Public functions (no `_` prefix) with type-hinted parameters
- - Supported types: `float`, `int`, `str`, `bool`
- - Return a `str` (success message) or `dict` with `output`/`data` keys
- - Docstring first line becomes the tool description
- 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.
- ### Thinking Mode
- Enable LLM reasoning in Settings (gear icon). Three levels:
- | Level | Description |
- |-------|-------------|
- | Off | Standard responses (default) |
- | On | LLM shows reasoning before responding |
- | Extended | Longer reasoning budget for complex tasks |
- 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.
- ### Session Resume
- 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.
- ### File Attachments
- Attach files to chat messages via the **Attach** button, drag-and-drop, or paste:
- | File type | Handling |
- |-----------|----------|
- | Images (PNG, JPG, etc.) | Sent as vision blocks (requires vision-capable model or MCP fallback) |
- | Text files (TXT, MD, CSV, PY, JSON, etc.) | Read as text and included in the message |
- | Binary files (PDF, DOCX, XLSX, etc.) | Converted via `file_attach` hook or MCP server |
- **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:
- 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.
- 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.
- To install the example PDF hook:
- ```bash
- # Replace <FreeCADAI dir> with your actual path — see "Configuration paths" above.
- # On FreeCAD 1.1+ Linux this is ~/.config/FreeCAD/v1-1/FreeCADAI/.
- cp -r docs/hooks/file-attach-example/ "<FreeCADAI dir>/hooks/file-attach/"
- # Requires: sudo apt install poppler-utils (provides pdftotext)
- ```
- Binary files are detected by magic bytes (PDF, ZIP/Office, PNG, JPEG, ELF, etc.) and null-byte content scanning.
- ### Referencing FreeCAD Objects
- Attach your current selection to the next message via the **Reference** button (above Attach):
- 1. Select geometry in the 3D view or model tree (Ctrl+click for several items).
- 2. Click **Reference** — an `@Name` token drops into the input box and a green chip appears in the attachment strip.
- 3. Type your question around the tokens (e.g. `why is @Pad.Face3 not parallel to @Pad.Face1?`) and send.
- 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.
- | Detail | Behaviour |
- |--------|-----------|
- | Whole objects | Click the object in the tree → `@Pad` |
- | Sub-elements | One chip per selected face/edge/vertex → `@Pad.Face3`, `@Pad.Edge7`, `@Pad.Vertex2` |
- | Snapshot timing | Descriptions are captured when you click the button — re-click after moving or editing geometry to refresh |
- | 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 |
- | Removing | The chip's **x** removes the context block; delete the `@token` from the input yourself |
- | Auto-clear | The strip clears after sending, like file attachments |
- ### AGENTS.md
- Place an `AGENTS.md` or `FREECAD_AI.md` file next to your `.FCStd` file to provide project-specific instructions:
- ```markdown
- # AGENTS.md
- This project uses metric units (mm).
- All parts should have 1mm fillets on external edges.
- Use PartDesign workflow (Body -> Sketch -> Pad), not Part primitives.
- ```
- **Search order:** document directory → parent directories (up to 3 levels) → `<FreeCADAI dir>/AGENTS.md`
- **Include directives** — split instructions across files:
- ```markdown
- <!-- include: materials.md -->
- <!-- include: conventions.md -->
- ```
- **Variable substitution** — use live document values:
- ```markdown
- Document: {{document_name}}
- Objects: {{object_count}}
- Active body: {{active_body}}
- ```
- ## Running macros & Dangerous mode
- The `run_macro` tool lets the assistant run an existing FreeCAD macro and read
- its console output directly — useful for AI-written test harnesses. By default
- it only runs a macro by **name** from FreeCAD's macro directory.
- ### ⚠️ Dangerous mode — read this
- Dangerous mode is an opt-in escape hatch that **removes the safety checks**
- FreeCAD AI normally applies to code it runs. Enable it from the chat panel
- (a confirmation dialog explains the risks; it resets to OFF every time FreeCAD
- restarts, and a red banner shows while it is active).
- While Dangerous mode is active:
- - **Arbitrary code/commands:** AI-run code can call shell commands, delete
- files, and do anything your user account is allowed to do.
- - **No timeout:** a macro containing an infinite loop will **freeze FreeCAD's
- main window with no way to recover — any unsaved work is lost.**
- - **No sandbox pre-check:** broken or destructive code runs straight against
- your live document.
- - **Endless loops:** if you also set the tool-loop count to `0` (endless), the
- AI can keep acting until you press **Stop**. There is no other limit, and it
- can consume a large number of tokens.
- **You are solely responsible for anything you run in this mode.** It is provided
- as a power-user convenience and is not tested against malicious or destructive
- input. Document integrity (undo rollback) is the only safeguard that remains on.
- To make Dangerous mode persist across restarts (not recommended), set
- `"dangerous_skip_safety": true` in your `config.json` by hand. The GUI will
- never write this for you.
- > Note: behavior described here is verified on Linux; the macro-directory
- > resolution uses FreeCAD's cross-platform API but is untested on macOS/Windows.
- ## Translations
- The UI supports internationalization via Qt's `.ts`/`.qm` translation system. Currently available:
- | Language | Status |
- |----------|--------|
- | English | Default (built-in) |
- | German | Complete |
- 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`.
- To re-extract strings after code changes:
- ```bash
- cd translations && bash update_translations.sh
- ```
- ## Project Structure
- ```
- freecad-ai/
- ├── Init.py # Non-GUI init
- ├── InitGui.py # Workbench registration + commands
- ├── package.xml # FreeCAD addon metadata
- ├── freecad_ai/
- │ ├── config.py # Settings (provider, API key, mode, tools, thinking)
- │ ├── i18n.py # Internationalization helpers
- │ ├── paths.py # Path utilities
- │ ├── llm/
- │ │ ├── client.py # HTTP client with SSE streaming + tool calling
- │ │ └── providers.py # Provider registry
- │ ├── tools/
- │ │ ├── registry.py # Tool abstractions + registry
- │ │ ├── freecad_tools.py # 39 FreeCAD tool handlers
- │ │ └── setup.py # Default registry factory
- │ ├── ui/
- │ │ ├── compat.py # PySide2/PySide6 shim
- │ │ ├── chat_widget.py # Chat dock + agentic tool loop
- │ │ ├── message_view.py # Message + tool call rendering
- │ │ ├── code_review_dialog.py
- │ │ └── settings_dialog.py
- │ ├── core/
- │ │ ├── active_document.py # GUI-aligned active document resolution
- │ │ ├── executor.py # Code execution with safety layers
- │ │ ├── context.py # Document state inspector
- │ │ ├── system_prompt.py # System prompt builder
- │ │ └── conversation.py # Conversation history + compacting + save/load
- │ ├── hooks/
- │ │ ├── __init__.py # Hooks package
- │ │ └── registry.py # Hook lifecycle event dispatch
- │ └── extensions/
- │ ├── agents_md.py # AGENTS.md loader (multi-location, includes, vars)
- │ ├── skills.py # Skills registry + execution
- │ └── user_tools.py # User extension tools (discover, validate, register)
- ├── translations/
- │ ├── freecad_ai_de.ts # German translation source
- │ └── update_translations.sh # Re-extract strings with pylupdate5
- ├── skills/ # Built-in skill definitions
- │ ├── enclosure/SKILL.md
- │ ├── gear/SKILL.md
- │ ├── fastener-hole/SKILL.md
- │ ├── thread-insert/SKILL.md
- │ ├── lattice/SKILL.md
- │ └── skill-creator/SKILL.md
- ├── hooks/ # Built-in hook examples
- │ └── log-tool-calls/
- └── resources/
- └── icons/
- └── freecad_ai.svg
- ```
- ## Contributing
- 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.
- ## License
- - **Code:** LGPL-2.1 — see [LICENSE-CODE](LICENSE-CODE)
- - **Icons:** CC0-1.0 (public domain) — see [LICENSE-ICON](LICENSE-ICON)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.