agentcad — CAD tool for AI agents

You have access to agentcad, a CLI that turns build123d or CadQuery Python scripts into

3D geometry. All output is JSON. Every command returns "command" and "status" keys.

First-time setup

agentcad init --name <project_name>
agentcad --help   # Read this — it is your complete operational briefing

Core workflow

1. Write a script. No imports needed — build123d primitives,

show_object, and agentcad edit helpers are pre-injected by default.

show_object(result) is required.

1. Dry-run first to check metrics without consuming a version:

```bash

agentcad run script.py --output test --dry-run

```

Check volume, dimensions, is_valid in the response.

1. Run for real. Visual feedback is on by default:

```bash

agentcad run script.py --output label

```

Every successful run produces (paths in the JSON response):

• preview.png — 4-view composite (front, right, top, iso). Read this

to confirm the part looks right before iterating. One image, all 4 angles.

• diff.side_by_side — side-by-side PNG vs the most recent successful prior

version. Read this when iterating to see what your change did.

• diff.overlay — tinted (green prev, red this) overlay for subtle shifts.

Read only if side-by-side didn't resolve the question.

• viewer.html — interactive 3D viewer for the user (humans only; you can't

render HTML). Mention it to the user so they open it.

Pass --no-preview only for tight parametric sweeps where latency matters.

1. Show the user. After a successful build, open the interactive viewer:

```bash

agentcad view v1_label/viewer.html # or output.step / output.glb

```

Users expect to see the result in a browser. Do this every run, unprompted.

1. Inspect if invalid. If is_valid: false or geometry looks wrong:

```bash

agentcad inspect v1_label/output.step

```

1. Iterate. Fix the script, run with a new --output label. Use

agentcad diff 1 2 to compare versions.

Script writing rules

• show_object(result) is required — at least one call.
• These are pre-injected by default (no import needed):

build123d primitives like Box, Cylinder, Sphere, Plane, plus

show_object, load_step, pick_face, pick_edge, fillet_edges,

chamfer_edges, shell_faces, cut_pocket, boss, split_by_plane,

and replace_face.

• CadQuery remains supported. Use import cadquery as cq, initialize with

agentcad init --runtime cadquery, or pass --runtime cadquery.

• CadQuery helper paths operate on TopoDS_Shape. Bridge with .val().wrapped:

```python

import cadquery as cq

part = cq.Workplane('XY').box(10, 20, 5).val().wrapped

moved = translate(part, 50, 0, 0)

```

• To show helper output:

```python

import cadquery as cq

show_object(cq.Workplane('XY').newObject([cq.Shape.cast(topo_shape)]))

```

• For OCP internals (gp_Pnt, BRepPrimAPI, etc.), import manually.

Key commands

Debugging playbook

1. Check metrics first — volume and dimensions catch most issues.
2. Read preview.png — the 4-view composite. Fastest way to spot obvious problems.
3. Read diff.side_by_side if iterating — confirms your change did what you intended.
4. Negative volume? Wire winding is backwards (CW instead of CCW).
5. is_valid: false? Run agentcad inspect — check free_edge_count and shell status.
6. Hollow shape? free_edge_count > 0 means open shell.
7. Complex profiles (gears, splines)? Use subtractive construction — cut from

a blank cylinder/box instead of building up. See agentcad docs patterns.

Patterns

• Build at origin, then position: Create geometry at origin, use translate()

and rotate() to place it.

• Compound vs Union: makeCompound() for assemblies (parts stay separate),

.union() for boolean fuse into one solid.

• Parametric scripts: Top-level variable assignments become overridable via

--params. Use this for iteration.

• Named parts: show_object(shape, name="wheel", options={"color": "red"})

for per-part metrics and colored GLB export.