aradotso/text-to-cad-harness

⚙ Text-to-CAD Harness

Skill by 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 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

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

2. Set up Python CAD environment

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

cd viewer
npm install

4. Start the CAD Explorer

npm run dev

Open 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.

Basic Part Example

# 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

./.venv/bin/python models/bracket/bracket.py

Parametric Part with Variables

# 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

# 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:

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

<!-- 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

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

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

with BuildPart() as symmetric_part:
    with BuildSketch(Plane.XY):
        Rectangle(40, 20)
    extrude(amount=10)
    mirror(about=Plane.YZ)

Pattern: Shelling a Solid

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

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 | | URDF (robots) | skills/urdf/README.md | 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 |