text-to-cad-harness

# ⚙ Text-to-CAD Harness > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. An open source harness that lets AI coding agents (Claude Code, Codex, Cursor, etc.) generate, export, and preview 3D CAD models from natural language descriptions. Models are written in Python using [build123d](https://github.com/gumyr/build123d) on top of OpenCascade (OCP), exported to STEP/STL/DXF/GLB/URDF, and inspected in a local React/Vite CAD Explorer viewer. --- ## How It Works ``` User prompt → Agent edits models/*.py → Python skill regenerates artifacts → Viewer previews geometry ``` - **`models/`** — Source-controlled Python CAD files (build123d scripts) - **`skills/cad/`** — Bundled CAD skill (STEP, STL, DXF, GLB, snapshots, `@cad[...]` references) - **`skills/urdf/`** — Bundled URDF skill (robot links, joints, validation) - **`viewer/`** — Local React/Vite CAD Explorer (no backend required) --- ## Installation ### 1. Clone the repo ```bash git clone https://github.com/earthtojake/text-to-cad.git cd text-to-cad ``` ### 2. Set up Python CAD environment ```bash python3.11 -m venv .venv ./.venv/bin/python -m pip install --upgrade pip ./.venv/bin/pip install -r requirements-cad.txt ``` > Requires Python 3.11+. The `requirements-cad.txt` pins build123d, OCP, and all geometry dependencies. ### 3. Install viewer dependencies ```bash cd viewer npm install ``` ### 4. Start the CAD Explorer ```bash npm run dev ``` Open [http://localhost:4178](http://localhost:4178) to browse generated models. --- ## Project Structure ``` text-to-cad/ ├── models/ # Your CAD source files live here │ └── my_part/ │ ├── part.py # build123d Python source │ ├── part.step # Generated STEP export │ ├── part.stl # Generated STL export │ └── part.glb # Generated GLB for viewer ├── skills/ │ ├── cad/ │ │ ├── SKILL.md # CAD skill documentation │ │ └── ... │ └── urdf/ │ ├── SKILL.md # URDF skill documentation │ └── ... ├── viewer/ # React/Vite local viewer │ ├── package.json │ └── src/ ├── requirements-cad.txt # Python dependencies └── assets/ ``` --- ## Writing CAD Models (build123d) All models live under `models/` as Python scripts using [build123d](https://github.com/gumyr/build123d). ### Basic Part Example ```python # models/bracket/bracket.py from build123d import * with BuildPart() as bracket: # Base plate with BuildSketch(Plane.XY): Rectangle(80, 60) extrude(amount=5) # Vertical wall with BuildSketch(Plane.XZ.offset(30)): Rectangle(80, 40) extrude(amount=5) # Fillets on all edges fillet(bracket.edges(), radius=2) # Mounting holes with BuildSketch(bracket.faces().filter_by(Axis.Z).sort_by(Axis.Z)[-1]): with Locations((-25, -15), (25, -15), (-25, 15), (25, 15)): Circle(3.5) extrude(amount=-5, mode=Mode.SUBTRACT) # Export export_step(bracket.part, "models/bracket/bracket.step") export_stl(bracket.part, "models/bracket/bracket.stl") ``` ### Running a Model to Generate Artifacts ```bash ./.venv/bin/python models/bracket/bracket.py ``` ### Parametric Part with Variables ```python # models/hex_spacer/hex_spacer.py from build123d import * # Parameters — agent edits these values OUTER_DIAMETER = 12.0 # mm, across-flats HEIGHT = 10.0 # mm HOLE_DIAMETER = 5.0 # mm (M5 clearance) WALL_THICKNESS = 2.0 # mm with BuildPart() as spacer: with BuildSketch(Plane.XY): RegularPolygon(radius=OUTER_DIAMETER / 2, side_count=6) extrude(amount=HEIGHT) with BuildSketch(Plane.XY): Circle(HOLE_DIAMETER / 2) extrude(amount=HEIGHT, mode=Mode.SUBTRACT) fillet(spacer.edges().filter_by(Axis.Z), radius=0.5) export_step(spacer.part, "models/hex_spacer/hex_spacer.step") export_stl(spacer.part, "models/hex_spacer/hex_spacer.stl") ``` ### Assembly Example ```python # models/assembly/assembly.py from build123d import * # Base with BuildPart() as base: with BuildSketch(Plane.XY): Rectangle(100, 80) extrude(amount=10) # Post with BuildPart() as post: with BuildSketch(Plane.XY): Circle(8) extrude(amount=50) # Combine into assembly assembly = Compound( children=[ base.part, post.part.move(Location((0, 0, 10))), ] ) export_step(assembly, "models/assembly/assembly.step") export_stl(assembly, "models/assembly/assembly.stl") ``` --- ## Exporting Formats From within any `models/*.py` script, use build123d export functions: ```python from build123d import * # STEP — full geometry, use for CAD interchange export_step(part, "models/my_part/my_part.step") # STL — mesh for 3D printing / simulation export_stl(part, "models/my_part/my_part.stl") # DXF — 2D drawing / laser cutting section = part.section(Plane.XY) export_dxf(section, "models/my_part/my_part.dxf") # GLB — viewer-compatible 3D web format export_gltf(part, "models/my_part/my_part.glb") ``` --- ## URDF Robot Descriptions The bundled URDF skill generates robot description files. See `skills/urdf/SKILL.md` for full docs. ### URDF Example Structure ``` models/my_robot/ ├── robot.py # build123d geometry for each link ├── robot.urdf # Generated URDF XML └── meshes/ ├── base.stl ├── arm.stl └── gripper.stl ``` ### Minimal URDF Output Pattern ```xml <!-- models/my_robot/robot.urdf (generated) --> <?xml version="1.0"?> <robot name="my_robot"> <link name="base_link"> <visual> <geometry> <mesh filename="meshes/base.stl"/> </geometry> </visual> </link> <link name="arm_link"> <visual> <geometry> <mesh filename="meshes/arm.stl"/> </geometry> </visual> </link> <joint name="base_to_arm" type="revolute"> <parent link="base_link"/> <child link="arm_link"/> <origin xyz="0 0 0.1" rpy="0 0 0"/> <axis xyz="0 0 1"/> <limit lower="-1.57" upper="1.57" effort="10" velocity="1"/> </joint> </robot> ``` --- ## CAD Explorer Viewer The local viewer reads exported files from `models/` and renders them in browser using WebAssembly (WASM). ### Viewer Commands ```bash cd viewer # Start dev server npm run dev # → http://localhost:4178 # Build for static hosting npm run build # Preview production build npm run preview ``` ### Viewer Features - Browse all models in `models/` directory - Inspect STEP/GLB geometry in 3D - Copy `@cad[...]` geometry references for agent follow-up edits - Quick snapshot renders for iteration review --- ## `@cad[...]` Geometry References After generating a model, the viewer provides stable `@cad[...]` handles. Paste these into your agent prompt to give it geometry-aware context for precise edits. ``` # Example agent follow-up using a reference @cad[models/bracket/bracket.step#face:top] — add a countersunk hole at center ``` --- ## Agent Workflow (Step-by-Step) ### Typical session with Claude Code or Codex ``` 1. User: "Create a parametric L-bracket with 4 mounting holes, 5mm thick" 2. Agent: creates models/l_bracket/l_bracket.py using build123d 3. Agent runs: ./.venv/bin/python models/l_bracket/l_bracket.py → generates l_bracket.step, l_bracket.stl, l_bracket.glb 4. User: opens http://localhost:4178, inspects the model 5. User copies @cad[...] reference from viewer 6. User: "Make the wall taller — @cad[models/l_bracket/l_bracket.step#face:wall]" 7. Agent edits WALL_HEIGHT parameter in l_bracket.py, reruns script 8. User commits models/l_bracket/ (source + artifacts together) ``` --- ## Common Patterns ### Pattern: Slot / Cutout ```python with BuildPart() as panel: with BuildSketch(Plane.XY): Rectangle(100, 60) extrude(amount=3) # Horizontal slot with BuildSketch(Plane.XY): SlottedHole(length=30, radius=3, rotation=0, align=Align.CENTER) extrude(amount=-3, mode=Mode.SUBTRACT) ``` ### Pattern: Mirrored Geometry ```python with BuildPart() as symmetric_part: with BuildSketch(Plane.XY): Rectangle(40, 20) extrude(amount=10) mirror(about=Plane.YZ) ``` ### Pattern: Shelling a Solid ```python with BuildPart() as box: Box(60, 40, 30) # Remove top face to shell into an open container shell(box.faces().sort_by(Axis.Z)[-1:], thickness=-2) ``` --- ## Troubleshooting | Problem | Fix | |---|---| | `ModuleNotFoundError: build123d` | Run with `./.venv/bin/python`, not system `python` | | Viewer shows no models | Check that `.glb` files exist in `models/` subdirectories | | `npm run dev` port conflict | Change port in `viewer/vite.config.*` | | STEP export fails silently | Ensure the part solid is valid — check for `part.is_valid` before export | | Python 3.12+ OCP errors | Pin to Python 3.11 as required by `requirements-cad.txt` | | Fillet fails on sharp geometry | Reduce fillet radius or apply after all cuts | ### Validate a Part Before Export ```python from build123d import * with BuildPart() as my_part: Box(50, 50, 20) # Check validity assert my_part.part.is_valid, "Part geometry is invalid — check for bad operations" export_step(my_part.part, "models/my_part/my_part.step") print(f"Exported: volume={my_part.part.volume:.2f} mm³") ``` --- ## Skills Reference | Skill | Docs | Standalone Repo | |---|---|---| | CAD (STEP/STL/DXF/GLB) | `skills/cad/README.md` | [earthtojake/cad-skill](https://github.com/earthtojake/cad-skill) | | URDF (robots) | `skills/urdf/README.md` | [earthtojake/urdf-skill](https://github.com/earthtojake/urdf-skill) | --- ## Key Dependencies | Package | Purpose | |---|---| | `build123d` | Pythonic 3D CAD modelling API | | `OCP` / OpenCascade | Geometry kernel (STEP, Boolean ops) | | `cadquery` | Underlying geometry utilities | | `React 18` + `Vite 7` | Viewer frontend | | `WASM` | In-browser geometry rendering |