How to Generate 3D CAD Models with Claude Code Using Text-to-CAD on macOS

If you're an engineer or developer who's spent hours manually modeling parts in CAD software, text-to-CAD offers a radically different workflow. The open source text-to-cad harness lets you describe 3D geometry in plain language, and Claude Code generates the parametric CAD code for you. This guide walks you through setting it up on macOS and generating your first exportable models.

Why Text-to-CAD Changes Your Workflow

Traditional CAD requires clicking through menus and remembering software-specific syntax. With text-to-cad, you describe what you want ("a rectangular base 100mm × 50mm × 10mm with four mounting holes"), Claude Code writes the build123d Python code, and the harness renders it into STEP, STL, or 3MF files.

The key advantage: your CAD becomes source-controlled code. You can iterate, diff changes, and let AI agents refine geometry without losing history.

Prerequisites for macOS Setup

Before starting, ensure you have:

• Python 3.11 or higher (check with python3 --version)
• Node.js 16+ for CAD Explorer (check with node --version)
• pip package manager (bundled with Python 3.11+)
• Claude Code access through Claude.ai or Claude API
• Git for cloning the repository

Optionally, install Homebrew to simplify dependency management:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 1: Clone the Text-to-CAD Repository

Start by cloning the open source harness locally:

git clone https://github.com/earthtojake/text-to-cad.git
cd text-to-cad

This gives you the complete harness with bundled CAD, URDF, and robot-motion skills.

Step 2: Install Python Dependencies on macOS

The text-to-cad harness requires build123d and OpenCascade (OCP). On macOS, these are best installed via Homebrew to avoid compilation issues:

# Install build123d and dependencies via Homebrew
brew install build123d

# Install Python dependencies from the bundled skill
cd .agents/skills/cad
pip3 install -r requirements.txt

Key dependencies include:

• build123d – Pythonic CAD modeling library
• OCP (OpenCascade Python bindings) – 3D geometry kernel
• Pillow – Image rendering for review previews

If you encounter OpenCascade compilation errors, use the prebuilt wheel:

pip3 install --only-binary :all: OCP

Step 3: Set Up CAD Explorer (Node.js Frontend)

CAD Explorer is the local web interface for previewing your geometry. Install dependencies:

cd .agents/skills/cad/explorer
npm install

Start the development server:

npm run dev

This launches CAD Explorer on http://localhost:5173. Leave it running in a separate terminal.

Step 4: Generate Your First CAD Model with Claude Code

Instead of writing Python manually, use Claude Code to generate the model. Here's the workflow:

1. Open Claude.ai and start a new conversation
2. Paste this prompt, adjusting dimensions as needed:

I want to create a simple rectangular mounting bracket using the text-to-cad harness.
The bracket should be:
- Base: 100mm × 50mm × 10mm (length × width × height)
- Two mounting holes at opposite corners, 8mm diameter, centered 10mm from edges
- Rounded corners with 5mm radius

Generate Python code using build123d that I can save to `bracket.py` and run through the text-to-cad harness.

3. Claude Code will generate something like:

from build123d import *

# Rectangular mounting bracket
base = Box(100, 50, 10)

# Round the top edges
base = fillet(base.edges().filter(lambda e: e.center.z > 4), 5)

# Create mounting holes
hole_diameter = 8
hole_positions = [
    (10, 10, 5),   # Bottom-left
    (90, 40, 5)    # Top-right
]

for x, y, z in hole_positions:
    hole = Cylinder(radius=hole_diameter / 2, height=20, mode=Mode.SUBTRACT)
    hole = hole.locate(Location((x, y, z - 10)))
    base = base.cut(hole)

part = base

4. Save as bracket.py in your project directory
5. Run the harness to generate exports

Step 5: Export to STEP, STL, and 3MF Formats

The bundled CAD Skill handles exports automatically. Run the generation pipeline:

python3 .agents/skills/cad/generate.py bracket.py

This produces:

• bracket.step – STEP format (CAD-software compatible)
• bracket.stl – STL format (3D printing, meshes)
• bracket.3mf – 3D Manufacturing Format (colors, metadata)
• bracket_render.png – Preview image
• bracket_geometry.json – Topology data for CAD Explorer

Step 6: Preview Geometry in CAD Explorer

With CAD Explorer running on localhost:5173:

1. Upload or drag-and-drop the generated geometry files
2. Inspect the model in 3D with rotation, zoom, and pan
3. Verify dimensions before manufacturing or 3D printing
4. Copy @cad[...] references for Claude Code follow-up edits

The @cad[...] syntax lets you reference specific features in follow-up prompts. For example:

Using @cad[mounting_hole_left], increase its diameter to 10mm and chamfer the edges.

Common Pitfalls and Solutions

| Issue | Cause | Solution | |-------|-------|----------| | ModuleNotFoundError: No module named 'build123d' | build123d not installed | Run pip3 install build123d or use Homebrew | | OpenCascade compilation fails | Missing build tools | Install brew install cmake gcc | | CAD Explorer shows blank model | Geometry export failed | Check .agents/skills/cad/generate.py output for errors | | Claude Code generates invalid syntax | Outdated build123d API | Paste .agents/skills/cad/SKILL.md examples into prompt | | STEP export won't open in Fusion 360 | Units mismatch | Specify units in Python: set_units(Unit.MM) |

Iterating with Claude Code

Once you have a working model, Claude Code can refine it iteratively:

1. Ask for modifications in natural language: "Add a circular boss in the center, 20mm diameter and 5mm tall"
2. Claude Code edits the Python file and regenerates exports
3. Preview in CAD Explorer to verify
4. Commit to Git once satisfied: git add bracket.py && git commit -m "Add center boss"

This workflow is far faster than manual CAD for parametric designs, especially when you need to test multiple dimensions.

Export Formats Reference

• STEP (.step) – Opens in Fusion 360, SolidWorks, FreeCAD, Inventor. Best for CAD work.
• STL (.stl) – Standard for 3D printing. Loses parametric data but universal.
• 3MF (.3mf) – Modern 3D printing format with color and material support.
• DXF (.dxf) – 2D drawing format for laser cutting and CNC.
• GLB (.glb) – Optimized 3D model for web viewers.
• URDF (.urdf) – For robot simulation and ROS 2 (bundled robot skill).

Next Steps

1. Build a part library – Save successful bracket, enclosure, and mount designs as Python templates
2. Integrate with your workflow – Use generated STEP files directly in assembly drawings
3. Explore robot skills – The harness includes URDF generation for robotic arms and mechanisms
4. Contribute to the project – The text-to-cad harness is MIT-licensed and actively developed

Troubleshooting Claude Code Integration

If Claude Code isn't generating valid Python:

1. Paste the CAD Skill documentation from .agents/skills/cad/SKILL.md into your prompt
2. Provide a working example from the bundled demos
3. Specify build123d version: "Use build123d 0.5.0+ API"
4. Include unit context: "All dimensions in millimeters"

Claude Code works best when given concrete examples and clear constraints.

Conclusion

Text-to-CAD with Claude Code transforms parametric design from a manual grind into a conversational workflow. By running the harness locally on macOS, you keep full control over your models, integrate with Git, and leverage AI to handle the repetitive geometry coding.

Start with a simple bracket, iterate with Claude Code, and export production-ready STEP files. Your CAD is now code—version controlled, auditable, and AI-enhanced.