freecad-ai
starsforks
How to install freecad-ai?
ghbalf/freecad-ai
$git clone https://github.com/ghbalf/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.
README.md
| 1 | # FreeCAD AI |
| 2 | |
| 3 | > **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. |
| 4 | |
| 5 | An AI-powered assistant workbench for FreeCAD that generates and executes Python code to create 3D models from natural language descriptions. |
| 6 | |
| 7 | ## Features |
| 8 | |
| 9 | - **Chat interface** — dock widget with streaming LLM responses |
| 10 | - **Plan / Act modes** — review code before execution (Plan) or auto-execute (Act) |
| 11 | - **Tool calling** — 50 structured FreeCAD operations (Act mode) for safer, more reliable modeling |
| 12 | - **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 |
| 13 | - **Skills** — reusable instruction sets the model invokes autonomously or via `/command` (enclosure, gear, fastener holes, sketch-from-image, etc.) |
| 14 | - **Skill optimizer** — automatically improve skill instructions via iterative test-evaluate-modify loop (`/optimize-skill`) |
| 15 | - **Hooks** — user-defined Python hooks for lifecycle events (block tools, modify input, log activity, convert file attachments) |
| 16 | - **User extension tools** — register your own Python functions as LLM-callable tools (`.py` or `.FCMacro`) |
| 17 | - **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 |
| 18 | - **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 |
| 19 | - **Image support** — viewport screenshots and images sent as vision blocks; auto-detected binary format rejection (PDF, ZIP, Office docs) |
| 20 | - **Thinking mode** — enable LLM reasoning for complex multi-step tasks (Off / On / Extended) |
| 21 | - **Context compacting** — automatically summarizes older messages when approaching context limits |
| 22 | - **Session resume** — save and load chat sessions to continue work later |
| 23 | - **20 LLM providers** — Anthropic, OpenAI, Ollama, Gemini, OpenRouter, Moonshot, DeepSeek, Qwen, Groq, Mistral, Together, Fireworks, xAI, Cohere, SambaNova, MiniMax, Llama, GitHub Models, HuggingFace, Zhipu, plus any OpenAI-compatible endpoint via Custom |
| 24 | - **Context-aware** — automatically includes document state (objects, properties, selection) in prompts |
| 25 | - **Error self-correction** — failed code is sent back to the LLM for automatic retry (up to 3 attempts) |
| 26 | - **AGENTS.md support** — project-level instructions with include directives and variable substitution |
| 27 | - **Dark mode** — chat widget automatically adapts to FreeCAD's light/dark theme (theme changes require FreeCAD restart) |
| 28 | - **Persistent dock layout** — the chat dock remembers its position, tab siblings (e.g. tabified with the Tasks panel), and floating geometry across FreeCAD sessions |
| 29 | - **Zero external dependencies** — uses only Python stdlib (`urllib`, `json`, `threading`, `ssl`) |
| 30 | |
| 31 | ## Requirements |
| 32 | |
| 33 | - FreeCAD 1.0+ (tested with 1.0.2 and 1.1.0) |
| 34 | - An LLM provider (local Ollama, or an API key for a cloud provider) |
| 35 | |
| 36 | ## Installation |
| 37 | |
| 38 | Clone or copy this repository into FreeCAD's Mod directory: |
| 39 | |
| 40 | ### Linux |
| 41 | |
| 42 | ```bash |
| 43 | ln -s /path/to/freecad-ai ~/.local/share/FreeCAD/Mod/freecad-ai |
| 44 | ``` |
| 45 | |
| 46 | ### macOS |
| 47 | |
| 48 | ```bash |
| 49 | ln -s /path/to/freecad-ai ~/Library/Application\ Support/FreeCAD/Mod/freecad-ai |
| 50 | ``` |
| 51 | |
| 52 | ### Windows |
| 53 | |
| 54 | ```powershell |
| 55 | # Run as Administrator |
| 56 | New-Item -ItemType SymbolicLink -Path "$env:APPDATA\FreeCAD\Mod\freecad-ai" -Target "C:\path\to\freecad-ai" |
| 57 | ``` |
| 58 | |
| 59 | Or manually copy the repository into `%APPDATA%\FreeCAD\Mod\freecad-ai`. |
| 60 | |
| 61 | > **FreeCAD 1.1+ uses version-scoped user dirs.** The `Mod` directory moved |
| 62 | > under a per-version folder, so on Linux the path is |
| 63 | > `~/.local/share/FreeCAD/v1.1/Mod/freecad-ai` (e.g. `v1.1`, `v1.2`), with the |
| 64 | > equivalent `…/FreeCAD/v1.1/Mod/` layout on macOS and |
People who liked this also viewed
6 picksType
- Figma-Context-MCPMCP server to provide Figma layout information to AI coding agents like CursorMCP ServersJul 2026
- sunnysideFigma-Context-MCPA comprehensive Model Context Protocol (MCP) server that bridges Figma designs with AI development workflows. It provides 30 specialized tools for extracting pixel-perfect code, assets, and component structures directly from Figma designs.MCP ServersApr 2026
- figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.MCP ServersJul 2026
- dcc-mcp-coreCore runtime and shared tooling for DCC-MCP: safe, skill-first MCP integration across Maya, Blender, Houdini, Photoshop, and custom DCC hosts.MCP ServersJul 2026
- godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.MCP ServersJul 2026
- freecad-mcpFreeCAD MCP(Model Context Protocol) serverMCP ServersJul 2026
